This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

The Pipeline class provides a flexible and expressive framework for building complex data transformation and query pipelines for Firestore.

A pipeline takes data sources, such as Firestore collections or collection groups, and applies a series of stages that are chained together. Each stage takes the output from the previous stage (or the data source) and produces an output for the next stage (or as the final output of the pipeline).

Expressions can be used within each stage to filter and transform data through the stage.

NOTE: The chained stages do not prescribe exactly how Firestore will execute the pipeline. Instead, Firestore only guarantees that the result is the same as if the chained stages were executed in order.

Usage Examples:

Signature:

exportdeclareclassPipeline

Methods

// Find the 10 most similar books based on the book description.constbookDescription="Lorem ipsum...";constqueryVector:number[]=...;// compute embedding of `bookDescription`firestore.pipeline().collection("books").findNearest({field:'embedding',vectorValue:queryVector,distanceMeasure:'euclidean',limit:10,// optionaldistanceField:'computedDistance'// optional});

||limit(limit) | |(Public Preview) Limits the maximum number of documents returned by previous stages tolimit.

This stage is particularly useful when you want to retrieve a controlled subset of data from a potentially large result set. It's often used for:

• **Pagination:** In combination with to retrieve specific pages of results.
• **Limiting Data Retrieval:** To prevent excessive data transfer and improve performance, especially when dealing with large collections.

Example: ||limit(options) | |(Public Preview) Limits the maximum number of documents returned by previous stages tolimit.

This stage is particularly useful when you want to retrieve a controlled subset of data from a potentially large result set. It's often used for:

• **Pagination:** In combination with to retrieve specific pages of results.
• **Limiting Data Retrieval:** To prevent excessive data transfer and improve performance, especially when dealing with large collections.

Example: ||offset(offset) | |(Public Preview) Skips the firstoffset number of documents from the results of previous stages.

This stage is useful for implementing pagination in your pipelines, allowing you to retrieve results in chunks. It is typically used in conjunction with to control the size of each page.

Example: ||offset(options) | |(Public Preview) Skips the firstoffset number of documents from the results of previous stages.

This stage is useful for implementing pagination in your pipelines, allowing you to retrieve results in chunks. It is typically used in conjunction with to control the size of each page.

Example: ||rawStage(name, params, options) | |(Public Preview) Adds a raw stage to the pipeline.

This method provides a flexible way to extend the pipeline's functionality by adding custom stages. Each raw stage is defined by a uniquename and a set ofparams that control its behavior.

Example (Assuming there is no 'where' stage available in SDK): ||removeFields(fieldValue, additionalFields) | |(Public Preview) Remove fields from outputs of previous stages.Example: ||removeFields(options) | |(Public Preview) Remove fields from outputs of previous stages.Example: ||replaceWith(fieldName) | |(Public Preview) Fully overwrites all fields in a document with those coming from a nested map.

This stage allows you to emit a map value as a document. Each key of the map becomes a field on the document that contains the corresponding value.

Example: ||replaceWith(expr) | |(Public Preview) Fully overwrites all fields in a document with those coming from a map.

This stage allows you to emit a map value as a document. Each key of the map becomes a field on the document that contains the corresponding value.

Example: ||replaceWith(options) | |(Public Preview) Fully overwrites all fields in a document with those coming from a map.

This stage allows you to emit a map value as a document. Each key of the map becomes a field on the document that contains the corresponding value.

Example: ||sample(documents) | |(Public Preview) Performs a pseudo-random sampling of the documents from the previous stage.

This stage will filter documents pseudo-randomly. The parameter specifies how number of documents to be returned.

Examples: ||sample(options) | |(Public Preview) Performs a pseudo-random sampling of the documents from the previous stage.

This stage will filter documents pseudo-randomly. The 'options' parameter specifies how sampling will be performed. SeeSampleStageOptions for more information. ||select(selection, additionalSelections) | |(Public Preview) Selects or creates a set of fields from the outputs of previous stages.

