Class Upsert (3.53.0)

public final class Upsert extends Stage

A pipeline stage that writes each document produced by the previous stages, creating the target document if it doesn't exist and replacing it if it does. Stored fields are not merged.

The target path of each document is determined as follows:

  • With neither a collection nor a document ID expression, the input document's own path (its name field) is used. A document without a name field fails with INVALID_ARGUMENT.
  • With only a collection, the document is written to that collection under the input document's ID, or under a generated ID if the input document has no name.
  • With only a document ID expression, the document is written to the input document's parent collection under the ID that the expression evaluates to.
  • With both, the document is written to the collection under the ID that the expression evaluates to.

Example:


 // Set "status" on each matching document and write it to the path given by its __name__ field.
 firestore.pipeline()
     .collection("books")
     .where(field("rating").greaterThan(4))
     .addFields(constant("Featured").as("status"))
     .upsert()
     .execute()
     .get();
 

See Also: com.google.cloud.firestore.Pipeline#upsert(Upsert)

Inheritance

java.lang.Object > Stage > Upsert

Constructors

Upsert()

public Upsert()

Creates an upsert stage with no additional fields, no target collection and no document ID expression, so each document is written to the path given by its name field.

Upsert(Selectable[] additionalFields)

public Upsert(Selectable[] additionalFields)

Creates an upsert stage that adds the given fields to each input document before it is written to the path given by its name field.

Parameter
Name Description
additionalFields Selectable[]

Fields to add to each input document. A field with the same name as an existing input field overwrites that field.

Methods

withAdditionalFields(Selectable[] additionalFields)

public Upsert withAdditionalFields(Selectable[] additionalFields)

Sets the fields to add to each input document before it is written.

Parameter
Name Description
additionalFields Selectable[]

Fields to add to each input document. A field with the same name as an existing input field overwrites that field.

Returns
Type Description
Upsert

A new Upsert stage with the additional fields set.

withAdditionalFields(List<Selectable> additionalFields)

public Upsert withAdditionalFields(List<Selectable> additionalFields)

Sets the fields to add to each input document before it is written.

Parameter
Name Description
additionalFields List<Selectable>

Fields to add to each input document. A field with the same name as an existing input field overwrites that field.

Returns
Type Description
Upsert

A new Upsert stage with the additional fields set.

withCollection(String collectionPath)

public Upsert withCollection(String collectionPath)

Sets the collection that documents are written to.

Parameter
Name Description
collectionPath String

The path of the target collection, for example "books" or "users/alice/books".

Returns
Type Description
Upsert

A new Upsert stage with the target collection set.

withDocumentIdExpression(Expression documentIdExpression)

public Upsert withDocumentIdExpression(Expression documentIdExpression)

Sets the expression that produces the ID of each target document.

Parameter
Name Description
documentIdExpression Expression

An expression that is evaluated against each input document and must evaluate to a document ID (not a document path). Use constant("id") for a fixed ID.

Returns
Type Description
Upsert

A new Upsert stage with the document ID expression set.