Repository navigation
feat(firestore): add web pipeline writes and atomic execute #18954
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: main
Are you sure you want to change the base?
Changes from all commits
e242549
792d1f6
09e178b
6eadccf
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -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); | ||
|
|
@@ -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() { | ||
| 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({ | ||
|
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Can we document that write stages must be the final stage? |
||
| 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) { | ||
|
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Worth also rejecting even segment counts and leading or trailing slashes here. |
||
| 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 |
|---|---|---|
|
|
@@ -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) { | ||
|
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Should this reject |
||
| 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; | ||
|
|
||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Mark
delete,update,insert,upsertandliteralsas web-only in their docs, or throwUnsupportedErroron other platforms. Right now Android and Apple fail at execute with a generic "Unknown pipeline stage" error.