Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
133 changes: 132 additions & 1 deletion packages/cloud_firestore/cloud_firestore/lib/src/pipeline.dart
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,10 @@ class Pipeline {
/// ```
Future<PipelineSnapshot> execute({ExecuteOptions? options}) async {
final optionsMap = options != null
? {'indexMode': options.indexMode.name}
? {
'indexMode': options.indexMode.name,
if (options.atomic) 'atomic': true,
}
: null;
final platformSnapshot = await _delegate.execute(options: optionsMap);
return _convertPlatformSnapshot(platformSnapshot);
Expand Down Expand Up @@ -808,4 +811,132 @@ class Pipeline {
final stage = _WhereStage(expression);
return Pipeline._(_firestore, _delegate.addStage(stage.toMap()));
}

/// Deletes each input document at its `__name__` path.
///
/// This must be the last stage in the pipeline. A later stage, such as
/// [limit], is rejected by the backend.
///
/// Currently supported on web only. On other platforms, [execute] throws
/// [UnsupportedError].
///
/// Example:
/// ```dart
/// firestore
/// .pipeline()
/// .collection('books')
/// .where(Expression.field('genre').equal('Science Fiction'))
/// .delete();
/// ```
Pipeline delete() {

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Mark delete, update, insert, upsert and literals as web-only in their docs, or throw UnsupportedError on other platforms. Right now Android and Apple fail at execute with a generic "Unknown pipeline stage" error.

final stage = _DeleteStage();
return Pipeline._(_firestore, _delegate.addStage(stage.toMap()));
}

/// Updates each input document at its `__name__` path.
///
/// [transformedFields] are [AliasedExpression]s applied before the write.
/// A bare [Expression.field] is not a field name here; call [Expression.as].
/// When omitted, each input document is written back from its current
/// fields. This stage does not create missing documents.
///
/// This must be the last stage in the pipeline. A later stage, such as
/// [limit], is rejected by the backend.
///
/// Currently supported on web only. On other platforms, [execute] throws
/// [UnsupportedError].
///
/// Example:
/// ```dart
/// firestore.pipeline().collection('books').update([
/// Expression.field('rating').as('score'),
/// ]);
/// ```
Pipeline update([List<AliasedExpression> transformedFields = const []]) {
final stage = _UpdateStage(transformedFields);
return Pipeline._(_firestore, _delegate.addStage(stage.toMap()));
}

/// Inserts each input document.
///
/// The write fails if a document already exists at the target path.
///
/// The target path depends on [collectionPath] and [documentId]:
///
/// * Neither set: the input document's `__name__` path. The write fails
/// when that field is missing.
/// * [collectionPath] only: that collection. The input document id is
/// reused when `__name__` is present, and a new id is generated when it
/// is not.
/// * [documentId] only: the input document's parent collection, using the
/// id from [documentId]. The input document must have a `__name__` field.
/// * Both set: [collectionPath], using the id from [documentId].
///
/// [documentId] is evaluated for each document: a field path is
/// [Expression.field], and a fixed id is [Expression.constant].
///
/// This must be the last stage in the pipeline. A later stage, such as
/// [limit], is rejected by the backend.
///
/// Currently supported on web only. On other platforms, [execute] throws
/// [UnsupportedError].
Pipeline insert({String? collectionPath, Expression? documentId}) {
_checkCollectionPath(collectionPath);
final stage = _InsertStage(collectionPath, documentId);
return Pipeline._(_firestore, _delegate.addStage(stage.toMap()));
}

/// Inserts each input document, or replaces it when the target already exists.
///
/// An existing document is replaced entirely. Fields that are not in the
/// written document are removed. [additionalFields] are [AliasedExpression]s
/// merged onto each input document before the write. A bare
/// [Expression.field] is not a field name here; call [Expression.as].
///
/// The target path depends on [collectionPath] and [documentId]:
///
/// * Neither set: the input document's `__name__` path. The write fails
/// when that field is missing.
/// * [collectionPath] only: that collection. The input document id is
/// reused when `__name__` is present, and a new id is generated when it
/// is not.
/// * Both set: [collectionPath], using the id from [documentId].
///
/// [documentId] without [collectionPath] is rejected. Unlike [insert], an
/// id on its own is not a target. [documentId] is evaluated for each
/// document: a field path is [Expression.field], and a fixed id is
/// [Expression.constant].
///
/// This must be the last stage in the pipeline. A later stage, such as
/// [limit], is rejected by the backend.
///
/// Currently supported on web only. On other platforms, [execute] throws
/// [UnsupportedError].
Pipeline upsert({

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we document that write stages must be the final stage? .delete().limit(1) compiles, and the backend error doesn't explain the ordering rule.

String? collectionPath,
Expression? documentId,
List<AliasedExpression> additionalFields = const [],
}) {
if (documentId != null && collectionPath == null) {
throw ArgumentError(
'upsert() requires collectionPath when documentId is set.',
);
}
_checkCollectionPath(collectionPath);
final stage = _UpsertStage(collectionPath, documentId, additionalFields);
return Pipeline._(_firestore, _delegate.addStage(stage.toMap()));
}
}

void _checkCollectionPath(String? collectionPath) {

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Worth also rejecting even segment counts and leading or trailing slashes here. 'books/dune' currently passes and only fails on the backend.

if (collectionPath == null) {
return;
}
if (collectionPath.isEmpty) {
throw ArgumentError('A collection path must be a non-empty string.');
} else if (collectionPath.contains('//')) {
throw ArgumentError('A collection path must not contain "//".');
} else if (!isValidCollectionPath(collectionPath)) {
throw ArgumentError('A collection path must point to a valid collection.');
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,18 @@ enum IndexMode {

/// Options for executing a pipeline
class ExecuteOptions {
/// Which indexes the backend may use.
final IndexMode indexMode;

const ExecuteOptions({this.indexMode = IndexMode.recommended});
/// When true, data-manipulation stages commit in one transaction.
///
/// When false, each document write is applied on its own and a pipeline
/// can partially succeed. Some writes, such as [PipelineSource.literals]
/// followed by [Pipeline.upsert], are rejected unless this is true.
final bool atomic;

const ExecuteOptions({
this.indexMode = IndexMode.recommended,
this.atomic = false,
});
}
Original file line number Diff line number Diff line change
Expand Up @@ -64,4 +64,32 @@ class PipelineSource {
final delegate = _firestore._delegate.pipeline([stage.toMap()]);
return Pipeline._(_firestore, delegate);
}

/// Creates a pipeline from literal documents.
///
/// Each map is one document. A field value may be a plain value or an
/// [Expression]. Expressions are only supported as top-level fields, and an
/// aliased expression is rejected because the map key is the field name.
/// Nested maps and lists are plain values. A [Uint8List] is bytes; a list
/// of numbers stays an array.
///
/// Currently supported on web only. On other platforms, executing the
/// pipeline throws [UnsupportedError].
///
/// Example:
/// ```dart
/// firestore.pipeline().literals([
/// {'name': 'Alice', 'score': 50},
/// {'name': 'Bob', 'score': Expression.constant(70)},
/// ]);
/// ```
Pipeline literals(List<Map<String, Object?>> documents) {
if (documents.isEmpty) {
throw ArgumentError('Documents list must not be empty.');
}

final stage = _LiteralsPipelineStage(documents);
final delegate = _firestore._delegate.pipeline([stage.toMap()]);
return Pipeline._(_firestore, delegate);
}
}
168 changes: 168 additions & 0 deletions packages/cloud_firestore/cloud_firestore/lib/src/pipeline_stage.dart
Original file line number Diff line number Diff line change
Expand Up @@ -385,6 +385,174 @@ final class _UnionStage extends PipelineStage {
}
}

/// Stage that deletes each input document.
final class _DeleteStage extends PipelineStage {
@override
String get name => 'delete';

@override
Map<String, dynamic> toMap() {
return {'stage': name, 'args': <String, dynamic>{}};
}
}

/// Stage that updates each input document.
final class _UpdateStage extends PipelineStage {
final List<AliasedExpression> transformedFields;

_UpdateStage(this.transformedFields);

@override
String get name => 'update';

@override
Map<String, dynamic> toMap() {
return {
'stage': name,
'args': {
'expressions': transformedFields.map((field) => field.toMap()).toList(),
},
};
}
}

/// Stage that inserts each input document.
final class _InsertStage extends PipelineStage {
final String? collectionPath;
final Expression? documentId;

_InsertStage(this.collectionPath, this.documentId);

@override
String get name => 'insert';

@override
Map<String, dynamic> toMap() {
return {
'stage': name,
'args': _writeTargetArgs(collectionPath, documentId),
};
}
}

/// Stage that inserts or replaces each input document.
final class _UpsertStage extends PipelineStage {
final String? collectionPath;
final Expression? documentId;
final List<AliasedExpression> additionalFields;

_UpsertStage(this.collectionPath, this.documentId, this.additionalFields);

@override
String get name => 'upsert';

@override
Map<String, dynamic> toMap() {
final args = _writeTargetArgs(collectionPath, documentId);
if (additionalFields.isNotEmpty) {
args['additional_fields'] = additionalFields
.map((field) => field.toMap())
.toList();
}
return {'stage': name, 'args': args};
}
}

Map<String, dynamic> _writeTargetArgs(
String? collectionPath,
Expression? documentId,
) {
final args = <String, dynamic>{};
if (collectionPath != null) {
args['collection'] = collectionPath;
}
if (documentId != null) {
args['document_id'] = documentId.toMap();
}
return args;
}

/// Stage representing literal documents as a pipeline source.
final class _LiteralsPipelineStage extends PipelineStage {
final List<Map<String, Object?>> documents;

_LiteralsPipelineStage(this.documents);

@override
String get name => 'literals';

@override
Map<String, dynamic> toMap() {
return {
'stage': name,
'args': {'documents': documents.map(_encodeLiteralDocument).toList()},
};
}
}

Map<String, dynamic> _encodeLiteralDocument(Map<String, Object?> document) {
return document.map(
(key, value) => MapEntry(key, _encodeLiteralField(value)),
);
}

Map<String, dynamic> _encodeLiteralField(Object? value) {
if (value is AliasedExpression) {
throw ArgumentError(
'literals() does not accept an aliased expression. '
'The map key is the field name; pass the expression without .as().',
);
}
if (value is Expression) {

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should this reject AliasedExpression? A top-level .as() value passes this check, then toExpression on web throws unsupported-expression at execute.

return {'kind': 'expression', 'expression': value.toMap()};
}
if (value is DocumentReference) {
return {'kind': 'expression', 'expression': Constant(value).toMap()};
}
return {'kind': 'value', 'value': _encodeLiteralValue(value)};
}

Object? _encodeLiteralValue(Object? value) {
if (value is Expression) {
throw ArgumentError(
'literals() only supports Expression values as top-level document fields.',
);
}
if (value is DocumentReference) {
throw ArgumentError(
'literals() only supports DocumentReference values as top-level '
'document fields.',
);
}
if (value == null ||
value is String ||
value is num ||
value is bool ||
value is DateTime ||
value is Timestamp ||
value is GeoPoint ||
value is Blob ||
value is VectorValue) {
return value;
}
if (value is Uint8List) {
return value;
}
if (value is Map) {
return value.map(
(key, nested) => MapEntry(key.toString(), _encodeLiteralValue(nested)),
);
}
if (value is List) {
return value.map(_encodeLiteralValue).toList();
}
throw ArgumentError(
'literals() value must be null, String, num, bool, DateTime, Timestamp, '
'GeoPoint, Blob, VectorValue, List, Map, or a top-level Expression. '
'Got: ${value.runtimeType}',
);
}

/// Stage for filtering documents
final class _WhereStage extends PipelineStage {
final BooleanExpression expression;
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@ import 'pipeline_search_e2e.dart';
import 'pipeline_seed.dart';
import 'pipeline_select_e2e.dart';
import 'pipeline_unnest_union_e2e.dart';
import 'pipeline_writes_e2e.dart';

void main() {
final binding = IntegrationTestWidgetsFlutterBinding.ensureInitialized();
Expand Down Expand Up @@ -64,5 +65,6 @@ void main() {
runPipelineFindNearestTests();
runPipelineSearchTests();
runPipelineExpressionsTests();
runPipelineWriteTests();
});
}
Loading
Loading