addFields

public final @NonNullPipeline addFields(@NonNullSelectable field, @NonNullSelectable additionalFields)

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.

The added fields are defined usingSelectables, which can be:

• Field: References an existing document field.

• AliasedExpression: Represents the result of a expression with an assigned alias name using Expr.alias

Example:

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

aggregate

public final @NonNullPipeline aggregate(@NonNullAggregateStage aggregateStage)

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 Expressions: 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.

• AggregateFunctions: One or more accumulation operations to perform within each group. These are defined usingAliasedAggregate expressions, which are typically created by callingAggregateFunction.alias onAggregateFunction instances. Each aggregation calculates a value (e.g., sum, average, count) based on the documents within its group.

Example:

// Calculate the average rating for each genre.
firestore.pipeline().collection("books")
  .aggregate(
    Aggregate
      .withAccumulators(average("rating").as("avg_rating"))
      .withGroups("genre"));

aggregate

public final @NonNullPipeline aggregate(
    @NonNullAliasedAggregate accumulator,
    @NonNullAliasedAggregate additionalAccumulators
)

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 callingAggregateFunction.alias onAggregateFunction instances.

Example:

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

aggregate

public final @NonNullPipeline aggregate(
    @NonNullAggregateStage aggregateStage,
    @NonNullAggregateOptions options
)

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 Expressions: 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.

• AggregateFunctions: One or more accumulation operations to perform within each group. These are defined usingAliasedAggregate expressions, which are typically created by callingAggregateFunction.alias onAggregateFunction instances. Each aggregation calculates a value (e.g., sum, average, count) based on the documents within its group.

distinct

public final @NonNullPipeline distinct(@NonNullSelectable group, @NonNullObject additionalGroups)

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 of Expr valuesField,FunctionExpression, 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 using Expr.alias

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"))
    .select("authorName");

distinct

