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.

 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 
 
 

 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 
 
 

 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 
 : 
  
 3 
 L 
 } 
 

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.