feat(firestore): support insert, upsert, and literals stages in pipelines - #10200
feat(firestore): support insert, upsert, and literals stages in pipelines#10200wu-hui wants to merge 13 commits into
Conversation
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces new DML pipeline stages (delete, update, insert, upsert) and a new literals source stage to Firestore pipelines, along with support for atomic execution via PipelineExecuteOptions. Feedback focuses on marking the literals method as @beta to resolve API extractor warnings, restoring the detailed documentation for execute(), and refactoring duplicated collection path normalization logic in the Insert and Upsert constructors.
| * Set the pipeline's source to in-memory literal document objects. | ||
| * | ||
| * @param document - A document object (key-value map). | ||
| * @param additionalDocuments - Optional additional document objects. | ||
| */ | ||
| literals( | ||
| document: Record<string, unknown>, | ||
| ...additionalDocuments: Array<Record<string, unknown>> | ||
| ): PipelineType; | ||
|
|
||
| /** | ||
| * Set the pipeline's source to in-memory literal document objects with options. | ||
| * | ||
| * @param options - Options containing the documents array. | ||
| */ | ||
| literals(options: LiteralsStageOptions): PipelineType; |
There was a problem hiding this comment.
The new literals method and its overloads should be marked as @beta to be consistent with other new pipeline features like insert and upsert. This will also resolve the ae-incompatible-release-tags warning in the generated API report.
/**
* @beta
* Set the pipeline's source to in-memory literal document objects.
*
* @param document - A document object (key-value map).
* @param additionalDocuments - Optional additional document objects.
*/
literals(
document: Record<string, unknown>,
...additionalDocuments: Array<Record<string, unknown>>
): PipelineType;
/**
* @beta
* Set the pipeline's source to in-memory literal document objects with options.
*
* @param options - Options containing the documents array.
*/
literals(options: LiteralsStageOptions): PipelineType;| /** | ||
| * Executes this pipeline and returns a Promise to represent the asynchronous operation. | ||
| * | ||
| * The returned Promise can be used to track the progress of the pipeline execution | ||
| * and retrieve the results (or handle any errors) asynchronously. | ||
| * | ||
| * The pipeline results are returned as a {@link @firebase/firestore/pipelines#PipelineSnapshot} that contains | ||
| * a list of {@link @firebase/firestore/pipelines#PipelineResult} objects. Each {@link @firebase/firestore/pipelines#PipelineResult} typically | ||
| * represents a single key/value map that has passed through all the | ||
| * stages of the pipeline, however this might differ depending on the stages involved in the | ||
| * pipeline. For example: | ||
| * | ||
| * <ul> | ||
| * <li>If there are no stages or only transformation stages, each {@link @firebase/firestore/pipelines#PipelineResult} | ||
| * represents a single document.</li> | ||
| * <li>If there is an aggregation, only a single {@link @firebase/firestore/pipelines#PipelineResult} is returned, | ||
| * representing the aggregated results over the entire dataset .</li> | ||
| * <li>If there is an aggregation stage with grouping, each {@link @firebase/firestore/pipelines#PipelineResult} represents a | ||
| * distinct group and its associated aggregated values.</li> | ||
| * </ul> | ||
| * | ||
| * @example | ||
| * ```typescript | ||
| * const snapshot: PipelineSnapshot = await execute(firestore.pipeline().collection("books") | ||
| * .where(gt(field("rating"), 4.5)) | ||
| * .select("title", "author", "rating")); | ||
| * | ||
| * const results: PipelineResults = snapshot.results; | ||
| * ``` | ||
| * | ||
| * @param pipeline - The pipeline to execute. | ||
| * @returns A Promise representing the asynchronous pipeline execution. | ||
| */ |
There was a problem hiding this comment.
The detailed documentation for the execute() function has been removed as part of adding the new overload. This documentation was very helpful for users to understand what to expect from the pipeline execution results. It would be beneficial to restore it, perhaps on the first overload or as a general comment for the function.
| this.collectionPath = typeof collection === 'string' ? collection : collection.path; | ||
| if (!this.collectionPath.startsWith('/')) { | ||
| this.collectionPath = '/' + this.collectionPath; | ||
| } |
There was a problem hiding this comment.
The logic for normalizing the collection path is duplicated in the Insert and Upsert stage constructors (lines 1109-1112). This could be extracted into a shared private helper function to reduce code duplication and improve maintainability.
66d2bc5 to
ce1aa81
Compare
…age.ts TAG=agy CONV=74d82eb4-f542-4abb-af06-5c096595ec83
TAG=agy CONV=74d82eb4-f542-4abb-af06-5c096595ec83
…age.ts TAG=agy CONV=74d82eb4-f542-4abb-af06-5c096595ec83
…rs in stage.ts TAG=agy CONV=74d82eb4-f542-4abb-af06-5c096595ec83
TAG=agy CONV=74d82eb4-f542-4abb-af06-5c096595ec83
…ion tests TAG=agy CONV=74d82eb4-f542-4abb-af06-5c096595ec83
TAG=agy CONV=74d82eb4-f542-4abb-af06-5c096595ec83
Added InsertStageOptions and UpsertStageOptions types, Insert and Upsert stage classes, and fluent .insert() and .upsert() methods on Pipeline. Also updated ExecutePipelineRequest serialization to correctly pass newTransaction when atomic execution is requested. TAG=agy CONV=74d82eb4-f542-4abb-af06-5c096595ec83
Implemented LiteralsStageOptions, LiteralsSource stage, and .literals() method overloads (vararg and options object) on PipelineSource. Enables in-memory document pipelines and non-transactional DML writes when using literal document sources. TAG=agy CONV=74d82eb4-f542-4abb-af06-5c096595ec83
…st transaction fields Added RequestOptions to common.proto and auto_commit_transaction/request_options fields to ExecutePipelineRequest in firestore.proto. Regenerated protos.json via compile.sh and updated firestore_proto_api.ts interfaces. TAG=agy CONV=74d82eb4-f542-4abb-af06-5c096595ec83
…nd tests TAG=agy CONV=74d82eb4-f542-4abb-af06-5c096595ec83
… files TAG=agy CONV=74d82eb4-f542-4abb-af06-5c096595ec83
ce1aa81 to
1d4185b
Compare
1 participant
Implements Insert, Upsert, and LiteralsSource pipeline stages and autoCommitTransaction transaction proto serialization.
TAG=agy
CONV=74d82eb4-f542-4abb-af06-5c096595ec83