public final @NonNullPipeline distinct(@NonNullString groupField, @NonNullObject additionalGroups)

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 of Expr values (Field,FunctionExpression, 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 using Expr.alias

Example:

// Get a list of unique genres.
firestore.pipeline().collection("books")
    .distinct("genre");

execute

public final @NonNullTask<@NonNullPipeline.Snapshot> execute()

Executes this pipeline and returns the results as aTask ofSnapshot.

execute

public final @NonNullTask<@NonNullPipeline.Snapshot> execute(@NonNullPipeline.ExecuteOptions options)

Executes this pipeline and returns the results as aTask ofSnapshot.

findNearest

public final @NonNullPipeline findNearest(
    @NonNullField vectorField,
    @NonNull double[] vectorValue,
    @NonNullFindNearestStage.DistanceMeasure distanceMeasure
)

Performs a vector similarity search, ordering the result set by most similar to least similar, and returning the full set in the order of similarity.

findNearest

public final @NonNullPipeline findNearest(
    @NonNullString vectorField,
    @NonNull double[] vectorValue,
    @NonNullFindNearestStage.DistanceMeasure distanceMeasure
)

Performs a vector similarity search, ordering the result set by most similar to least similar, and returning the full set in the order of similarity.

findNearest

public final @NonNullPipeline findNearest(
    @NonNullString vectorField,
    @NonNullExpression vectorValue,
    @NonNullFindNearestStage.DistanceMeasure distanceMeasure,
    @NonNullFindNearestOptions options
)

Performs a vector similarity search, ordering the result set by most similar to least similar, and returning the first N documents (specified byFindNearestOptions.withLimit) in the result set.

Example:

// Find books with similar "topicVectors" to the given targetVector
firestore.pipeline().collection("books")
    .findNearest("topicVectors", targetVector, FindNearest.DistanceMeasure.COSINE,
       new FindNearestOptions()
         .withLimit(10)
         .withDistanceField("distance"));

limit

public final @NonNullPipeline limit(int limit)

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 withoffset 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 the results to the top 10 highest-rated books
firestore.pipeline().collection("books")
    .sort(field("rating").descending())
    .limit(10);

offset

public final @NonNullPipeline offset(int offset)

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 withlimit to control the size of each page.

Example:

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

rawStage

public final @NonNullPipeline rawStage(@NonNullRawStage rawStage)

Adds a raw stage to the pipeline by specifying the stage name as an argument. This does not offer any type safety on the stage params and requires the caller to know the order (and optionally names) of parameters accepted by the stage.

This method provides a way to call stages that are supported by the Firestore backend but that are not implemented in the SDK version being used.

removeFields

public final @NonNullPipeline removeFields(@NonNullField field, @NonNullField additionalFields)

Remove fields from outputs of previous stages.

Example:

firestore.pipeline().collection("books")
  .removeFields(
    field("rating"), field("cost")
  );

removeFields

public final @NonNullPipeline removeFields(@NonNullString field, @NonNullString additionalFields)

Remove fields from outputs of previous stages.

Example:

firestore.pipeline().collection("books")
  .removeFields(
    "rating", "cost"
  );

replaceWith

public final @NonNullPipeline replaceWith(@NonNullString field)

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:

// 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"
// }

replaceWith

public final @NonNullPipeline replaceWith(@NonNullExpression mapValue)

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:

// Input.
// {
//  "name": "John Doe Jr.",
//  "parents": {
//    "father": "John Doe Sr.",
//    "mother": "Jane Doe"
// }

// Emit parents as document.
firestore.pipeline().collection("people").replaceWith(field("parents"));

// Output
// {
//  "father": "John Doe Sr.",
//  "mother": "Jane Doe"
// }

sample

public final @NonNullPipeline sample(int documents)

Performs a pseudo-random sampling of the input documents.

Thedocuments parameter represents the target number of documents to produce and must be a non-negative integer value. If the previous stage produces less than size documents, the entire previous results are returned. If the previous stage produces more than size, this outputs a sample of exactly size entries where any sample is equally likely.

Example:

// Sample 10 books, if available.
firestore.pipeline().collection("books")
    .sample(10);

sample

public final @NonNullPipeline sample(@NonNullSampleStage sample)

Performs a pseudo-random sampling of the input documents.

Examples:

// Sample 10 books, if available.
firestore.pipeline().collection("books")
    .sample(Sample.withDocLimit(10));

// Sample 50% of books.
firestore.pipeline().collection("books")
    .sample(Sample.withPercentage(0.5));

select

public final @NonNullPipeline select(@NonNullString fieldName, @NonNullObject additionalSelections)

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: Reference to an existing field.

• AliasedExpression: Represents the result of a expression with an assigned alias name using Expr.alias

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

Example:

firestore.collection("books")
.select("name","address");

// The above is a shorthand of this:
firestore.pipeline().collection("books")
   .select(field("name"), field("address"));

select

public final @NonNullPipeline select(@NonNullSelectable selection, @NonNullObject additionalSelections)

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

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

• String: Name of an existing field

• Field: Reference to an existing field.

• AliasedExpression: Represents the result of a expression with an assigned alias name using Expr.alias

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

Example:

firestore.pipeline().collection("books")
.select(
field("name"),
field("address").toUppercase().as("upperAddress"),
);

sort

public final @NonNullPipeline sort(@NonNullOrdering order, @NonNullOrdering additionalOrders)

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 books by rating in descending order, and then by title in ascending order for books with the same rating
firestore.pipeline().collection("books")
    .sort(
        Ordering.of("rating").descending(),
        Ordering.of("title")  // Ascending order is the default
    );

union

public final @NonNullPipeline union(@NonNullPipeline other)

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 theother Pipeline given in parameter. The order of documents emitted from this stage is undefined.

Example:

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

unnest

public final @NonNullPipeline unnest(@NonNullSelectable arrayWithAlias)

Takes a specified array from the input documents and outputs a document for each element with the element stored in a field with name specified by the alias.

For each document emitted by the prior stage, this stage will emit zero or more augmented documents. The input array is found in parameterarrayWithAlias, which can be an Expr with an alias specified via Expr.alias, or aField that can also have alias specified. For each element of the input array, an augmented document will be produced. The element of input array will be stored in a field with name specified by the alias of thearrayWithAlias parameter. If thearrayWithAlias is aField with no alias, then the original array field will be replaced with the individual element.

unnest

public final @NonNullPipeline unnest(@NonNullUnnestStage unnestStage)

Takes a specified array from the input documents and outputs a document for each element with the element stored in a field with name specified by the alias.

For each document emitted by the prior stage, this stage will emit zero or more augmented documents. The input array specified in theunnestStage parameter will for each element of the input array produce an augmented document. The element of the input array will be stored in a field with a name specified by theunnestStage parameter.

Optionally, an index field can also be added to emitted documents. SeeUnnestStage for further information.

unnest

public final @NonNullPipeline unnest(@NonNullString arrayField, @NonNullString alias)

Takes a specified array from the input documents and outputs a document for each element with the element stored in a field with name specified by the alias.

For each document emitted by the prior stage, this stage will emit zero or more augmented documents. The input array found in the previous stage document field specified by thearrayField parameter, will for each element of the input array produce an augmented document. The element of the input array will be stored in a field with name specified byalias parameter on the augmented document.

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("tags", "tag");

// Output:
// { "title": "The Hitchhiker's Guide to the Galaxy", "tag": "comedy", ... }
// { "title": "The Hitchhiker's Guide to the Galaxy", "tag": "space", ... }
// { "title": "The Hitchhiker's Guide to the Galaxy", "tag": "adventure", ... }

unnest

public final @NonNullPipeline unnest(@NonNullSelectable arrayWithAlias, @NonNullUnnestOptions options)

Takes a specified array from the input documents and outputs a document for each element with the element stored in a field with name specified by the alias.

For each document emitted by the prior stage, this stage will emit zero or more augmented documents. The input array is found in parameterarrayWithAlias, which can be an Expr with an alias specified via Expr.alias, or aField that can also have alias specified. For each element of the input array, an augmented document will be produced. The element of input array will be stored in a field with name specified by the alias of thearrayWithAlias parameter. If thearrayWithAlias is aField with no alias, then the original array field will be replaced with the individual element.

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("tags", "tag", new UnnestOptions().withIndexField("tagIndex"));

// Output:
// { "title": "The Hitchhiker's Guide to the Galaxy", "tagIndex": 0, "tag": "comedy", ... }
// { "title": "The Hitchhiker's Guide to the Galaxy", "tagIndex": 1, "tag": "space", ... }
// { "title": "The Hitchhiker's Guide to the Galaxy", "tagIndex": 2, "tag": "adventure", ... }

where

public final @NonNullPipeline where(@NonNullBooleanExpression condition)

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: Expr.equal, Expr.lessThan, Expr.greaterThan, etc.

• logical operators: Expr.and, Expr.or, Expr.not, etc.

• advanced functions: Expr.regexMatch, Expr.arrayContains, etc.

Example:

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