Skip to content
Draft
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
78 changes: 77 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,77 @@ class Pipeline {
final stage = _WhereStage(expression);
return Pipeline._(_firestore, _delegate.addStage(stage.toMap()));
}

/// Deletes each input document at its `__name__` path.
///
/// 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 aliased expressions applied before the write.
/// When omitted, each input document is written back from its current
/// fields. This stage does not create missing documents.
///
/// Example:
/// ```dart
/// firestore.pipeline().collection('books').update([
/// Expression.field('rating').as('score'),
/// ]);
/// ```
Pipeline update([List<Selectable> 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 is the input document's `__name__` when [collectionPath] and
/// [documentId] are both omitted. [collectionPath] writes into that
/// collection, reusing the input document id or generating one.
/// [documentId] is evaluated for each document: a field path is
/// [Expression.field], and a fixed id is [Expression.constant].
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 aliased expressions
/// merged onto each input document before the write. See [insert] for how
/// [collectionPath] and [documentId] choose the target path.
Pipeline upsert({
String? collectionPath,
Expression? documentId,
List<Selectable> additionalFields = const [],
}) {
_checkCollectionPath(collectionPath);
final stage = _UpsertStage(collectionPath, documentId, additionalFields);
return Pipeline._(_firestore, _delegate.addStage(stage.toMap()));
}
}

void _checkCollectionPath(String? collectionPath) {
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 "//".');
}
}
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,27 @@ 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.
/// Nested maps and lists are plain values.
///
/// 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);
}
}
159 changes: 159 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,165 @@ 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<Selectable> 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<Selectable> 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 Expression) {
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 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