Update

The update(...) stage updates existing documents.

Examples

For example, the following operation backfills a data model change to all documents in a collection group. The pipeline adds a preferences.color field to all all documents in the users collection group that are missing that field.

Node.js
const snapshot = await db.pipeline()
   .collectionGroup("users")
   .where(not(exists(field("preferences.color"))))
   .addFields(constant(null).as("preferences.color"))
   .removeFields("color")
   .update()
   .execute();
test.firestore.js
Python
from google.cloud.firestore_v1.pipeline_expressions import Constant, Field, Not

snapshot = (
    client.pipeline()
    .collection_group("users")
    .where(Not(Field.of("preferences.color").exists()))
    .add_fields(Constant.of(None).as_("preferences.color"))
    .remove_fields("color")
    .update()
    .execute()
)
firestore_pipelines.py
Java
Pipeline.Snapshot snapshot = firestore.pipeline()
   .collectionGroup("users")
   .where(not(exists(field("preferences.color"))))
   .addFields(constant((String) null).as("preferences.color"))
   .removeFields("color")
   .update()
   .execute().get();
PipelineSnippets.java

Behavior

All data manipulation language (DML) stages must come at the end of the pipeline.

The documents coming into this stage must include the __name__ field to identify which documents to update. The operation fails if any of the documents don't exist. Most Input stages (like collection(...), collection_group(...), database(...), and documents(...)) include the __name__ field by default.

You can optionally provide transformations to apply right before writing the documents. These act identically to adding an add_fields(...) right before the final output stage and the expressions run in the context of the previous documents.

The response includes a summary of the number of documents modified. For example, the following response confirms that the pipeline modified three documents:

{documents_modified: 3L}

Limitations

  • DML stages don't support Cloud Firestore Security Rules. DML operation attempts through Cloud Firestore Security Rules are denied.

  • During the Preview for this feature, you cannot run DML stages in a transaction. For more information on consistency behavior see Consistency.

  • If the stage preceding the DML stage produces multiple documents with the same __name__, each instance is processed. For update(...), this means the same target document might be modified multiple times. For delete(...), subsequent attempts after the first will be no-ops.