firebase-firestore/com.google.firebase.firestore/Pipeline

Pipeline

A pipeline: a source (from FirebaseFirestore.pipeline) followed by stages that filter, transform and aggregate the documents, run by execute. Immutable: each stage method returns a new pipeline with the stage appended.

On Apple platforms, execute with ExecuteOptions that set options other than ExecuteOptions.withAtomic, and source stages with options other than the forced index (CollectionHints.withForceIndex), fail: the iOS SDK's pipeline bridge has no way to pass them.

Types

ExecuteOptions

class ExecuteOptions : AbstractOptions<Pipeline.ExecuteOptions>

The options of an execution; besides the typed ones, with sets an option by its backend name. The iOS SDK takes only withAtomic: on Apple platforms, executing with any other fails with UnsupportedOperationException.

Snapshot

class Snapshot : Iterable<PipelineResult>

The results of an execution, in order, and when the backend computed them.

Functions

addFields

fun addFields(field: Selectable, vararg additionalFields: Selectable): Pipeline

Adds field and additionalFields to the documents.

aggregate

fun aggregate(aggregateStage: AggregateStage): Pipeline

Appends the aggregation aggregateStage.

fun aggregate(aggregateStage: AggregateStage, options: AggregateOptions): Pipeline

Appends the aggregation aggregateStage with options.

fun aggregate(accumulator: AliasedAggregate, vararg additionalAccumulators: AliasedAggregate): Pipeline

Replaces the documents with one document holding accumulator and additionalAccumulators.

define

fun define(aliasedExpression: AliasedExpression, vararg additionalExpressions: AliasedExpression): Pipeline

Binds aliasedExpression and additionalExpressions to variables, by their aliases, for the following stages.

delete

fun delete(): Pipeline

Deletes each document of the previous stages from the database.

distinct

fun distinct(group: Selectable, vararg additionalGroups: Any): Pipeline

Keeps one document per distinct value of group and additionalGroups (selectables or field names).

fun distinct(groupField: String, vararg additionalGroups: Any): Pipeline

Keeps one document per distinct value of the field groupField and additionalGroups (selectables or field names).

execute

fun execute(): Task<Pipeline.Snapshot>

Runs the pipeline and completes with its results.

fun execute(options: Pipeline.ExecuteOptions): Task<Pipeline.Snapshot>

Runs the pipeline with options and completes with its results; on Apple platforms options are not supported (see ExecuteOptions).

findNearest

fun findNearest(vectorField: Field, vectorValue: DoubleArray, distanceMeasure: FindNearestStage.DistanceMeasure): Pipeline

fun findNearest(vectorField: String, vectorValue: DoubleArray, distanceMeasure: FindNearestStage.DistanceMeasure): Pipeline

Keeps the documents whose vector field vectorField is nearest to vectorValue by distanceMeasure.

fun findNearest(vectorField: String, vectorValue: Expression, distanceMeasure: FindNearestStage.DistanceMeasure, options: FindNearestOptions): Pipeline

Keeps the documents whose vector field vectorField is nearest to vectorValue by distanceMeasure, with options.

insert

fun insert(): Pipeline

Inserts each document of the previous stages at the path in its __name__ field; fails if the document exists.

fun insert(collection: CollectionReference): Pipeline

Inserts each document of the previous stages into collection, with its own id or a new one.

fun insert(documentIdExpression: Expression): Pipeline

Inserts each document of the previous stages into its own collection, with the id documentIdExpression evaluates to.

fun insert(collectionPath: String): Pipeline

Inserts each document of the previous stages into the collection at collectionPath, with its own id or a new one.

fun insert(collection: CollectionReference, documentIdExpression: Expression): Pipeline

Inserts each document of the previous stages into collection, with the id documentIdExpression evaluates to.

fun insert(collectionPath: String, documentIdExpression: Expression): Pipeline

Inserts each document of the previous stages into the collection at collectionPath, with the id documentIdExpression evaluates to.

limit

fun limit(limit: Int): Pipeline

Keeps the first limit documents.

offset

fun offset(offset: Int): Pipeline

Skips the first offset documents.

rawStage

fun rawStage(rawStage: RawStage): Pipeline

Appends rawStage, a stage by its backend name.

removeFields

fun removeFields(field: Field, vararg additionalFields: Field): Pipeline

Removes field and additionalFields from the documents.

fun removeFields(field: String, vararg additionalFields: String): Pipeline

Removes the fields field and additionalFields from the documents.

replaceWith

fun replaceWith(mapValue: Expression): Pipeline

Replaces each document with the map mapValue.

fun replaceWith(field: String): Pipeline

Replaces each document with the map in its field field.

sample

fun sample(sample: SampleStage): Pipeline

Keeps the random sample sample.

fun sample(documents: Int): Pipeline

Keeps a random sample of at most documents documents.

fun search(searchStage: SearchStage): Pipeline

Appends the search searchStage. Beta in the Android SDK.

select

fun select(selection: Selectable, vararg additionalSelections: Any): Pipeline

Replaces the documents with selection and additionalSelections (selectables or field names).

fun select(fieldName: String, vararg additionalSelections: Any): Pipeline

Replaces the documents with the field fieldName and additionalSelections (selectables or field names).

sort

fun sort(order: Ordering, vararg additionalOrders: Ordering): Pipeline

Sorts the documents by order, then by additionalOrders.

toArrayExpression

fun toArrayExpression(): Expression

This pipeline as a subquery evaluating to the array of its results.

toScalarExpression

fun toScalarExpression(): Expression

This pipeline as a subquery evaluating to its single result.

union

fun union(other: Pipeline): Pipeline

Adds the documents of other.

unnest

fun unnest(arrayWithAlias: Selectable): Pipeline

One document per element of the array arrayWithAlias, the element under its alias.

fun unnest(unnestStage: UnnestStage): Pipeline

Appends unnestStage.

fun unnest(arrayWithAlias: Selectable, options: UnnestOptions): Pipeline

One document per element of the array arrayWithAlias, the element under its alias, with options.

fun unnest(arrayField: String, alias: String): Pipeline

One document per element of the array field arrayField, the element under alias.

update

fun update(vararg fields: Selectable): Pipeline

Writes each document of the previous stages back to its path, with fields set under their aliases; the stored document is replaced, so fields earlier stages removed are removed from it too. Creates no documents.

upsert

fun upsert(collection: CollectionReference): Pipeline

Writes each document of the previous stages to collection, with its own id or a new one, creating or replacing the document.

fun upsert(collectionPath: String): Pipeline

Writes each document of the previous stages to the collection at collectionPath, with its own id or a new one, creating or replacing the document.

fun upsert(vararg additionalFields: Selectable): Pipeline

Writes each document of the previous stages, with additionalFields added, to the path in its __name__ field, creating or replacing the document (stored fields are not merged).

fun upsert(collection: CollectionReference, documentIdExpression: Expression): Pipeline

Writes each document of the previous stages to collection, with the id documentIdExpression evaluates to, creating or replacing the document.

fun upsert(collectionPath: String, documentIdExpression: Expression): Pipeline

Writes each document of the previous stages to the collection at collectionPath, with the id documentIdExpression evaluates to, creating or replacing the document.

where

fun where(condition: BooleanExpression): Pipeline

Keeps the documents for which condition is true.