The selected fields are defined usingSelectable expressions, which can be:

• string : Name of an existing field
• Field: References an existing field.
• AliasedExpression: Represents the result of a function with an assigned alias name usingExpression.as()

If no selections are provided, the output of this stage is empty. UsePipeline.addFields() instead if only additions are desired.

Example: ||select(options) | |(Public Preview) Selects or creates a set of fields from the outputs of previous stages.

The selected fields are defined usingSelectable expressions, which can be:

• string: Name of an existing field
• Field: References an existing field.
• AliasedExpression: Represents the result of a function with an assigned alias name usingExpression.as()

If no selections are provided, the output of this stage is empty. UsePipeline.addFields() instead if only additions are desired.

Example: ||sort(ordering, additionalOrderings) | |(Public Preview) Sorts the documents from previous stages based on one or moreOrdering criteria.

This stage allows you to order the results of your pipeline. You can specify multipleOrdering instances to sort by multiple fields in ascending or descending order. If documents have the same value for a field used for sorting, the next specified ordering will be used. If all orderings result in equal comparison, the documents are considered equal and the order is unspecified.

Example: ||sort(options) | |(Public Preview) Sorts the documents from previous stages based on one or moreOrdering criteria.

This stage allows you to order the results of your pipeline. You can specify multipleOrdering instances to sort by multiple fields in ascending or descending order. If documents have the same value for a field used for sorting, the next specified ordering will be used. If all orderings result in equal comparison, the documents are considered equal and the order is unspecified.

Example: ||union(other) | |(Public Preview) Performs union of all documents from two pipelines, including duplicates.

This stage will pass through documents from previous stage, and also pass through documents from previous stage of theotherPipeline given in parameter. The order of documents emitted from this stage is undefined.

Example: ||union(options) | |(Public Preview) Performs union of all documents from two pipelines, including duplicates.

This stage will pass through documents from previous stage, and also pass through documents from previous stage of theotherPipeline given in parameter. The order of documents emitted from this stage is undefined.

Example: ||unnest(selectable, indexField) | |(Public Preview) Produces a document for each element in an input array.For each previous stage document, this stage will emit zero or more augmented documents. The input array specified by theselectable parameter, will emit an augmented document for each input array element. The input array element will augment the previous stage document by setting thealias field with the array element value.Whenselectable evaluates to a non-array value (ex: number, null, absent), then the stage becomes a no-op for the current input document, returning it as is with thealias field absent.No documents are emitted whenselectable evaluates to an empty array.Example: ||unnest(options) | |(Public Preview) Produces a document for each element in an input array.For each previous stage document, this stage will emit zero or more augmented documents. The input array specified by theselectable parameter, will emit an augmented document for each input array element. The input array element will augment the previous stage document by setting thealias field with the array element value.Whenselectable evaluates to a non-array value (ex: number, null, absent), then the stage becomes a no-op for the current input document, returning it as is with thealias field absent.No documents are emitted whenselectable evaluates to an empty array.Example: ||where(condition) | |(Public Preview) Filters the documents from previous stages to only include those matching the specifiedBooleanExpression.

This stage allows you to apply conditions to the data, similar to a "WHERE" clause in SQL. You can filter documents based on their field values, using implementations ofBooleanExpression, typically including but not limited to:

• field comparators:Expression.equal(),Expression.lessThan(),Expression.greaterThan(), etc.
• logical operators: , , , etc.
• advanced functions:Expression.regexMatch(),Expression.arrayContains(), etc.

Example: ||where(options) | |(Public Preview) Filters the documents from previous stages to only include those matching the specifiedBooleanExpression.

This stage allows you to apply conditions to the data, similar to a "WHERE" clause in SQL. You can filter documents based on their field values, using implementations ofBooleanExpression, typically including but not limited to:

