Stay organized with collectionsSave and categorize content based on your preferences.
Add and update data
This document explains how to set, add, or update individual documents in
Firestore. To write data in bulk, seeTransactions and batched writes.
Overview
You can write data to Firestore in one of the following ways:
Set the data of a document within a collection, explicitly specifying a
document identifier.
Add a new document to a collection. In this case, Firestore
automatically generates the document identifier.
Create an empty document with an automatically generated identifier,
and assign data to it later.
Before you begin
Before you can initialize Firestore to set, add, or update data,
you must complete the following steps:
Create a Firestore database. For more information, see one of theFirestore quickstarts.
If you use the web or mobile client libraries, authenticate with security rules. For more information, seeGetting started with security rules.
If you use the server client libraries or REST API, authenticate with Identity and Access Management (IAM). For more information, seeSecurity for server client libraries.
fromgoogle.cloudimportfirestore# The `project` parameter is optional and represents which project the client# will act on behalf of. If not supplied, the client falls back to the default# project inferred from the environment.db=firestore.Client(project="my-project-id")
fromgoogle.cloudimportfirestore# The `project` parameter is optional and represents which project the client# will act on behalf of. If not supplied, the client falls back to the default# project inferred from the environment.db=firestore.AsyncClient(project="my-project-id")
import("context""flag""fmt""log""google.golang.org/api/iterator""cloud.google.com/go/firestore")funccreateClient(ctxcontext.Context)*firestore.Client{// Sets your Google Cloud Platform project ID.projectID:="YOUR_PROJECT_ID"client,err:=firestore.NewClient(ctx,projectID)iferr!=nil{log.Fatalf("Failed to create client: %v",err)}// Close client when done with// defer client.Close()returnclient}
use Google\Cloud\Firestore\FirestoreClient;/*** Initialize Cloud Firestore with default project ID.*/function setup_client_create(string $projectId = null){// Create the Cloud Firestore clientif (empty($projectId)) {// The `projectId` parameter is optional and represents which project the// client will act on behalf of. If not supplied, the client falls back to// the default project inferred from the environment.$db = new FirestoreClient();printf('Created Cloud Firestore client with default project ID.' . PHP_EOL);} else {$db = new FirestoreClient(['projectId' => $projectId,]);printf('Created Cloud Firestore client with project ID: %s' . PHP_EOL, $projectId);}}
FirestoreDbdb=FirestoreDb.Create(project);Console.WriteLine("Created Cloud Firestore client with project ID: {0}",project);
Ruby
require"google/cloud/firestore"# The `project_id` parameter is optional and represents which project the# client will act on behalf of. If not supplied, the client falls back to the# default project inferred from the environment.firestore=Google::Cloud::Firestore.newproject_id:project_idputs"Created Cloud Firestore client with given project ID."
To create or overwrite a single document, use the following language-specificset()methods:
Web version 9
Use thesetDoc()method:
import{doc,setDoc}from"firebase/firestore";// Add a new document in collection "cities"awaitsetDoc(doc(db,"cities","LA"),{name:"Los Angeles",state:"CA",country:"USA"});
// Add a new document in collection "cities"db.collection("cities").doc("LA").set({name:"Los Angeles",state:"CA",country:"USA"}).then(()=>{console.log("Document successfully written!");}).catch((error)=>{console.error("Error writing document: ",error);});
Note:This product is not available on watchOS and App Clip targets.
// Add a new document in collection "cities"do{tryawaitdb.collection("cities").document("LA").setData(["name":"Los Angeles","state":"CA","country":"USA"])print("Document successfully written!")}catch{print("Error writing document:\(error)")}
Note:This product is not available on watchOS and App Clip targets.
// Add a new document in collection "cities"[[[self.dbcollectionWithPath:@"cities"]documentWithPath:@"LA"]setData:@{@"name":@"Los Angeles",@"state":@"CA",@"country":@"USA"}completion:^(NSError*_Nullableerror){if(error!=nil){NSLog(@"Error writing document: %@",error);}else{NSLog(@"Document successfully written!");}}];
// Create a Map to store the data we want to setMap<String,Object>docData=newHashMap<>();docData.put("name","Los Angeles");docData.put("state","CA");docData.put("country","USA");docData.put("regions",Arrays.asList("west_coast","socal"));// Add a new document (asynchronously) in collection "cities" with id "LA"ApiFuture<WriteResult>future=db.collection("cities").document("LA").set(docData);// ...// future.get() blocks on responseSystem.out.println("Update time : "+future.get().getUpdateTime());
data={"name":"Los Angeles","state":"CA","country":"USA"}# Add a new doc in collection 'cities' with ID 'LA'db.collection("cities").document("LA").set(data)
data={"name":"Los Angeles","state":"CA","country":"USA"}# Add a new doc in collection 'cities' with ID 'LA'awaitdb.collection("cities").document("LA").set(data)
constdata={name:'Los Angeles',state:'CA',country:'USA'};// Add a new document in collection "cities" with ID 'LA'constres=awaitdb.collection('cities').doc('LA').set(data);
import("context""log""cloud.google.com/go/firestore")funcaddDocAsMap(ctxcontext.Context,client*firestore.Client)error{_,err:=client.Collection("cities").Doc("LA").Set(ctx,map[string]interface{}{"name":"Los Angeles","state":"CA","country":"USA",})iferr!=nil{// Handle any errors in an appropriate way, such as returning them.log.Printf("An error has occurred: %s",err)}returnerr}
DocumentReferencedocRef=db.Collection("cities").Document("LA");Dictionary<string,object>city=newDictionary<string,object>{{"Name","Los Angeles"},{"State","CA"},{"Country","USA"}};docRef.SetAsync(city).ContinueWithOnMainThread(task=>{Debug.Log("Added data to the LA document in the cities collection.");});
If the document does not exist, it will be created. If the document does exist,
its contents will be overwritten with the newly provided data, unless you
specify that the data should be merged into the existing document, as follows:
Note:This product is not available on watchOS and App Clip targets.
// Write to the document reference, merging data with existing// if the document already exists[[[self.dbcollectionWithPath:@"cities"]documentWithPath:@"BJ"]setData:@{@"capital":@YES}merge:YEScompletion:^(NSError*_Nullableerror){// ...}];
// Update one field, creating the document if it does not already exist.valdata=hashMapOf("capital"totrue)db.collection("cities").document("BJ").set(data,SetOptions.merge())
// Update one field, creating the document if it does not already exist.Map<String,Object>data=newHashMap<>();data.put("capital",true);db.collection("cities").document("BJ").set(data,SetOptions.merge());
// Update one field, creating the document if it does not already exist.finaldata={"capital":true};db.collection("cities").doc("BJ").set(data,SetOptions(merge:true));
// asynchronously update doc, create the document if missingMap<String,Object>update=newHashMap<>();update.put("capital",true);ApiFuture<WriteResult>writeResult=db.collection("cities").document("BJ").set(update,SetOptions.merge());// ...System.out.println("Update time : "+writeResult.get().getUpdateTime());
import("context""log""cloud.google.com/go/firestore")funcupdateDocCreateIfMissing(ctxcontext.Context,client*firestore.Client)error{_,err:=client.Collection("cities").Doc("BJ").Set(ctx,map[string]interface{}{"capital":true,},firestore.MergeAll)iferr!=nil{// Handle any errors in an appropriate way, such as returning them.log.Printf("An error has occurred: %s",err)}returnerr}
If you're not sure whether the document exists, pass the option to merge the new
data with any existing document to avoid overwriting entire documents. For
documents that contain maps, if you specify a set with a field that contains an
empty map, the map field of the target document is overwritten.
Data types
Firestore lets you write a variety of data types inside a document,
including strings, booleans, numbers, dates, null, and nested arrays and
objects. Firestore always stores numbers as doubles, regardless of
what type of number you use in your code.
Map<String,Object>docData=newHashMap<>();docData.put("stringExample","Hello, World");docData.put("booleanExample",false);docData.put("numberExample",3.14159265);docData.put("nullExample",null);ArrayList<Object>arrayExample=newArrayList<>();Collections.addAll(arrayExample,5L,true,"hello");docData.put("arrayExample",arrayExample);Map<String,Object>objectExample=newHashMap<>();objectExample.put("a",5L);objectExample.put("b",true);docData.put("objectExample",objectExample);ApiFuture<WriteResult>future=db.collection("data").document("one").set(docData);System.out.println("Update time : "+future.get().getUpdateTime());
import("context""log""time""cloud.google.com/go/firestore")funcaddDocDataTypes(ctxcontext.Context,client*firestore.Client)error{doc:=make(map[string]interface{})doc["stringExample"]="Hello world!"doc["booleanExample"]=truedoc["numberExample"]=3.14159265doc["dateExample"]=time.Now()doc["arrayExample"]=[]interface{}{5,true,"hello"}doc["nullExample"]=nildoc["objectExample"]=map[string]interface{}{"a":5,"b":true,}_,err:=client.Collection("data").Doc("one").Set(ctx,doc)iferr!=nil{// Handle any errors in an appropriate way, such as returning them.log.Printf("An error has occurred: %s",err)}returnerr}
UsingMaporDictionaryobjects to represent your documents is often
inconvenient, so Firestore supports writing documents with custom
classes. Firestore converts the objects to supported data types.
Using custom classes, you can rewrite the initial example in the following way:
Web version 9
classCity{constructor(name,state,country){this.name=name;this.state=state;this.country=country;}toString(){returnthis.name+', '+this.state+', '+this.country;}}// Firestore data converterconstcityConverter={toFirestore:(city)=>{return{name:city.name,state:city.state,country:city.country};},fromFirestore:(snapshot,options)=>{constdata=snapshot.data(options);returnnewCity(data.name,data.state,data.country);}};
Note:This product is not available on watchOS and App Clip targets.
// This isn't supported in Objective-C.
Kotlin Android
dataclassCity(valname:String?=null,valstate:String?=null,valcountry:String?=null,@field:JvmField// use this annotation if your Boolean field is prefixed with 'is'valisCapital:Boolean?=null,valpopulation:Long?=null,valregions:List<String>?=null,)
publicCity(){// Must have a public no-argument constructor}// Initialize all fields of a citypublicCity(Stringname,Stringstate,Stringcountry,Booleancapital,Longpopulation,List<String>regions){this.name=name;this.state=state;this.country=country;this.capital=capital;this.population=population;this.regions=regions;}
// City represents a city.typeCitystruct{Namestring`firestore:"name,omitempty"`Statestring`firestore:"state,omitempty"`Countrystring`firestore:"country,omitempty"`Capitalbool`firestore:"capital,omitempty"`Populationint64`firestore:"population,omitempty"`Densityint64`firestore:"density,omitempty"`Regions[]string`firestore:"regions,omitempty"`}
import{doc,setDoc}from"firebase/firestore";// Set with cityConverterconstref=doc(db,"cities","LA").withConverter(cityConverter);awaitsetDoc(ref,newCity("Los Angeles","CA","USA"));
Note:This product is not available on watchOS and App Clip targets.
letcity=City(name:"Los Angeles",state:"CA",country:"USA",isCapital:false,population:5000000)do{trydb.collection("cities").document("LA").setData(from:city)}catchleterror{print("Error writing city to Firestore:\(error)")}
Citycity=newCity("Los Angeles","CA","USA",false,3900000L,Arrays.asList("west_coast","socal"));ApiFuture<WriteResult>future=db.collection("cities").document("LA").set(city);// block on response if requiredSystem.out.println("Update time : "+future.get().getUpdateTime());
import("context""log""cloud.google.com/go/firestore")funcaddDocAsEntity(ctxcontext.Context,client*firestore.Client)error{city:=City{Name:"Los Angeles",Country:"USA",}_,err:=client.Collection("cities").Doc("LA").Set(ctx,city)iferr!=nil{// Handle any errors in an appropriate way, such as returning them.log.Printf("An error has occurred: %s",err)}returnerr}
import("context""log""cloud.google.com/go/firestore")funcaddDocWithID(ctxcontext.Context,client*firestore.Client)error{vardata=make(map[string]interface{})_,err:=client.Collection("cities").Doc("new-city-id").Set(ctx,data)iferr!=nil{// Handle any errors in an appropriate way, such as returning them.log.Printf("An error has occurred: %s",err)}returnerr}
If there isn't a meaningful ID for the document, Firestore can
auto-generate an ID for you. You can call the following language-specificadd()methods:
Web version 9
Use theaddDoc()method:
import{collection,addDoc}from"firebase/firestore";// Add a new document with a generated id.constdocRef=awaitaddDoc(collection(db,"cities"),{name:"Tokyo",country:"Japan"});console.log("Document written with ID: ",docRef.id);
// Add a new document with a generated id.db.collection("cities").add({name:"Tokyo",country:"Japan"}).then((docRef)=>{console.log("Document written with ID: ",docRef.id);}).catch((error)=>{console.error("Error adding document: ",error);});
Note:This product is not available on watchOS and App Clip targets.
// Add a new document with a generated id.do{letref=tryawaitdb.collection("cities").addDocument(data:["name":"Tokyo","country":"Japan"])print("Document added with ID:\(ref.documentID)")}catch{print("Error adding document:\(error)")}
Note:This product is not available on watchOS and App Clip targets.
// Add a new document with a generated id.__blockFIRDocumentReference*ref=[[self.dbcollectionWithPath:@"cities"]addDocumentWithData:@{@"name":@"Tokyo",@"country":@"Japan"}completion:^(NSError*_Nullableerror){if(error!=nil){NSLog(@"Error adding document: %@",error);}else{NSLog(@"Document added with ID: %@",ref.documentID);}}];
// Add a new document with a generated id.valdata=hashMapOf("name"to"Tokyo","country"to"Japan",)db.collection("cities").add(data).addOnSuccessListener{documentReference->Log.d(TAG,"DocumentSnapshot written with ID:${documentReference.id}")}.addOnFailureListener{e->Log.w(TAG,"Error adding document",e)}
// Add a new document with a generated id.Map<String,Object>data=newHashMap<>();data.put("name","Tokyo");data.put("country","Japan");db.collection("cities").add(data).addOnSuccessListener(newOnSuccessListener<DocumentReference>(){@OverridepublicvoidonSuccess(DocumentReferencedocumentReference){Log.d(TAG,"DocumentSnapshot written with ID: "+documentReference.getId());}}).addOnFailureListener(newOnFailureListener(){@OverridepublicvoidonFailure(@NonNullExceptione){Log.w(TAG,"Error adding document",e);}});
// Add a new document with a generated id.finaldata={"name":"Tokyo","country":"Japan"};db.collection("cities").add(data).then((documentSnapshot)=>print("Added Data with ID:${documentSnapshot.id}"));
// Add document data with auto-generated id.Map<String,Object>data=newHashMap<>();data.put("name","Tokyo");data.put("country","Japan");ApiFuture<DocumentReference>addedDocRef=db.collection("cities").add(data);System.out.println("Added document with ID: "+addedDocRef.get().getId());
// Add a new document with a generated id.constres=awaitdb.collection('cities').add({name:'Tokyo',country:'Japan'});console.log('Added document with ID: ',res.id);
import("context""log""cloud.google.com/go/firestore")funcaddDocWithoutID(ctxcontext.Context,client*firestore.Client)error{_,_,err:=client.Collection("cities").Add(ctx,map[string]interface{}{"name":"Tokyo","country":"Japan",})iferr!=nil{// Handle any errors in an appropriate way, such as returning them.log.Printf("An error has occurred: %s",err)}returnerr}
Dictionary<string,object>city=newDictionary<string,object>{{"Name","Tokyo"},{"Country","Japan"}};db.Collection("cities").AddAsync(city).ContinueWithOnMainThread(task=>{DocumentReferenceaddedDocRef=task.Result;Debug.Log(String.Format("Added document with ID: {0}.",addedDocRef.Id));});
C#
Use theAddAsync()method:
Dictionary<string,object>city=newDictionary<string,object>{{"Name","Tokyo"},{"Country","Japan"}};DocumentReferenceaddedDocRef=awaitdb.Collection("cities").AddAsync(city);Console.WriteLine("Added document with ID: {0}.",addedDocRef.Id);
data={name:"Tokyo",country:"Japan"}cities_ref=firestore.colcollection_pathadded_doc_ref=cities_ref.adddataputs"Added document with ID:#{added_doc_ref.document_id}."
In some cases, it can be useful to create a document reference with an
auto-generated ID, then use the reference later. For this use case, you can calldoc()in the following way:
Web version 9
import{collection,doc,setDoc}from"firebase/firestore";// Add a new document with a generated idconstnewCityRef=doc(collection(db,"cities"));// later...awaitsetDoc(newCityRef,data);
// Add document data after generating an id.DocumentReferenceaddedDocRef=db.collection("cities").document();System.out.println("Added document with ID: "+addedDocRef.getId());// later...ApiFuture<WriteResult>writeResult=addedDocRef.set(data);
import("context""log""cloud.google.com/go/firestore")funcaddDocAfterAutoGeneratedID(ctxcontext.Context,client*firestore.Client)error{data:=City{Name:"Sydney",Country:"Australia",}ref:=client.Collection("cities").NewDoc()// later..._,err:=ref.Set(ctx,data)iferr!=nil{// Handle any errors in an appropriate way, such as returning them.log.Printf("An error has occurred: %s",err)}returnerr}
$addedDocRef = $db->collection('samples/php/cities')->newDocument();printf('Added document with ID: %s' . PHP_EOL, $addedDocRef->id());$addedDocRef->set($data);
Unity
DocumentReferenceaddedDocRef=db.Collection("cities").Document();Debug.Log(String.Format("Added document with ID: {0}.",addedDocRef.Id));addedDocRef.SetAsync(city).ContinueWithOnMainThread(task=>{Debug.Log(String.Format("Added data to the {0} document in the cities collection.",addedDocRef.Id));});
C#
DocumentReferenceaddedDocRef=db.Collection("cities").Document();Console.WriteLine("Added document with ID: {0}.",addedDocRef.Id);awaitaddedDocRef.SetAsync(city);
In the backend,.add(...)and.doc().set(...)are equivalent, so you can use
either option.
Update a document
To update some fields of a document without overwriting the entire document, use
the following language-specificupdate()methods:
Web version 9
Use theupdateDoc()method:
import{doc,updateDoc}from"firebase/firestore";constwashingtonRef=doc(db,"cities","DC");// Set the "capital" field of the city 'DC'awaitupdateDoc(washingtonRef,{capital:true});
varwashingtonRef=db.collection("cities").doc("DC");// Set the "capital" field of the city 'DC'returnwashingtonRef.update({capital:true}).then(()=>{console.log("Document successfully updated!");}).catch((error)=>{// The document probably doesn't exist.console.error("Error updating document: ",error);});
Note:This product is not available on watchOS and App Clip targets.
letwashingtonRef=db.collection("cities").document("DC")// Set the "capital" field of the city 'DC'do{tryawaitwashingtonRef.updateData(["capital":true])print("Document successfully updated")}catch{print("Error updating document:\(error)")}
Note:This product is not available on watchOS and App Clip targets.
FIRDocumentReference*washingtonRef=[[self.dbcollectionWithPath:@"cities"]documentWithPath:@"DC"];// Set the "capital" field of the city[washingtonRefupdateData:@{@"capital":@YES}completion:^(NSError*_Nullableerror){if(error!=nil){NSLog(@"Error updating document: %@",error);}else{NSLog(@"Document successfully updated");}}];
valwashingtonRef=db.collection("cities").document("DC")// Set the "isCapital" field of the city 'DC'washingtonRef.update("capital",true).addOnSuccessListener{Log.d(TAG,"DocumentSnapshot successfully updated!")}.addOnFailureListener{e->Log.w(TAG,"Error updating document",e)}
DocumentReferencewashingtonRef=db.collection("cities").document("DC");// Set the "isCapital" field of the city 'DC'washingtonRef.update("capital",true).addOnSuccessListener(newOnSuccessListener<Void>(){@OverridepublicvoidonSuccess(VoidaVoid){Log.d(TAG,"DocumentSnapshot successfully updated!");}}).addOnFailureListener(newOnFailureListener(){@OverridepublicvoidonFailure(@NonNullExceptione){Log.w(TAG,"Error updating document",e);}});
DocumentReferencewashington_ref=db->Collection("cities").Document("DC");// Set the "capital" field of the city "DC".washington_ref.Update({{"capital", FieldValue::Boolean(true)}});
import("context""log""cloud.google.com/go/firestore")funcupdateDoc(ctxcontext.Context,client*firestore.Client)error{// ..._,err:=client.Collection("cities").Doc("DC").Update(ctx,[]firestore.Update{{Path:"capital",Value:true,},})iferr!=nil{// Handle any errors in an appropriate way, such as returning them.log.Printf("An error has occurred: %s",err)}returnerr}
DocumentReferencecityRef=db.Collection("cities").Document("new-city-id");Dictionary<string,object>updates=newDictionary<string,object>{{"Capital",false}};cityRef.UpdateAsync(updates).ContinueWithOnMainThread(task=>{Debug.Log("Updated the Capital field of the new-city-id document in the cities collection.");});// You can also update a single field with: cityRef.UpdateAsync("Capital", false);
C#
Use theUpdateAsync()method:
DocumentReferencecityRef=db.Collection("cities").Document("new-city-id");Dictionary<string,object>updates=newDictionary<string,object>{{"Capital",false}};awaitcityRef.UpdateAsync(updates);// You can also update a single field with: await cityRef.UpdateAsync("Capital", false);
You can set a field in your document to a server timestamp which tracks when
the server receives the update.
Web version 9
import{updateDoc,serverTimestamp}from"firebase/firestore";constdocRef=doc(db,'objects','some-id');// Update the timestamp field with the value from the serverconstupdateTimestamp=awaitupdateDoc(docRef,{timestamp:serverTimestamp()});
vardocRef=db.collection('objects').doc('some-id');// Update the timestamp field with the value from the servervarupdateTimestamp=docRef.update({timestamp:firebase.firestore.FieldValue.serverTimestamp()});
// If you're using custom Kotlin objects in Android, add an @ServerTimestamp// annotation to a Date field for your custom object classes. This indicates// that the Date field should be treated as a server timestamp by the object mapper.valdocRef=db.collection("objects").document("some-id")// Update the timestamp field with the value from the servervalupdates=hashMapOf<String,Any>("timestamp"toFieldValue.serverTimestamp(),)docRef.update(updates).addOnCompleteListener{}
// If you're using custom Java objects in Android, add an @ServerTimestamp// annotation to a Date field for your custom object classes. This indicates// that the Date field should be treated as a server timestamp by the object mapper.DocumentReferencedocRef=db.collection("objects").document("some-id");// Update the timestamp field with the value from the serverMap<String,Object>updates=newHashMap<>();updates.put("timestamp",FieldValue.serverTimestamp());docRef.update(updates).addOnCompleteListener(newOnCompleteListener<Void>(){// ...// ...
DocumentReferencedocRef=db.collection("objects").document("some-id");// Update the timestamp field with the value from the serverApiFuture<WriteResult>writeResult=docRef.update("timestamp",FieldValue.serverTimestamp());System.out.println("Update time : "+writeResult.get());
// Create a document referenceconstdocRef=db.collection('objects').doc('some-id');// Update the timestamp field with the value from the serverconstres=awaitdocRef.update({timestamp:FieldValue.serverTimestamp()});
import("context""log""cloud.google.com/go/firestore")funcupdateDocServerTimestamp(ctxcontext.Context,client*firestore.Client)error{// ..._,err:=client.Collection("objects").Doc("some-id").Set(ctx,map[string]interface{}{"timestamp":firestore.ServerTimestamp,},firestore.MergeAll)iferr!=nil{// Handle any errors in an appropriate way, such as returning them.log.Printf("An error has occurred: %s",err)}returnerr}
DocumentReferencecityRef=db.Collection("cities").Document("new-city-id");cityRef.UpdateAsync("Timestamp",FieldValue.ServerTimestamp).ContinueWithOnMainThread(task=>{Debug.Log("Updated the Timestamp field of the new-city-id document in the cities "+"collection.");});
When updating multiple timestamp fields inside of atransaction, each field receives the same server timestamp
value.
Update fields in nested objects
If your document contains nested objects, you can use thedot notationto
reference nested fields within the document when you callupdate():
Web version 9
import{doc,setDoc,updateDoc}from"firebase/firestore";// Create an initial document to update.constfrankDocRef=doc(db,"users","frank");awaitsetDoc(frankDocRef,{name:"Frank",favorites:{food:"Pizza",color:"Blue",subject:"recess"},age:12});// To update age and favorite color:awaitupdateDoc(frankDocRef,{"age":13,"favorites.color":"Red"});
// Create an initial document to update.varfrankDocRef=db.collection("users").doc("frank");frankDocRef.set({name:"Frank",favorites:{food:"Pizza",color:"Blue",subject:"recess"},age:12});// To update age and favorite color:db.collection("users").doc("frank").update({"age":13,"favorites.color":"Red"}).then(()=>{console.log("Document successfully updated!");});
Note:This product is not available on watchOS and App Clip targets.
// Create an initial document to update.letfrankDocRef=db.collection("users").document("frank")do{tryawaitfrankDocRef.setData(["name":"Frank","favorites":["food":"Pizza","color":"Blue","subject":"recess"],"age":12])// To update age and favorite color:tryawaitfrankDocRef.updateData(["age":13,"favorites.color":"Red"])print("Document successfully updated")}catch{print("Error updating document:\(error)")}
Note:This product is not available on watchOS and App Clip targets.
// Create an initial document to update.FIRDocumentReference*frankDocRef=[[self.dbcollectionWithPath:@"users"]documentWithPath:@"frank"];[frankDocRefsetData:@{@"name":@"Frank",@"favorites":@{@"food":@"Pizza",@"color":@"Blue",@"subject":@"recess"},@"age":@12}];// To update age and favorite color:[frankDocRefupdateData:@{@"age":@13,@"favorites.color":@"Red",}completion:^(NSError*_Nullableerror){if(error!=nil){NSLog(@"Error updating document: %@",error);}else{NSLog(@"Document successfully updated");}}];
// Create an initial document to updateDocumentReferencefrankDocRef=db.collection("users").document("frank");Map<String,Object>initialData=newHashMap<>();initialData.put("name","Frank");initialData.put("age",12);Map<String,Object>favorites=newHashMap<>();favorites.put("food","Pizza");favorites.put("color","Blue");favorites.put("subject","Recess");initialData.put("favorites",favorites);ApiFuture<WriteResult>initialResult=frankDocRef.set(initialData);// Confirm that data has been successfully saved by blocking on the operationinitialResult.get();// Update age and favorite colorMap<String,Object>updates=newHashMap<>();updates.put("age",13);updates.put("favorites.color","Red");// Async update documentApiFuture<WriteResult>writeResult=frankDocRef.update(updates);// ...System.out.println("Update time : "+writeResult.get().getUpdateTime());
# Create an initial document to updatefrank_ref=db.collection("users").document("frank")frank_ref.set({"name":"Frank","favorites":{"food":"Pizza","color":"Blue","subject":"Recess"},"age":12,})# Update age and favorite colorfrank_ref.update({"age":13,"favorites.color":"Red"})
# Create an initial document to updatefrank_ref=db.collection("users").document("frank")awaitfrank_ref.set({"name":"Frank","favorites":{"food":"Pizza","color":"Blue","subject":"Recess"},"age":12,})# Update age and favorite colorawaitfrank_ref.update({"age":13,"favorites.color":"Red"})
import("context""log""cloud.google.com/go/firestore")funcupdateDocNested(ctxcontext.Context,client*firestore.Client)error{initialData:=map[string]interface{}{"name":"Frank","age":12,"favorites":map[string]interface{}{"food":"Pizza","color":"Blue","subject":"recess",},}// ..._,err:=client.Collection("users").Doc("frank").Set(ctx,map[string]interface{}{"age":13,"favorites":map[string]interface{}{"color":"Red",},},firestore.MergeAll)iferr!=nil{// Handle any errors in an appropriate way, such as returning them.log.Printf("An error has occurred: %s",err)}returnerr}
// Create an initial document to update$frankRef = $db->collection('samples/php/users')->document('frank');$frankRef->set(['first' => 'Frank','last' => 'Franklin','favorites' => ['food' => 'Pizza', 'color' => 'Blue', 'subject' => 'Recess'],'age' => 12]);// Update age and favorite color$frankRef->update([['path' => 'age', 'value' => 13],['path' => 'favorites.color', 'value' => 'Red']]);
Unity
DocumentReferencefrankDocRef=db.Collection("users").Document("frank");Dictionary<string,object>initialData=newDictionary<string,object>{{"Name","Frank"},{"Age",12}};Dictionary<string,object>favorites=newDictionary<string,object>{{"Food","Pizza"},{"Color","Blue"},{"Subject","Recess"},};initialData.Add("Favorites",favorites);frankDocRef.SetAsync(initialData).ContinueWithOnMainThread(task=>{// Update age and favorite colorDictionary<string,object>updates=newDictionary<string,object>{{"Age",13},{"Favorites.Color","Red"},};// Asynchronously update the documentreturnfrankDocRef.UpdateAsync(updates);}).ContinueWithOnMainThread(task=>{Debug.Log("Updated the age and favorite color fields of the Frank document in "+"the users collection.");});
C#
DocumentReferencefrankDocRef=db.Collection("users").Document("frank");Dictionary<string,object>initialData=newDictionary<string,object>{{"Name","Frank"},{"Age",12}};Dictionary<string,object>favorites=newDictionary<string,object>{{"Food","Pizza"},{"Color","Blue"},{"Subject","Recess"},};initialData.Add("Favorites",favorites);awaitfrankDocRef.SetAsync(initialData);// Update age and favorite colorDictionary<string,object>updates=newDictionary<string,object>{{"Age",13},{"Favorites.Color","Red"},};// Asynchronously update the documentawaitfrankDocRef.UpdateAsync(updates);
# Create an initial document to updatefrank_ref=firestore.doc"#{collection_path}/frank"frank_ref.set({name:"Frank",favorites:{food:"Pizza",color:"Blue",subject:"Recess"},age:12})# Update age and favorite colorfrank_ref.update({age:13,"favorites.color":"Red"})
Dot notation allows you to update a single nested field without overwriting
other nested fields. If you update a nested field without dot notation, you will
overwrite the entire map field, as shown in the following example:
Web
// Create our initial docdb.collection("users").doc("frank").set({name:"Frank",favorites:{food:"Pizza",color:"Blue",subject:"Recess"},age:12}).then(function(){console.log("Frank created");});// Update the doc without using dot notation.// Notice the map value for favorites.db.collection("users").doc("frank").update({favorites:{food:"Ice Cream"}}).then(function(){console.log("Frank food updated");});/*EndingState,favorite.colorandfavorite.subjectarenolongerpresent:/users/frank{name:"Frank",favorites:{food:"Ice Cream",},age:12}*/
Update elements in an array
If your document contains an array field, you can usearrayUnion()andarrayRemove()to add and remove elements.arrayUnion()adds elements to an
array but only elements not already present.arrayRemove()removes all
instances of each given element.
Web version 9
import{doc,updateDoc,arrayUnion,arrayRemove}from"firebase/firestore";constwashingtonRef=doc(db,"cities","DC");// Atomically add a new region to the "regions" array field.awaitupdateDoc(washingtonRef,{regions:arrayUnion("greater_virginia")});// Atomically remove a region from the "regions" array field.awaitupdateDoc(washingtonRef,{regions:arrayRemove("east_coast")});
varwashingtonRef=db.collection("cities").doc("DC");// Atomically add a new region to the "regions" array field.washingtonRef.update({regions:firebase.firestore.FieldValue.arrayUnion("greater_virginia")});// Atomically remove a region from the "regions" array field.washingtonRef.update({regions:firebase.firestore.FieldValue.arrayRemove("east_coast")});
Note:This product is not available on watchOS and App Clip targets.
letwashingtonRef=db.collection("cities").document("DC")// Atomically add a new region to the "regions" array field.washingtonRef.updateData(["regions":FieldValue.arrayUnion(["greater_virginia"])])// Atomically remove a region from the "regions" array field.washingtonRef.updateData(["regions":FieldValue.arrayRemove(["east_coast"])])
Note:This product is not available on watchOS and App Clip targets.
FIRDocumentReference*washingtonRef=[[self.dbcollectionWithPath:@"cities"]documentWithPath:@"DC"];// Atomically add a new region to the "regions" array field.[washingtonRefupdateData:@{@"regions":[FIRFieldValuefieldValueForArrayUnion:@[@"greater_virginia"]]}];// Atomically remove a new region to the "regions" array field.[washingtonRefupdateData:@{@"regions":[FIRFieldValuefieldValueForArrayRemove:@[@"east_coast"]]}];
valwashingtonRef=db.collection("cities").document("DC")// Atomically add a new region to the "regions" array field.washingtonRef.update("regions",FieldValue.arrayUnion("greater_virginia"))// Atomically remove a region from the "regions" array field.washingtonRef.update("regions",FieldValue.arrayRemove("east_coast"))
DocumentReferencewashingtonRef=db.collection("cities").document("DC");// Atomically add a new region to the "regions" array field.washingtonRef.update("regions",FieldValue.arrayUnion("greater_virginia"));// Atomically remove a region from the "regions" array field.washingtonRef.update("regions",FieldValue.arrayRemove("east_coast"));
finalwashingtonRef=db.collection("cities").doc("DC");// Atomically add a new region to the "regions" array field.washingtonRef.update({"regions":FieldValue.arrayUnion(["greater_virginia"]),});// Atomically remove a region from the "regions" array field.washingtonRef.update({"regions":FieldValue.arrayRemove(["east_coast"]),});
DocumentReferencewashingtonRef=db.collection("cities").document("DC");// Atomically add a new region to the "regions" array field.ApiFuture<WriteResult>arrayUnion=washingtonRef.update("regions",FieldValue.arrayUnion("greater_virginia"));System.out.println("Update time : "+arrayUnion.get());// Atomically remove a region from the "regions" array field.ApiFuture<WriteResult>arrayRm=washingtonRef.update("regions",FieldValue.arrayRemove("east_coast"));System.out.println("Update time : "+arrayRm.get());
city_ref=db.collection("cities").document("DC")# Atomically add a new region to the 'regions' array field.city_ref.update({"regions":firestore.ArrayUnion(["greater_virginia"])})# // Atomically remove a region from the 'regions' array field.city_ref.update({"regions":firestore.ArrayRemove(["east_coast"])})
city_ref=db.collection("cities").document("DC")# Atomically add a new region to the 'regions' array field.awaitcity_ref.update({"regions":firestore.ArrayUnion(["greater_virginia"])})# // Atomically remove a region from the 'regions' array field.awaitcity_ref.update({"regions":firestore.ArrayRemove(["east_coast"])})
// ...constwashingtonRef=db.collection('cities').doc('DC');// Atomically add a new region to the "regions" array field.constunionRes=awaitwashingtonRef.update({regions:FieldValue.arrayUnion('greater_virginia')});// Atomically remove a region from the "regions" array field.constremoveRes=awaitwashingtonRef.update({regions:FieldValue.arrayRemove('east_coast')});// To add or remove multiple items, pass multiple arguments to arrayUnion/arrayRemoveconstmultipleUnionRes=awaitwashingtonRef.update({regions:FieldValue.arrayUnion('south_carolina','texas')// Alternatively, you can use spread operator in ES6 syntax// const newRegions = ['south_carolina', 'texas']// regions: FieldValue.arrayUnion(...newRegions)});
$cityRef = $db->collection('samples/php/cities')->document('DC');// Atomically add a new region to the "regions" array field.$cityRef->update([['path' => 'regions', 'value' => FieldValue::arrayUnion(['greater_virginia'])]]);// Atomically remove a region from the "regions" array field.$cityRef->update([['path' => 'regions', 'value' => FieldValue::arrayRemove(['east_coast'])]]);
Unity
// This is not yet supported in the Unity SDK
C#
DocumentReferencewashingtonRef=db.Collection("cities").Document("DC");// Atomically add a new region to the "regions" array field.awaitwashingtonRef.UpdateAsync("Regions",FieldValue.ArrayUnion("greater_virginia"));// Atomically remove a region from the "regions" array field.awaitwashingtonRef.UpdateAsync("Regions",FieldValue.ArrayRemove("east_coast"));
You can increment or decrement a numeric field value as shown in the
following example. An increment operation increases or decreases the current
value of a field by the given amount.
Web version 9
import{doc,updateDoc,increment}from"firebase/firestore";constwashingtonRef=doc(db,"cities","DC");// Atomically increment the population of the city by 50.awaitupdateDoc(washingtonRef,{population:increment(50)});
varwashingtonRef=db.collection('cities').doc('DC');// Atomically increment the population of the city by 50.washingtonRef.update({population:firebase.firestore.FieldValue.increment(50)});
Note:This product is not available on watchOS and App Clip targets.
letwashingtonRef=db.collection("cities").document("DC")// Atomically increment the population of the city by 50.// Note that increment() with no arguments increments by 1.washingtonRef.updateData(["population":FieldValue.increment(Int64(50))])
Note:This product is not available on watchOS and App Clip targets.
FIRDocumentReference*washingtonRef=[[self.dbcollectionWithPath:@"cities"]documentWithPath:@"DC"];// Atomically increment the population of the city by 50.// Note that increment() with no arguments increments by 1.[washingtonRefupdateData:@{@"population":[FIRFieldValuefieldValueForIntegerIncrement:50]}];
valwashingtonRef=db.collection("cities").document("DC")// Atomically increment the population of the city by 50.washingtonRef.update("population",FieldValue.increment(50))
DocumentReferencewashingtonRef=db.collection("cities").document("DC");// Atomically increment the population of the city by 50.washingtonRef.update("population",FieldValue.increment(50));
varwashingtonRef=db.collection('cities').doc('DC');// Atomically increment the population of the city by 50.washingtonRef.update({"population":FieldValue.increment(50)},);
DocumentReferencewashingtonRef=db.collection("cities").document("DC");// Atomically increment the population of the city by 50.finalApiFuture<WriteResult>updateFuture=washingtonRef.update("population",FieldValue.increment(50));
// ...constwashingtonRef=db.collection('cities').doc('DC');// Atomically increment the population of the city by 50.constres=awaitwashingtonRef.update({population:FieldValue.increment(50)});
import("context""fmt""cloud.google.com/go/firestore")// updateDocumentIncrement increments the population of the city document in the// cities collection by 50.funcupdateDocumentIncrement(projectID,citystring)error{// projectID := "my-project"ctx:=context.Background()client,err:=firestore.NewClient(ctx,projectID)iferr!=nil{returnfmt.Errorf("firestore.NewClient: %w",err)}deferclient.Close()dc:=client.Collection("cities").Doc(city)_,err=dc.Update(ctx,[]firestore.Update{{Path:"population",Value:firestore.Increment(50)},})iferr!=nil{returnfmt.Errorf("Update: %w",err)}returnnil}
$cityRef = $db->collection('samples/php/cities')->document('DC');// Atomically increment the population of the city by 50.$cityRef->update([['path' => 'regions', 'value' => FieldValue::increment(50)]]);
Unity
// This is not yet supported in the Unity SDK.
C#
DocumentReferencewashingtonRef=db.Collection("cities").Document("DC");// Atomically increment the population of the city by 50.awaitwashingtonRef.UpdateAsync("Regions",FieldValue.Increment(50));
Increment operations are useful for implementing counters. Note that
updating a single document too quickly canlead to contention or errors. If you need to update
your counter at a very high rate, see theDistributed counterspage.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-09-04 UTC."],[],[],null,[]]