• field comparators: , (less than),Expression.greaterThan(), etc.
• logical operators: , , , etc.
• advanced functions:Expression.regexMatch(),Expression.arrayContains(), etc.

Example: |

Pipeline.addFields()

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Adds new fields to outputs from previous stages.

This stage allows you to compute values on-the-fly based on existing data from previous stages or constants. You can use this to create new fields or overwrite existing ones (if there is name overlaps).

The added fields are defined usingSelectables, which can be:

• Field: References an existing document field. -Expression: Either a literal value (seeconstant()) or a computed value with an assigned alias usingExpression.as().

Example:

Signature:

addFields(field:Selectable,...additionalFields:Selectable[]):Pipeline;

Parameters

Returns:

Pipeline

A new Pipeline object with this stage appended to the stage list.

Example

firestore.pipeline().collection("books").addFields(field("rating").as("bookRating"),// Rename 'rating' to 'bookRating'add(5,field("quantity")).as("totalCost")// Calculate 'totalCost');

Pipeline.addFields()

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Adds new fields to outputs from previous stages.

This stage allows you to compute values on-the-fly based on existing data from previous stages or constants. You can use this to create new fields or overwrite existing ones (if there is name overlaps).

The added fields are defined usingSelectables, which can be:

• Field: References an existing document field. -Expression: Either a literal value (seeconstant()) or a computed value with an assigned alias usingExpression.as().

Example:

Signature:

addFields(options:AddFieldsStageOptions):Pipeline;

Parameters

Returns:

Pipeline

A new Pipeline object with this stage appended to the stage list.

Example

firestore.pipeline().collection("books").addFields(field("rating").as("bookRating"),// Rename 'rating' to 'bookRating'add(5,field("quantity")).as("totalCost")// Calculate 'totalCost');

Pipeline.aggregate()

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Performs aggregation operations on the documents from previous stages.

This stage allows you to calculate aggregate values over a set of documents. You define the aggregations to perform usingAliasedAggregate expressions which are typically results of callingExpression.as() onAggregateFunction instances.

Example:

Signature:

aggregate(accumulator:AliasedAggregate,...additionalAccumulators:AliasedAggregate[]):Pipeline;

Parameters

Returns:

Pipeline

A new Pipeline object with this stage appended to the stage list.

Example

// Calculate the average rating and the total number of booksfirestore.pipeline().collection("books").aggregate(field("rating").avg().as("averageRating"),countAll().as("totalBooks"));

Pipeline.aggregate()

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Performs optionally grouped aggregation operations on the documents from previous stages.

This stage allows you to calculate aggregate values over a set of documents, optionally grouped by one or more fields or functions. You can specify:

• \*\*Grouping Fields or Functions:\*\* One or more fields or functions to group the documents by. For each distinct combination of values in these fields, a separate group is created. If no grouping fields are provided, a single group containing all documents is used. Not specifying groups is the same as putting the entire inputs into one group.
• \*\*Accumulators:\*\* One or more accumulation operations to perform within each group. These are defined using [AliasedAggregate](./firestore_pipelines.aliasedaggregate.md#aliasedaggregate_class) expressions, which are typically created by calling [Expression.as()](./firestore_pipelines.expression.md#expressionas) on [AggregateFunction](./firestore_pipelines.aggregatefunction.md#aggregatefunction_class) instances. Each aggregation calculates a value (e.g., sum, average, count) based on the documents within its group.

Example:

Signature:

aggregate(options:AggregateStageOptions):Pipeline;

Parameters

Returns:

Pipeline

A newPipeline object with this stage appended to the stage list.

Example

// Calculate the average rating for each genre.firestore.pipeline().collection("books").aggregate({accumulators:[avg(field("rating")).as("avg_rating")]groups:["genre"]});

Pipeline.distinct()

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Returns a set of distinct values from the inputs to this stage.

This stage runs through the results from previous stages to include only results with unique combinations ofExpression values (Field,AliasedExpression, etc).

The parameters to this stage are defined usingSelectable expressions or strings:

• string: Name of an existing field -Field: References an existing document field. -AliasedExpression: Represents the result of a function with an assigned alias name usingExpression.as().

Example:

Signature:

distinct(group:string|Selectable,...additionalGroups:Array<string|Selectable>):Pipeline;

Parameters

Returns:

Pipeline

A newPipeline object with this stage appended to the stage list.

Example

// Get a list of unique author names in uppercase and genre combinations.firestore.pipeline().collection("books").distinct(toUppercase(field("author")).as("authorName"),field("genre"),"publishedAt").select("authorName");

Pipeline.distinct()

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Returns a set of distinct values from the inputs to this stage.

This stage runs through the results from previous stages to include only results with unique combinations ofExpression values (Field,AliasedExpression, etc).

The parameters to this stage are defined usingSelectable expressions or strings:

• string: Name of an existing field -Field: References an existing document field. -AliasedExpression: Represents the result of a function with an assigned alias name usingExpression.as().

Example:

Signature:

distinct(options:DistinctStageOptions):Pipeline;

Parameters

Returns:

Pipeline

A newPipeline object with this stage appended to the stage list.

Example

// Get a list of unique author names in uppercase and genre combinations.firestore.pipeline().collection("books").distinct(toUppercase(field("author")).as("authorName"),field("genre"),"publishedAt").select("authorName");

Pipeline.findNearest()

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Performs a vector proximity search on the documents from the previous stage, returning the K-nearest documents based on the specified queryvectorValue anddistanceMeasure. The returned documents will be sorted in order from nearest to furthest from the queryvectorValue.

Example:

// Find the 10 most similar books based on the book description.constbookDescription="Lorem ipsum...";constqueryVector:number[]=...;// compute embedding of `bookDescription`firestore.pipeline().collection("books").findNearest({field:'embedding',vectorValue:queryVector,distanceMeasure:'euclidean',limit:10,// optionaldistanceField:'computedDistance'// optional});

Signature:

findNearest(options:FindNearestStageOptions):Pipeline;

Parameters

Returns:

Pipeline

A newPipeline object with this stage appended to the stage list.

Pipeline.limit()

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Limits the maximum number of documents returned by previous stages tolimit.

This stage is particularly useful when you want to retrieve a controlled subset of data from a potentially large result set. It's often used for:

• \*\*Pagination:\*\* In combination with to retrieve specific pages of results.
• \*\*Limiting Data Retrieval:\*\* To prevent excessive data transfer and improve performance, especially when dealing with large collections.

Example:

Signature:

limit(limit:number):Pipeline;

Parameters

Returns:

Pipeline

A new Pipeline object with this stage appended to the stage list.

Example

// Limit the results to the top 10 highest-rated booksfirestore.pipeline().collection('books').sort(field('rating').descending()).limit(10);

Pipeline.limit()

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Limits the maximum number of documents returned by previous stages tolimit.

This stage is particularly useful when you want to retrieve a controlled subset of data from a potentially large result set. It's often used for:

• \*\*Pagination:\*\* In combination with to retrieve specific pages of results.
• \*\*Limiting Data Retrieval:\*\* To prevent excessive data transfer and improve performance, especially when dealing with large collections.

Example:

Signature:

limit(options:LimitStageOptions):Pipeline;

Parameters

Returns:

Pipeline

A new Pipeline object with this stage appended to the stage list.

Example

// Limit the results to the top 10 highest-rated booksfirestore.pipeline().collection('books').sort(field('rating').descending()).limit(10);

Pipeline.offset()

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Skips the firstoffset number of documents from the results of previous stages.

This stage is useful for implementing pagination in your pipelines, allowing you to retrieve results in chunks. It is typically used in conjunction with to control the size of each page.

Example:

Signature:

offset(offset:number):Pipeline;

Parameters

Returns:

Pipeline

A new Pipeline object with this stage appended to the stage list.

Example

// Retrieve the second page of 20 resultsfirestore.pipeline().collection('books').sort(field('published').descending()).offset(20)// Skip the first 20 results.limit(20);// Take the next 20 results

Pipeline.offset()

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Skips the firstoffset number of documents from the results of previous stages.

This stage is useful for implementing pagination in your pipelines, allowing you to retrieve results in chunks. It is typically used in conjunction with to control the size of each page.

Example:

Signature:

offset(options:OffsetStageOptions):Pipeline;

Parameters

Returns:

Pipeline

A new Pipeline object with this stage appended to the stage list.

Example

// Retrieve the second page of 20 resultsfirestore.pipeline().collection('books').sort(field('published').descending()).offset(20)// Skip the first 20 results.limit(20);// Take the next 20 results

Pipeline.rawStage()

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Adds a raw stage to the pipeline.

This method provides a flexible way to extend the pipeline's functionality by adding custom stages. Each raw stage is defined by a uniquename and a set ofparams that control its behavior.

Example (Assuming there is no 'where' stage available in SDK):

Signature:

rawStage(name:string,params:unknown[],options?:{[key:string]:Expression|unknown;}):Pipeline;

Parameters

Returns:

Pipeline

A newPipeline object with this stage appended to the stage list.

Example

// Assume we don't have a built-in 'where' stagefirestore.pipeline().collection('books').rawStage('where',[field('published').lt(1900)])// Custom 'where' stage.select('title','author');

Pipeline.removeFields()

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Remove fields from outputs of previous stages.

Example:

Signature:

removeFields(fieldValue:Field|string,...additionalFields:Array<Field|string>):Pipeline;

Parameters

Returns:

Pipeline

A new Pipeline object with this stage appended to the stage list.

Example

firestore.pipeline().collection('books')// removes field 'rating' and 'cost' from the previous stage outputs..removeFields(field('rating'),'cost');

Pipeline.removeFields()

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Remove fields from outputs of previous stages.

Example:

Signature:

removeFields(options:RemoveFieldsStageOptions):Pipeline;

Parameters

Returns:

Pipeline

A new Pipeline object with this stage appended to the stage list.

Example

firestore.pipeline().collection('books')// removes field 'rating' and 'cost' from the previous stage outputs..removeFields(field('rating'),'cost');

Pipeline.replaceWith()

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Fully overwrites all fields in a document with those coming from a nested map.

This stage allows you to emit a map value as a document. Each key of the map becomes a field on the document that contains the corresponding value.

Example:

Signature:

replaceWith(fieldName:string):Pipeline;

Parameters

Returns:

Pipeline

A newPipeline object with this stage appended to the stage list.

Example

// Input.// {//  'name': 'John Doe Jr.',//  'parents': {//    'father': 'John Doe Sr.',//    'mother': 'Jane Doe'//   }// }// Emit parents as document.firestore.pipeline().collection('people').replaceWith('parents');// Output// {//  'father': 'John Doe Sr.',//  'mother': 'Jane Doe'// }

Pipeline.replaceWith()

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Fully overwrites all fields in a document with those coming from a map.

This stage allows you to emit a map value as a document. Each key of the map becomes a field on the document that contains the corresponding value.

Example:

Signature:

replaceWith(expr:Expression):Pipeline;

Parameters

Returns:

Pipeline

A newPipeline object with this stage appended to the stage list.

Example

// Input.// {//  'name': 'John Doe Jr.',//  'parents': {//    'father': 'John Doe Sr.',//    'mother': 'Jane Doe'//   }// }// Emit parents as document.firestore.pipeline().collection('people').replaceWith(map({foo:'bar',info:{name:field('name')}}));// Output// {//  'father': 'John Doe Sr.',//  'mother': 'Jane Doe'// }

Pipeline.replaceWith()

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Fully overwrites all fields in a document with those coming from a map.

This stage allows you to emit a map value as a document. Each key of the map becomes a field on the document that contains the corresponding value.

Example:

Signature:

replaceWith(options:ReplaceWithStageOptions):Pipeline;

Parameters

Returns:

Pipeline

A newPipeline object with this stage appended to the stage list.

Example

// Input.// {//  'name': 'John Doe Jr.',//  'parents': {//    'father': 'John Doe Sr.',//    'mother': 'Jane Doe'//   }// }// Emit parents as document.firestore.pipeline().collection('people').replaceWith(map({foo:'bar',info:{name:field('name')}}));// Output// {//  'father': 'John Doe Sr.',//  'mother': 'Jane Doe'// }

Pipeline.sample()

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Performs a pseudo-random sampling of the documents from the previous stage.

This stage will filter documents pseudo-randomly. The parameter specifies how number of documents to be returned.

Examples:

Signature:

sample(documents:number):Pipeline;

Parameters

Returns:

Pipeline

A newPipeline object with this stage appended to the stage list.

Example

// Sample 25 books, if available.firestore.pipeline().collection('books').sample(25);

Pipeline.sample()

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Performs a pseudo-random sampling of the documents from the previous stage.

This stage will filter documents pseudo-randomly. The 'options' parameter specifies how sampling will be performed. SeeSampleStageOptions for more information.

Signature:

sample(options:SampleStageOptions):Pipeline;

Parameters

Returns:

Pipeline

A newPipeline object with this stage appended to the stage list.

Example

// Sample 10 books, if available.firestore.pipeline().collection("books").sample({documents:10});// Sample 50% of books.firestore.pipeline().collection("books").sample({percentage:0.5});

Pipeline.select()

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Selects or creates a set of fields from the outputs of previous stages.

The selected fields are defined usingSelectable expressions, which can be:

• `string` : Name of an existing field
• [Field](./firestore_pipelines.field.md#field_class): References an existing field.
• [AliasedExpression](./firestore_pipelines.aliasedexpression.md#aliasedexpression_class): Represents the result of a function with an assigned alias name using [Expression.as()](./firestore_pipelines.expression.md#expressionas)

If no selections are provided, the output of this stage is empty. UsePipeline.addFields() instead if only additions are desired.

Example:

Signature:

select(selection:Selectable|string,...additionalSelections:Array<Selectable|string>):Pipeline;

Parameters

Returns:

Pipeline

A new Pipeline object with this stage appended to the stage list.

Example

db.pipeline().collection("books").select("firstName",field("lastName"),field("address").toUppercase().as("upperAddress"),);

Pipeline.select()

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Selects or creates a set of fields from the outputs of previous stages.

The selected fields are defined usingSelectable expressions, which can be:

• `string`: Name of an existing field
• [Field](./firestore_pipelines.field.md#field_class): References an existing field.
• [AliasedExpression](./firestore_pipelines.aliasedexpression.md#aliasedexpression_class): Represents the result of a function with an assigned alias name using [Expression.as()](./firestore_pipelines.expression.md#expressionas)

If no selections are provided, the output of this stage is empty. UsePipeline.addFields() instead if only additions are desired.

Example:

Signature:

select(options:SelectStageOptions):Pipeline;

Parameters

Returns:

Pipeline

A new Pipeline object with this stage appended to the stage list.

Example

db.pipeline().collection("books").select("firstName",field("lastName"),field("address").toUppercase().as("upperAddress"),);

Pipeline.sort()

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Sorts the documents from previous stages based on one or moreOrdering criteria.

This stage allows you to order the results of your pipeline. You can specify multipleOrdering instances to sort by multiple fields in ascending or descending order. If documents have the same value for a field used for sorting, the next specified ordering will be used. If all orderings result in equal comparison, the documents are considered equal and the order is unspecified.

Example:

Signature:

sort(ordering:Ordering,...additionalOrderings:Ordering[]):Pipeline;

Parameters

Returns:

Pipeline

A newPipeline object with this stage appended to the stage list.

Example

// Sort books by rating in descending order, and then by title in ascending order for books// with the same ratingfirestore.pipeline().collection("books").sort(Ordering.of(field("rating")).descending(),Ordering.of(field("title"))// Ascending order is the default);

Pipeline.sort()

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Sorts the documents from previous stages based on one or moreOrdering criteria.

This stage allows you to order the results of your pipeline. You can specify multipleOrdering instances to sort by multiple fields in ascending or descending order. If documents have the same value for a field used for sorting, the next specified ordering will be used. If all orderings result in equal comparison, the documents are considered equal and the order is unspecified.

Example:

Signature:

sort(options:SortStageOptions):Pipeline;

Parameters

Returns:

Pipeline

A newPipeline object with this stage appended to the stage list.

Example

// Sort books by rating in descending order, and then by title in ascending order for books// with the same ratingfirestore.pipeline().collection("books").sort(Ordering.of(field("rating")).descending(),Ordering.of(field("title"))// Ascending order is the default);

Pipeline.union()

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Performs union of all documents from two pipelines, including duplicates.

This stage will pass through documents from previous stage, and also pass through documents from previous stage of theotherPipeline given in parameter. The order of documents emitted from this stage is undefined.

Example:

Signature:

union(other:Pipeline):Pipeline;

Parameters

Returns:

Pipeline

A newPipeline object with this stage appended to the stage list.

Example

// Emit documents from books collection and magazines collection.firestore.pipeline().collection('books').union(firestore.pipeline().collection('magazines'));

Pipeline.union()

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Performs union of all documents from two pipelines, including duplicates.

This stage will pass through documents from previous stage, and also pass through documents from previous stage of theotherPipeline given in parameter. The order of documents emitted from this stage is undefined.

Example:

Signature:

union(options:UnionStageOptions):Pipeline;

Parameters

Returns:

Pipeline

A newPipeline object with this stage appended to the stage list.

Example

// Emit documents from books collection and magazines collection.firestore.pipeline().collection('books').union(firestore.pipeline().collection('magazines'));

Pipeline.unnest()

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Produces a document for each element in an input array.

For each previous stage document, this stage will emit zero or more augmented documents. The input array specified by theselectable parameter, will emit an augmented document for each input array element. The input array element will augment the previous stage document by setting thealias field with the array element value.

Whenselectable evaluates to a non-array value (ex: number, null, absent), then the stage becomes a no-op for the current input document, returning it as is with thealias field absent.

No documents are emitted whenselectable evaluates to an empty array.

Example:

Signature:

unnest(selectable:Selectable,indexField?:string):Pipeline;

Parameters

Returns:

Pipeline

A newPipeline object with this stage appended to the stage list.

Example

// Input:// { "title": "The Hitchhiker's Guide to the Galaxy", "tags": [ "comedy", "space", "adventure" ], ... }// Emit a book document for each tag of the book.firestore.pipeline().collection("books").unnest(field("tags").as('tag'),'tagIndex');// Output:// { "title": "The Hitchhiker's Guide to the Galaxy", "tag": "comedy", "tagIndex": 0, ... }// { "title": "The Hitchhiker's Guide to the Galaxy", "tag": "space", "tagIndex": 1, ... }// { "title": "The Hitchhiker's Guide to the Galaxy", "tag": "adventure", "tagIndex": 2, ... }

Pipeline.unnest()

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Produces a document for each element in an input array.

For each previous stage document, this stage will emit zero or more augmented documents. The input array specified by theselectable parameter, will emit an augmented document for each input array element. The input array element will augment the previous stage document by setting thealias field with the array element value.

Whenselectable evaluates to a non-array value (ex: number, null, absent), then the stage becomes a no-op for the current input document, returning it as is with thealias field absent.

No documents are emitted whenselectable evaluates to an empty array.

Example:

Signature:

unnest(options:UnnestStageOptions):Pipeline;

Parameters

Returns:

Pipeline

A newPipeline object with this stage appended to the stage list.

Example

// Input:// { "title": "The Hitchhiker's Guide to the Galaxy", "tags": [ "comedy", "space", "adventure" ], ... }// Emit a book document for each tag of the book.firestore.pipeline().collection("books").unnest(field("tags").as('tag'),'tagIndex');// Output:// { "title": "The Hitchhiker's Guide to the Galaxy", "tag": "comedy", "tagIndex": 0, ... }// { "title": "The Hitchhiker's Guide to the Galaxy", "tag": "space", "tagIndex": 1, ... }// { "title": "The Hitchhiker's Guide to the Galaxy", "tag": "adventure", "tagIndex": 2, ... }

Pipeline.where()

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Filters the documents from previous stages to only include those matching the specifiedBooleanExpression.

This stage allows you to apply conditions to the data, similar to a "WHERE" clause in SQL. You can filter documents based on their field values, using implementations ofBooleanExpression, typically including but not limited to:

• field comparators: [Expression.equal()](./firestore_pipelines.expression.md#expressionequal), [Expression.lessThan()](./firestore_pipelines.expression.md#expressionlessthan), [Expression.greaterThan()](./firestore_pipelines.expression.md#expressiongreaterthan), etc.
• logical operators: , , , etc.
• advanced functions: [Expression.regexMatch()](./firestore_pipelines.expression.md#expressionregexmatch), [Expression.arrayContains()](./firestore_pipelines.expression.md#expressionarraycontains), etc.

Example:

Signature:

where(condition:BooleanExpression):Pipeline;

Parameters

Returns:

Pipeline

A new Pipeline object with this stage appended to the stage list.

Example

firestore.pipeline().collection("books").where(and(gt(field("rating"),4.0),// Filter for ratings greater than 4.0field("genre").eq("Science Fiction")// Equivalent to gt("genre", "Science Fiction")));

Pipeline.where()

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Filters the documents from previous stages to only include those matching the specifiedBooleanExpression.

This stage allows you to apply conditions to the data, similar to a "WHERE" clause in SQL. You can filter documents based on their field values, using implementations ofBooleanExpression, typically including but not limited to:

• field comparators: , (less than), [Expression.greaterThan()](./firestore_pipelines.expression.md#expressiongreaterthan), etc.
• logical operators: , , , etc.
• advanced functions: [Expression.regexMatch()](./firestore_pipelines.expression.md#expressionregexmatch), [Expression.arrayContains()](./firestore_pipelines.expression.md#expressionarraycontains), etc.

Example:

Signature:

where(options:WhereStageOptions):Pipeline;

Parameters

Returns:

Pipeline

A new Pipeline object with this stage appended to the stage list.

Example

firestore.pipeline().collection("books").where(and(gt(field("rating"),4.0),// Filter for ratings greater than 4.0field("genre").eq("Science Fiction")// Equivalent to gt("genre", "Science Fiction")));

Example

constdb:Firestore;// Assumes a valid firestore instance.// Example 1: Select specific fields and rename 'rating' to 'bookRating'constresults1=awaitexecute(db.pipeline().collection("books").select("title","author",field("rating").as("bookRating")));// Example 2: Filter documents where 'genre' is "Science Fiction" and 'published' is after 1950constresults2=awaitexecute(db.pipeline().collection("books").where(and(field("genre").eq("Science Fiction"),field("published").gt(1950))));// Example 3: Calculate the average rating of books published after 1980constresults3=awaitexecute(db.pipeline().collection("books").where(field("published").gt(1980)).aggregate(avg(field("rating")).as("averageRating")));