Add data to Cloud Firestore

There are several ways to write data to Cloud Firestore:

Set the data of a document within a collection, explicitly specifying a document identifier.
Add a new document to a collection. In this case, Cloud Firestore automatically generates the document identifier.
Create an empty document with an automatically generated identifier, and assign data to it later.

This guide explains how to use the set, add, or update individual documents in Cloud Firestore. If you want to write data in bulk, see Transactions and Batched Writes.

Set a document

To create or overwrite a single document, use the set() method:

Web

// Add a new document in collection "cities"
db.collection("cities").doc("LA").set({
    name: "Los Angeles",
    state: "CA",
    country: "USA"
})
.then(function() {
    console.log("Document successfully written!");
})
.catch(function(error) {
    console.error("Error writing document: ", error);
});test.firestore.js

Swift

// Add a new document in collection "cities"
db.collection("cities").document("LA").setData([
    "name": "Los Angeles",
    "state": "CA",
    "country": "USA"
]) { err in
    if let err = err {
        print("Error writing document: \(err)")
    } else {
        print("Document successfully written!")
    }
}ViewController.swift

Objective-C

// Add a new document in collection "cities"
[[[self.db collectionWithPath:@"cities"] documentWithPath:@"LA"] setData:@{
  @"name": @"Los Angeles",
  @"state": @"CA",
  @"country": @"USA"
} completion:^(NSError * _Nullable error) {
  if (error != nil) {
    NSLog(@"Error writing document: %@", error);
  } else {
    NSLog(@"Document successfully written!");
  }
}];ViewController.m

Java

Map<String, Object> city = new HashMap<>();
city.put("name", "Los Angeles");
city.put("state", "CA");
city.put("country", "USA");

db.collection("cities").document("LA")
        .set(city)
        .addOnSuccessListener(new OnSuccessListener<Void>() {
            @Override
            public void onSuccess(Void aVoid) {
                Log.d(TAG, "DocumentSnapshot successfully written!");
            }
        })
        .addOnFailureListener(new OnFailureListener() {
            @Override
            public void onFailure(@NonNull Exception e) {
                Log.w(TAG, "Error writing document", e);
            }
        });DocSnippets.java

Kotlin+KTX

val city = hashMapOf(
        "name" to "Los Angeles",
        "state" to "CA",
        "country" to "USA"
)

db.collection("cities").document("LA")
        .set(city)
        .addOnSuccessListener { Log.d(TAG, "DocumentSnapshot successfully written!") }
        .addOnFailureListener { e -> Log.w(TAG, "Error writing document", e) }DocSnippets.kt

Java

// Create a Map to store the data we want to set
Map<String, Object> docData = new HashMap<>();
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 response
System.out.println("Update time : " + future.get().getUpdateTime());ManageDataSnippets.java

Python

data = {
    u'name': u'Los Angeles',
    u'state': u'CA',
    u'country': u'USA'
}

# Add a new doc in collection 'cities' with ID 'LA'
db.collection(u'cities').document(u'LA').set(data)snippets.py

C++

// Add a new document in collection 'cities'
db->Collection("cities")
    .Document("LA")
    .Set({{"name", FieldValue::FromString("Los Angeles")},
          {"state", FieldValue::FromString("CA")},
          {"country", FieldValue::FromString("USA")}})
    .OnCompletion([](const Future<void>& future) {
      if (future.error() == Error::Ok) {
        std::cout << "DocumentSnapshot successfully written!\n";
      } else {
        std::cout << "Error writing document: " << future.error_message()
                  << '\n';
      }
    });snippets.cpp

Node.js

let data = {
  name: 'Los Angeles',
  state: 'CA',
  country: 'USA'
};

// Add a new document in collection "cities" with ID 'LA'
let setDoc = db.collection('cities').doc('LA').set(data);index.js

Go

_, err := client.Collection("cities").Doc("LA").Set(ctx, map[string]interface{}{
	"name":    "Los Angeles",
	"state":   "CA",
	"country": "USA",
})
if err != nil {
	// Handle any errors in an appropriate way, such as returning them.
	log.Printf("An error has occurred: %s", err)
}save.go

PHP

$data = [
    'name' => 'Los Angeles',
    'state' => 'CA',
    'country' => 'USA'
];
$db->collection('cities')->document('LA')->set($data);set_document.php

Unity

DocumentReference docRef = db.Collection("cities").Document("LA");
Dictionary<string, object> city = new Dictionary<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.");
});

C#

DocumentReference docRef = db.Collection("cities").Document("LA");
Dictionary<string, object> city = new Dictionary<string, object>
{
    { "name", "Los Angeles" },
    { "state", "CA" },
    { "country", "USA" }
};
await docRef.SetAsync(city);Program.cs

Ruby

city_ref = firestore.doc "cities/LA"

data = {
  name:    "Los Angeles",
  state:   "CA",
  country: "USA"
}

city_ref.set dataadd_data.rb

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:

Web

var cityRef = db.collection('cities').doc('BJ');

var setWithMerge = cityRef.set({
    capital: true
}, { merge: true });test.firestore.js

Swift

// Update one field, creating the document if it does not exist.
db.collection("cities").document("BJ").setData([ "capital": true ], merge: true)ViewController.swift

Objective-C

// Write to the document reference, merging data with existing
// if the document already exists
[[[self.db collectionWithPath:@"cities"] documentWithPath:@"BJ"]
     setData:@{ @"capital": @YES }
     merge:YES
     completion:^(NSError * _Nullable error) {
       // ...
     }];ViewController.m

Java

// Update one field, creating the document if it does not already exist.
Map<String, Object> data = new HashMap<>();
data.put("capital", true);

db.collection("cities").document("BJ")
        .set(data, SetOptions.merge());DocSnippets.java

Kotlin+KTX

// Update one field, creating the document if it does not already exist.
val data = hashMapOf("capital" to true)

db.collection("cities").document("BJ")
        .set(data, SetOptions.merge())DocSnippets.kt

Java

//asynchronously update doc, create the document if missing
Map<String, Object> update = new HashMap<>();
update.put("capital", true);

ApiFuture<WriteResult> writeResult =
    db
        .collection("cities")
        .document("BJ")
        .set(update, SetOptions.merge());
// ...
System.out.println("Update time : " + writeResult.get().getUpdateTime());ManageDataSnippets.java

Python

city_ref = db.collection(u'cities').document(u'BJ')

city_ref.set({
    u'capital': True
}, merge=True)snippets.py

C++

db->Collection("cities").Document("BJ").Set(
    {{"capital", FieldValue::FromBoolean(true)}}, SetOptions::Merge());snippets.cpp

Node.js

let cityRef = db.collection('cities').doc('BJ');

let setWithOptions = cityRef.set({
  capital: true
}, {merge: true});index.js

Go

_, err := client.Collection("cities").Doc("BJ").Set(ctx, map[string]interface{}{
	"capital": true,
}, firestore.MergeAll)

if err != nil {
	// Handle any errors in an appropriate way, such as returning them.
	log.Printf("An error has occurred: %s", err)
}save.go

PHP

$cityRef = $db->collection('cities')->document('BJ');
$cityRef->set([
    'capital' => true
], ['merge' => true]);set_document_merge.php

Unity

DocumentReference docRef = db.Collection("cities").Document("LA");
Dictionary<string, object> update = new Dictionary<string, object>
{
	{ "capital", false }
};
docRef.SetAsync(update, SetOptions.MergeAll);

C#

DocumentReference docRef = db.Collection("cities").Document("LA");
Dictionary<string, object> update = new Dictionary<string, object>
{
    { "capital", false }
};
await docRef.SetAsync(update, SetOptions.MergeAll);Program.cs

Ruby

city_ref = firestore.doc "cities/LA"
city_ref.set({ capital: false }, merge: true)add_data.rb

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.

Data types

Cloud Firestore lets you write a variety of data types inside a document, including strings, booleans, numbers, dates, null, and nested arrays and objects. Cloud Firestore always stores numbers as doubles, regardless of what type of number you use in your code.

Web

var docData = {
    stringExample: "Hello world!",
    booleanExample: true,
    numberExample: 3.14159265,
    dateExample: firebase.firestore.Timestamp.fromDate(new Date("December 10, 1815")),
    arrayExample: [5, true, "hello"],
    nullExample: null,
    objectExample: {
        a: 5,
        b: {
            nested: "foo"
        }
    }
};
db.collection("data").doc("one").set(docData).then(function() {
    console.log("Document successfully written!");
});test.firestore.js

Swift

let docData: [String: Any] = [
    "stringExample": "Hello world!",
    "booleanExample": true,
    "numberExample": 3.14159265,
    "dateExample": Timestamp(date: Date()),
    "arrayExample": [5, true, "hello"],
    "nullExample": NSNull(),
    "objectExample": [
        "a": 5,
        "b": [
            "nested": "foo"
        ]
    ]
]
db.collection("data").document("one").setData(docData) { err in
    if let err = err {
        print("Error writing document: \(err)")
    } else {
        print("Document successfully written!")
    }
}ViewController.swift

Objective-C

NSDictionary *docData = @{
  @"stringExample": @"Hello world!",
  @"booleanExample": @YES,
  @"numberExample": @3.14,
  @"dateExample": [FIRTimestamp timestampWithDate:[NSDate date]],
  @"arrayExample": @[@5, @YES, @"hello"],
  @"nullExample": [NSNull null],
  @"objectExample": @{
    @"a": @5,
    @"b": @{
      @"nested": @"foo"
    }
  }
};

[[[self.db collectionWithPath:@"data"] documentWithPath:@"one"] setData:docData
    completion:^(NSError * _Nullable error) {
      if (error != nil) {
        NSLog(@"Error writing document: %@", error);
      } else {
        NSLog(@"Document successfully written!");
      }
    }];ViewController.m

Java

Map<String, Object> docData = new HashMap<>();
docData.put("stringExample", "Hello world!");
docData.put("booleanExample", true);
docData.put("numberExample", 3.14159265);
docData.put("dateExample", new Timestamp(new Date()));
docData.put("listExample", Arrays.asList(1, 2, 3));
docData.put("nullExample", null);

Map<String, Object> nestedData = new HashMap<>();
nestedData.put("a", 5);
nestedData.put("b", true);

docData.put("objectExample", nestedData);

db.collection("data").document("one")
        .set(docData)
        .addOnSuccessListener(new OnSuccessListener<Void>() {
            @Override
            public void onSuccess(Void aVoid) {
                Log.d(TAG, "DocumentSnapshot successfully written!");
            }
        })
        .addOnFailureListener(new OnFailureListener() {
            @Override
            public void onFailure(@NonNull Exception e) {
                Log.w(TAG, "Error writing document", e);
            }
        });DocSnippets.java

Kotlin+KTX

val docData = hashMapOf(
        "stringExample" to "Hello world!",
        "booleanExample" to true,
        "numberExample" to 3.14159265,
        "dateExample" to Timestamp(Date()),
        "listExample" to arrayListOf(1, 2, 3),
        "nullExample" to null
)

val nestedData = hashMapOf(
        "a" to 5,
        "b" to true
)

docData["objectExample"] = nestedData

db.collection("data").document("one")
        .set(docData)
        .addOnSuccessListener { Log.d(TAG, "DocumentSnapshot successfully written!") }
        .addOnFailureListener { e -> Log.w(TAG, "Error writing document", e) }DocSnippets.kt

Java

Map<String, Object> docData = new HashMap<>();
docData.put("stringExample", "Hello, World");
docData.put("booleanExample", false);
docData.put("numberExample", 3.14159265);
docData.put("nullExample", null);

ArrayList<Object> arrayExample = new ArrayList<>();
Collections.addAll(arrayExample, 5L, true, "hello");
docData.put("arrayExample", arrayExample);

Map<String, Object> objectExample = new HashMap<>();
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());ManageDataSnippets.java

Python

data = {
    u'stringExample': u'Hello, World!',
    u'booleanExample': True,
    u'numberExample': 3.14159265,
    u'dateExample': datetime.datetime.now(),
    u'arrayExample': [5, True, u'hello'],
    u'nullExample': None,
    u'objectExample': {
        u'a': 5,
        u'b': True
    }
}

db.collection(u'data').document(u'one').set(data)snippets.py

C++

MapFieldValue doc_data{
    {"stringExample", FieldValue::FromString("Hello world!")},
    {"booleanExample", FieldValue::FromBoolean(true)},
    {"numberExample", FieldValue::FromDouble(3.14159265)},
    {"dateExample", FieldValue::FromTimestamp(Timestamp::Now())},
    {"arrayExample", FieldValue::FromArray({FieldValue::FromInteger(1),
                                            FieldValue::FromInteger(2),
                                            FieldValue::FromInteger(3)})},
    {"nullExample", FieldValue::Null()},
    {"objectExample",
     FieldValue::FromMap(
         {{"a", FieldValue::FromInteger(5)},
          {"b", FieldValue::FromMap(
                    {{"nested", FieldValue::FromString("foo")}})}})},
};

db->Collection("data").Document("one").Set(doc_data).OnCompletion(
    [](const Future<void>& future) {
      if (future.error() == Error::Ok) {
        std::cout << "DocumentSnapshot successfully written!\n";
      } else {
        std::cout << "Error writing document: " << future.error_message()
                  << '\n';
      }
    });snippets.cpp

Node.js

let data = {
  stringExample: 'Hello, World!',
  booleanExample: true,
  numberExample: 3.14159265,
  dateExample: admin.firestore.Timestamp.fromDate(new Date('December 10, 1815')),
  arrayExample: [5, true, 'hello'],
  nullExample: null,
  objectExample: {
    a: 5,
    b: true
  }
};

let setDoc = db.collection('data').doc('one').set(data);index.js

Go

doc := make(map[string]interface{})
doc["stringExample"] = "Hello world!"
doc["booleanExample"] = true
doc["numberExample"] = 3.14159265
doc["dateExample"] = time.Now()
doc["arrayExample"] = []interface{}{5, true, "hello"}
doc["nullExample"] = nil
doc["objectExample"] = map[string]interface{}{
	"a": 5,
	"b": true,
}

_, err := client.Collection("data").Doc("one").Set(ctx, doc)
if err != nil {
	// Handle any errors in an appropriate way, such as returning them.
	log.Printf("An error has occurred: %s", err)
}save.go

PHP

$data = [
    'stringExample' => 'Hello World',
    'booleanExample' => true,
    'numberExample' => 3.14159265,
    'dateExample' => new Timestamp(new DateTime()),
    'arrayExample' => array(5, true, 'hello'),
    'nullExample' => null,
    'objectExample' => ['a' => 5, 'b' => true],
    'documentReferenceExample' => $db->collection('data')->document('two'),
];
$db->collection('data')->document('one')->set($data);
printf('Set multiple data-type data for the one document in the data collection.' . PHP_EOL);add_doc_data_types.php

Unity

DocumentReference docRef = db.Collection("data").Document("one");
Dictionary<string, object> docData = new Dictionary<string, object>
{
	{ "stringExample", "Hello World" },
	{ "booleanExample", false },
	{ "numberExample", 3.14159265 },
	{ "nullExample", null },
	{ "arrayExample", new List<object>() { 5, true, "Hello" } },
	{ "objectExample", new Dictionary<string, object>
		{
			{ "a", 5 },
			{ "b", true },
		}
	},
};

docRef.SetAsync(docData);

C#

DocumentReference docRef = db.Collection("data").Document("one");
Dictionary<string, object> docData = new Dictionary<string, object>
{
    { "stringExample", "Hello World" },
    { "booleanExample", false },
    { "numberExample", 3.14159265 },
    { "nullExample", null },
};

ArrayList arrayExample = new ArrayList();
arrayExample.Add(5);
arrayExample.Add(true);
arrayExample.Add("Hello");
docData.Add("arrayExample", arrayExample);

Dictionary<string, object> objectExample = new Dictionary<string, object>
{
    { "a", 5 },
    { "b", true },
};
docData.Add("objectExample", objectExample);

await docRef.SetAsync(docData);Program.cs

Ruby

doc_ref = firestore.doc "data/one"

data = {
  stringExample:  "Hello, World!",
  booleanExample: true,
  numberExample:  3.14159265,
  dateExample:    DateTime.now,
  arrayExample:   [5, true, "hello"],
  nullExample:    nil,
  objectExample:  {
    a: 5,
    b: true
  }
}

doc_ref.set dataadd_data.rb

Custom objects

Using Map or Dictionary objects to represent your documents is often not very convenient, so Cloud Firestore supports writing documents with custom classes. Cloud Firestore converts the objects to supported data types.

Using custom classes, you could rewrite the initial example as follows:

Web

To use a custom class, you must define a FirestoreDataConverter function for your class. For example:

class City {
    constructor (name, state, country ) {
        this.name = name;
        this.state = state;
        this.country = country;
    }
    toString() {
        return this.name + ', ' + this.state + ', ' + this.country;
    }
}

    // Firestore data converter
  cityConverter = {
      toFirestore: function(city) {
          return {
              name: city.name,
              state: city.state,
              country: city.country
              }
      },
      fromFirestore: function(snapshot, options){
          const data = snapshot.data(options);
          return new City(data.name, data.state, data.country)
      }
  }test.firestore.js

Swift

public struct City: Codable {

    let name: String
    let state: String?
    let country: String?
    let isCapital: Bool?
    let population: Int64?

    enum CodingKeys: String, CodingKey {
        case name
        case state
        case country
        case isCapital = "capital"
        case population
    }

}ViewController.swift

Objective-C

// This isn't supported in Objective-C.

Java

Each custom class must have a public constructor that takes no arguments. In addition, the class must include a public getter for each property.

public class City {


    private String name;
    private String state;
    private String country;
    private boolean capital;
    private long population;
    private List<String> regions;

    public City() {}

    public City(String name, String state, String country, boolean capital, long population, List<String> regions) {
        // ...
    }

    public String getName() {
        return name;
    }

    public String getState() {
        return state;
    }

    public String getCountry() {
        return country;
    }

    public boolean isCapital() {
        return capital;
    }

    public long getPopulation() {
        return population;
    }

    public List<String> getRegions() {
        return regions;
    }

}DocSnippets.java

Kotlin+KTX

data class City(
    val name: String? = null,
    val state: String? = null,
    val country: String? = null,
    val isCapital: Boolean? = null,
    val population: Long? = null,
    val regions: List<String>? = null
)DocSnippets.kt

Java

public City() {
  // Must have a public no-argument constructor
}

// Initialize all fields of a city
public City(String name, String state, String country,
            Boolean capital, Long population, List<String> regions) {
  this.name = name;
  this.state = state;
  this.country = country;
  this.capital = capital;
  this.population = population;
  this.regions = regions;
}City.java

Python

class City(object):
    def __init__(self, name, state, country, capital=False, population=0,
                 regions=[]):
        self.name = name
        self.state = state
        self.country = country
        self.capital = capital
        self.population = population
        self.regions = regions

    @staticmethod
    def from_dict(source):
        # ...

    def to_dict(self):
        # ...

    def __repr__(self):
        return(
            u'City(name={}, country={}, population={}, capital={}, regions={})'
            .format(self.name, self.country, self.population, self.capital,
                    self.regions))snippets.py

C++

// This is not yet supported.

Node.js

// Node.js uses JavaScript objects

Go


// City represents a city.
type City struct {
	Name       string   `firestore:"name,omitempty"`
	State      string   `firestore:"state,omitempty"`
	Country    string   `firestore:"country,omitempty"`
	Capital    bool     `firestore:"capital,omitempty"`
	Population int64    `firestore:"population,omitempty"`
	Regions    []string `firestore:"regions,omitempty"`
}
main.go

PHP

// This isn't supported in PHP

Unity

[FirestoreData]
public class City
{
	[FirestoreProperty]
	public string Name { get; set; }

	[FirestoreProperty]
	public string State { get; set; }

	[FirestoreProperty]
	public string Country { get; set; }

	[FirestoreProperty]
	public bool Capital { get; set; }

	[FirestoreProperty]
	public long Population { get; set; }
}

C#

[FirestoreData]
public class City
{
    [FirestoreProperty]
    public string Name { get; set; }

    [FirestoreProperty]
    public string State { get; set; }

    [FirestoreProperty]
    public string Country { get; set; }

    [FirestoreProperty]
    public bool Capital { get; set; }

    [FirestoreProperty]
    public long Population { get; set; }
}Program.cs

Ruby

// This isn't supported in Ruby

Web

Call your data converter with your write operation:

// Set with cityConverter
db.collection("cities").doc("LA")
  .withConverter(cityConverter)
  .set(new City("Los Angeles", "CA", "USA"));test.firestore.js

Swift

let city = City(name: "Los Angeles",
                state: "CA",
                country: "USA",
                isCapital: false,
                population: 5000000)

do {
    try db.collection("cities").document("LA").setData(from: city)
} catch let error {
    print("Error writing city to Firestore: \(error)")
}ViewController.swift

Objective-C

// This isn't supported in Objective-C.

Java

City city = new City("Los Angeles", "CA", "USA",
        false, 5000000L, Arrays.asList("west_coast", "sorcal"));
db.collection("cities").document("LA").set(city);DocSnippets.java

Kotlin+KTX

val city = City("Los Angeles", "CA", "USA",
        false, 5000000L, listOf("west_coast", "socal"))
db.collection("cities").document("LA").set(city)DocSnippets.kt

Java

City city = new City("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 required
System.out.println("Update time : " + future.get().getUpdateTime());ManageDataSnippets.java

Python

city = City(name=u'Los Angeles', state=u'CA', country=u'USA')
db.collection(u'cities').document(u'LA').set(city.to_dict())snippets.py

C++

// This is not yet supported.

Node.js

// Node.js uses JavaScript objects

Go

city := City{
	Name:    "Los Angeles",
	Country: "USA",
}
_, err := client.Collection("cities").Doc("LA").Set(ctx, city)
if err != nil {
	// Handle any errors in an appropriate way, such as returning them.
	log.Printf("An error has occurred: %s", err)
}save.go

PHP

// This isn't supported in PHP.

Unity

DocumentReference docRef = db.Collection("cities").Document("LA");
City city = new City
{
	Name = "Los Angeles",
	State = "CA",
	Country = "USA",
	Capital = false,
	Population = 3900000L
};
docRef.SetAsync(city);

C#

DocumentReference docRef = db.Collection("cities").Document("LA");
City city = new City
{
    Name = "Los Angeles",
    State = "CA",
    Country = "USA",
    Capital = false,
    Population = 3900000L
};
await docRef.SetAsync(city);Program.cs

Ruby

// This isn't supported in Ruby.

Add a document

When you use set() to create a document, you must specify an ID for the document to create. For example:

Web

db.collection("cities").doc("new-city-id").set(data);test.firestore.js

Swift

db.collection("cities").document("new-city-id").setData(data)ViewController.swift

Objective-C

[[[self.db collectionWithPath:@"cities"] documentWithPath:@"new-city-id"]
    setData:data];ViewController.m

Java

db.collection("cities").document("new-city-id").set(data);DocSnippets.java

Kotlin+KTX

db.collection("cities").document("new-city-id").set(data)DocSnippets.kt

Java

db.collection("cities").document("new-city-id").set(data);ManageDataSnippets.java

Python

db.collection(u'cities').document(u'new-city-id').set(data)snippets.py

C++

db->Collection("cities").Document("SF").Set({/*some data*/});snippets.cpp

Node.js

db.collection('cities').doc('new-city-id').set(data);index.js

Go

_, err := client.Collection("cities").Doc("new-city-id").Set(ctx, data)
if err != nil {
	// Handle any errors in an appropriate way, such as returning them.
	log.Printf("An error has occurred: %s", err)
}save.go

PHP

$db->collection('cities')->document('new-city-id')->set($data);set_requires_id.php

Unity

db.Collection("cities").Document("new-city-id").SetAsync(city);

C#

await db.Collection("cities").Document("new-city-id").SetAsync(city);Program.cs

Ruby

city_ref = firestore.doc "cities/new-city-id"
city_ref.set dataadd_data.rb

But sometimes there isn't a meaningful ID for the document, and it's more convenient to let Cloud Firestore auto-generate an ID for you. You can do this by calling add():

Web

// Add a new document with a generated id.
db.collection("cities").add({
    name: "Tokyo",
    country: "Japan"
})
.then(function(docRef) {
    console.log("Document written with ID: ", docRef.id);
})
.catch(function(error) {
    console.error("Error adding document: ", error);
});test.firestore.js

Swift

// Add a new document with a generated id.
var ref: DocumentReference? = nil
ref = db.collection("cities").addDocument(data: [
    "name": "Tokyo",
    "country": "Japan"
]) { err in
    if let err = err {
        print("Error adding document: \(err)")
    } else {
        print("Document added with ID: \(ref!.documentID)")
    }
}ViewController.swift

Objective-C

// Add a new document with a generated id.
__block FIRDocumentReference *ref =
    [[self.db collectionWithPath:@"cities"] addDocumentWithData:@{
      @"name": @"Tokyo",
      @"country": @"Japan"
    } completion:^(NSError * _Nullable error) {
      if (error != nil) {
        NSLog(@"Error adding document: %@", error);
      } else {
        NSLog(@"Document added with ID: %@", ref.documentID);
      }
    }];ViewController.m

Java

// Add a new document with a generated id.
Map<String, Object> data = new HashMap<>();
data.put("name", "Tokyo");
data.put("country", "Japan");

db.collection("cities")
        .add(data)
        .addOnSuccessListener(new OnSuccessListener<DocumentReference>() {
            @Override
            public void onSuccess(DocumentReference documentReference) {
                Log.d(TAG, "DocumentSnapshot written with ID: " + documentReference.getId());
            }
        })
        .addOnFailureListener(new OnFailureListener() {
            @Override
            public void onFailure(@NonNull Exception e) {
                Log.w(TAG, "Error adding document", e);
            }
        });DocSnippets.java

Kotlin+KTX

// Add a new document with a generated id.
val data = 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)
    }DocSnippets.kt

Java

// Add document data with auto-generated id.
Map<String, Object> data = new HashMap<>();
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());ManageDataSnippets.java

Python

city = City(name=u'Tokyo', state=None, country=u'Japan')
db.collection(u'cities').add(city.to_dict())snippets.py

C++

db->Collection("cities").Add({/*some data*/});snippets.cpp

Node.js

// Add a new document with a generated id.
let addDoc = db.collection('cities').add({
  name: 'Tokyo',
  country: 'Japan'
}).then(ref => {
  console.log('Added document with ID: ', ref.id);
});index.js

Go

_, _, err := client.Collection("cities").Add(ctx, map[string]interface{}{
	"name":    "Tokyo",
	"country": "Japan",
})
if err != nil {
	// Handle any errors in an appropriate way, such as returning them.
	log.Printf("An error has occurred: %s", err)
}save.go

PHP

$data = [
    'name' => 'Tokyo',
    'country' => 'Japan'
];
$addedDocRef = $db->collection('cities')->add($data);
printf('Added document with ID: %s' . PHP_EOL, $addedDocRef->id());add_doc_data_with_auto_id.php

Unity

Dictionary<string, object> city = new Dictionary<string, object>
{
	{ "Name", "Tokyo" },
	{ "Country", "Japan" }
};
db.Collection("cities").AddAsync(city).ContinueWithOnMainThread(task => {
	DocumentReference addedDocRef = task.Result;
	Debug.Log(String.Format("Added document with ID: {0}.", addedDocRef.Id));
});

C#

Dictionary<string, object> city = new Dictionary<string, object>
{
    { "Name", "Tokyo" },
    { "Country", "Japan" }
};
DocumentReference addedDocRef = await db.Collection("cities").AddAsync(city);
Console.WriteLine("Added document with ID: {0}.", addedDocRef.Id);Program.cs

Ruby

data = {
  name:    "Tokyo",
  country: "Japan"
}

cities_ref = firestore.col "cities"

added_doc_ref = cities_ref.add data
puts "Added document with ID: #{added_doc_ref.document_id}."add_data.rb

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 call doc():

Web

// Add a new document with a generated id.
var newCityRef = db.collection("cities").doc();

// later...
newCityRef.set(data);test.firestore.js

Swift

let newCityRef = db.collection("cities").document()

// later...
newCityRef.setData([
    // ...
])ViewController.swift

Objective-C

FIRDocumentReference *newCityRef = [[self.db collectionWithPath:@"cities"] documentWithAutoID];
// later...
[newCityRef setData:@{ /* ... */ }];ViewController.m

Java

Map<String, Object> data = new HashMap<>();

DocumentReference newCityRef = db.collection("cities").document();

// Later...
newCityRef.set(data);DocSnippets.java

Kotlin+KTX

val data = HashMap<String, Any>()

val newCityRef = db.collection("cities").document()

// Later...
newCityRef.set(data)DocSnippets.kt

Java

// Add document data after generating an id.
DocumentReference addedDocRef = db.collection("cities").document();
System.out.println("Added document with ID: " + addedDocRef.getId());

// later...
ApiFuture<WriteResult> writeResult = addedDocRef.set(data);ManageDataSnippets.java

Python

new_city_ref = db.collection(u'cities').document()

# later...
new_city_ref.set({
    # ...
})snippets.py

C++

DocumentReference new_city_ref = db->Collection("cities").Document();snippets.cpp

Node.js

let newCityRef = db.collection('cities').doc();

// Later...
let setDoc = newCityRef.set({
  // ...
});index.js

Go

ref := client.Collection("cities").NewDoc()

// later...
_, err := ref.Set(ctx, data)
if err != nil {
	// Handle any errors in an appropriate way, such as returning them.
	log.Printf("An error has occurred: %s", err)
}save.go

PHP

$addedDocRef = $db->collection('cities')->newDocument();
printf('Added document with ID: %s' . PHP_EOL, $addedDocRef->id());
$addedDocRef->set($data);add_doc_data_after_auto_id.php

Unity

DocumentReference addedDocRef = 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#

DocumentReference addedDocRef = db.Collection("cities").Document();
Console.WriteLine("Added document with ID: {0}.", addedDocRef.Id);
await addedDocRef.SetAsync(city);Program.cs

Ruby

cities_ref = firestore.col "cities"

added_doc_ref = cities_ref.doc
puts "Added document with ID: #{added_doc_ref.document_id}."

added_doc_ref.set dataadd_data.rb

Behind the scenes, .add(...) and .doc().set(...) are completely equivalent, so you can use whichever is more convenient.

Update a document

To update some fields of a document without overwriting the entire document, use the update() method:

Web

var washingtonRef = db.collection("cities").doc("DC");

// Set the "capital" field of the city 'DC'
return washingtonRef.update({
    capital: true
})
.then(function() {
    console.log("Document successfully updated!");
})
.catch(function(error) {
    // The document probably doesn't exist.
    console.error("Error updating document: ", error);
});test.firestore.js

Swift

let washingtonRef = db.collection("cities").document("DC")

// Set the "capital" field of the city 'DC'
washingtonRef.updateData([
    "capital": true
]) { err in
    if let err = err {
        print("Error updating document: \(err)")
    } else {
        print("Document successfully updated")
    }
}ViewController.swift

Objective-C

FIRDocumentReference *washingtonRef =
    [[self.db collectionWithPath:@"cities"] documentWithPath:@"DC"];
// Set the "capital" field of the city
[washingtonRef updateData:@{
  @"capital": @YES
} completion:^(NSError * _Nullable error) {
  if (error != nil) {
    NSLog(@"Error updating document: %@", error);
  } else {
    NSLog(@"Document successfully updated");
  }
}];ViewController.m

Java

DocumentReference washingtonRef = db.collection("cities").document("DC");

// Set the "isCapital" field of the city 'DC'
washingtonRef
        .update("capital", true)
        .addOnSuccessListener(new OnSuccessListener<Void>() {
            @Override
            public void onSuccess(Void aVoid) {
                Log.d(TAG, "DocumentSnapshot successfully updated!");
            }
        })
        .addOnFailureListener(new OnFailureListener() {
            @Override
            public void onFailure(@NonNull Exception e) {
                Log.w(TAG, "Error updating document", e);
            }
        });DocSnippets.java

Kotlin+KTX

val washingtonRef = 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) }DocSnippets.kt

Java

// Update an existing document
DocumentReference docRef = db.collection("cities").document("DC");

// (async) Update one field
ApiFuture<WriteResult> future = docRef.update("capital", true);

// ...
WriteResult result = future.get();
System.out.println("Write result: " + result);ManageDataSnippets.java

Python

city_ref = db.collection(u'cities').document(u'DC')

# Set the capital field
city_ref.update({u'capital': True})snippets.py

C++

DocumentReference washington_ref = db->Collection("cities").Document("DC");
// Set the "capital" field of the city "DC".
washington_ref.Update({{"capital", FieldValue::FromBoolean(true)}});snippets.cpp

Node.js

let cityRef = db.collection('cities').doc('DC');

// Set the 'capital' field of the city
let updateSingle = cityRef.update({capital: true});index.js

Go

_, err := client.Collection("cities").Doc("DC").Set(ctx, map[string]interface{}{
	"capital": true,
}, firestore.MergeAll)
if err != nil {
	// Handle any errors in an appropriate way, such as returning them.
	log.Printf("An error has occurred: %s", err)
}save.go

PHP

$cityRef = $db->collection('cities')->document('DC');
$cityRef->update([
    ['path' => 'capital', 'value' => true]
]);update_doc.php

Unity

DocumentReference cityRef = db.Collection("cities").Document("new-city-id");
Dictionary<string, object> updates = new Dictionary<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#

DocumentReference cityRef = db.Collection("cities").Document("new-city-id");
Dictionary<string, object> updates = new Dictionary<string, object>
{
    { "Capital", false }
};
await cityRef.UpdateAsync(updates);

// You can also update a single field with: await cityRef.UpdateAsync("Capital", false);Program.cs

Ruby

city_ref = firestore.doc "cities/DC"
city_ref.update capital: trueadd_data.rb

Server Timestamp

You can set a field in your document to a server timestamp which tracks when the server receives the update.

Web

var docRef = db.collection('objects').doc('some-id');

// Update the timestamp field with the value from the server
var updateTimestamp = docRef.update({
    timestamp: firebase.firestore.FieldValue.serverTimestamp()
});test.firestore.js

Swift

db.collection("objects").document("some-id").updateData([
    "lastUpdated": FieldValue.serverTimestamp(),
]) { err in
    if let err = err {
        print("Error updating document: \(err)")
    } else {
        print("Document successfully updated")
    }
}ViewController.swift

Objective-C

[[[self.db collectionWithPath:@"objects"] documentWithPath:@"some-id"] updateData:@{
  @"lastUpdated": [FIRFieldValue fieldValueForServerTimestamp]
} completion:^(NSError * _Nullable error) {
  if (error != nil) {
    NSLog(@"Error updating document: %@", error);
  } else {
    NSLog(@"Document successfully updated");
  }
}];ViewController.m

Java

// 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.
DocumentReference docRef = db.collection("objects").document("some-id");

// Update the timestamp field with the value from the server
Map<String,Object> updates = new HashMap<>();
updates.put("timestamp", FieldValue.serverTimestamp());

docRef.update(updates).addOnCompleteListener(new OnCompleteListener<Void>() {
    // ...
    // ...DocSnippets.java

Kotlin+KTX

// 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.
val docRef = db.collection("objects").document("some-id")

// Update the timestamp field with the value from the server
val updates = hashMapOf<String, Any>(
        "timestamp" to FieldValue.serverTimestamp()
)

docRef.update(updates).addOnCompleteListener { }DocSnippets.kt

Java

DocumentReference docRef = db.collection("objects").document("some-id");
// Update the timestamp field with the value from the server
ApiFuture<WriteResult> writeResult = docRef.update("timestamp", FieldValue.serverTimestamp());
System.out.println("Update time : " + writeResult.get());ManageDataSnippets.java

Python

city_ref = db.collection(u'objects').document(u'some-id')
city_ref.update({
    u'timestamp': firestore.SERVER_TIMESTAMP
})snippets.py

C++

DocumentReference doc_ref = db->Collection("objects").Document("some-id");
doc_ref.Update({{"timestamp", FieldValue::ServerTimestamp()}})
    .OnCompletion([](const Future<void>& future) {
      // ...
    });snippets.cpp

Node.js

// Get the `FieldValue` object
let FieldValue = require('firebase-admin').firestore.FieldValue;

// Create a document reference
let docRef = db.collection('objects').doc('some-id');

// Update the timestamp field with the value from the server
let updateTimestamp = docRef.update({
  timestamp: FieldValue.serverTimestamp()
});index.js

Go

_, err := client.Collection("objects").Doc("some-id").Set(ctx, map[string]interface{}{
	"timestamp": firestore.ServerTimestamp,
}, firestore.MergeAll)
if err != nil {
	// Handle any errors in an appropriate way, such as returning them.
	log.Printf("An error has occurred: %s", err)
}save.go

PHP

$docRef = $db->collection('objects')->document('some-id');
$docRef->update([
    ['path' => 'timestamp', 'value' => FieldValue::serverTimestamp()]
]);update_server_timestamp.php

Unity

DocumentReference cityRef = 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.");
	});

C#

DocumentReference cityRef = db.Collection("cities").Document("new-city-id");
await cityRef.UpdateAsync("Timestamp", Timestamp.GetCurrentTimestamp());Program.cs

Ruby

city_ref = firestore.doc "cities/new-city-id"
city_ref.update timestamp: firestore.field_server_timeadd_data.rb

Update fields in nested objects

If your document contains nested objects, you can use "dot notation" to reference nested fields within the document when you call update():

Web

// Create an initial document to update.
var frankDocRef = 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(function() {
    console.log("Document successfully updated!");
});test.firestore.js

Swift

// Create an initial document to update.
let frankDocRef = db.collection("users").document("frank")
frankDocRef.setData([
    "name": "Frank",
    "favorites": [ "food": "Pizza", "color": "Blue", "subject": "recess" ],
    "age": 12
    ])

// To update age and favorite color:
db.collection("users").document("frank").updateData([
    "age": 13,
    "favorites.color": "Red"
]) { err in
    if let err = err {
        print("Error updating document: \(err)")
    } else {
        print("Document successfully updated")
    }
}ViewController.swift

Objective-C

// Create an initial document to update.
FIRDocumentReference *frankDocRef =
    [[self.db collectionWithPath:@"users"] documentWithPath:@"frank"];
[frankDocRef setData:@{
  @"name": @"Frank",
  @"favorites": @{
    @"food": @"Pizza",
    @"color": @"Blue",
    @"subject": @"recess"
  },
  @"age": @12
}];
// To update age and favorite color:
[frankDocRef updateData:@{
  @"age": @13,
  @"favorites.color": @"Red",
} completion:^(NSError * _Nullable error) {
  if (error != nil) {
    NSLog(@"Error updating document: %@", error);
  } else {
    NSLog(@"Document successfully updated");
  }
}];ViewController.m

Java

// Assume the document contains:
// {
//   name: "Frank",
//   favorites: { food: "Pizza", color: "Blue", subject: "recess" }
//   age: 12
// }
//
// To update age and favorite color:
db.collection("users").document("frank")
        .update(
                "age", 13,
                "favorites.color", "Red"
        );DocSnippets.java

Kotlin+KTX

// Assume the document contains:
// {
//   name: "Frank",
//   favorites: { food: "Pizza", color: "Blue", subject: "recess" }
//   age: 12
// }
//
// To update age and favorite color:
db.collection("users").document("frank")
        .update(mapOf(
                "age" to 13,
                "favorites.color" to "Red"
        ))DocSnippets.kt

Java

// Create an initial document to update
DocumentReference frankDocRef = db.collection("users").document("frank");
Map<String, Object> initialData = new HashMap<>();
initialData.put("name", "Frank");
initialData.put("age", 12);

Map<String, Object> favorites = new HashMap<>();
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 operation
initialResult.get();

// Update age and favorite color
Map<String, Object> updates = new HashMap<>();
updates.put("age", 13);
updates.put("favorites.color", "Red");

// Async update document
ApiFuture<WriteResult> writeResult = frankDocRef.update(updates);
// ...
System.out.println("Update time : " + writeResult.get().getUpdateTime());ManageDataSnippets.java

Python

# Create an initial document to update
frank_ref = db.collection(u'users').document(u'frank')
frank_ref.set({
    u'name': u'Frank',
    u'favorites': {
        u'food': u'Pizza',
        u'color': u'Blue',
        u'subject': u'Recess'
    },
    u'age': 12
})

# Update age and favorite color
frank_ref.update({
    u'age': 13,
    u'favorites.color': u'Red'
})snippets.py

C++

// Assume the document contains:
// {
//   name: "Frank",
//   favorites: { food: "Pizza", color: "Blue", subject: "recess" }
//   age: 12
// }
//
// To update age and favorite color:
db->Collection("users").Document("frank").Update({
    {"age", FieldValue::FromInteger(13)},
    {"favorites.color", FieldValue::FromString("red")},
});snippets.cpp

Node.js

let initialData = {
  name: 'Frank',
  age: 12,
  favorites: {
    food: 'Pizza',
    color: 'Blue',
    subject: 'recess'
  }
};

// ...
let updateNested = db.collection('users').doc('Frank').update({
  age: 13,
  'favorites.color': 'Red'
});index.js

Go

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)
if err != nil {
	// Handle any errors in an appropriate way, such as returning them.
	log.Printf("An error has occurred: %s", err)
}save.go

PHP

// Create an initial document to update
$frankRef = $db->collection('users')->document('frank');
$frankRef->set([
    'name' => 'Frank',
    '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']
]);update_nested_fields.php

Unity

DocumentReference frankDocRef = db.Collection("users").Document("frank");
Dictionary<string, object> initialData = new Dictionary<string, object>
{
	{ "Name", "Frank" },
	{ "Age", 12 }
};

Dictionary<string, object> favorites = new Dictionary<string, object>
{
	{ "Food", "Pizza" },
	{ "Color", "Blue" },
	{ "Subject", "Recess" },
};
initialData.Add("Favorites", favorites);
frankDocRef.SetAsync(initialData).ContinueWithOnMainThread(task => {

	// Update age and favorite color
	Dictionary<string, object> updates = new Dictionary<string, object>
	{
		{ "Age", 13 },
		{ "Favorites.Color", "Red" },
	};

	// Asynchronously update the document
	return frankDocRef.UpdateAsync(updates);
}).ContinueWithOnMainThread(task => {
	Debug.Log(
		"Updated the age and favorite color fields of the Frank document in "
		+ "the users collection.");
});

C#

DocumentReference frankDocRef = db.Collection("users").Document("frank");
Dictionary<string, object> initialData = new Dictionary<string, object>
{
    { "Name", "Frank" },
    { "Age", 12 }
};

Dictionary<string, object> favorites = new Dictionary<string, object>
{
    { "Food", "Pizza" },
    { "Color", "Blue" },
    { "Subject", "Recess" },
};
initialData.Add("Favorites", favorites);
await frankDocRef.SetAsync(initialData);

// Update age and favorite color
Dictionary<string, object> updates = new Dictionary<string, object>
{
    { "Age", 13 },
    { "Favorites.Color", "Red" },
};

// Asynchronously update the document
await frankDocRef.UpdateAsync(updates);Program.cs

Ruby

# Create an initial document to update
frank_ref = firestore.doc "users/frank"
frank_ref.set(
  name:      "Frank",
  favorites: {
    food:    "Pizza",
    color:   "Blue",
    subject: "Recess"
  },
  age:       12
)

# Update age and favorite color
frank_ref.update age: 13, "favorites.color": "Red"add_data.rb

Dot notation allows you to update a single nested field without overwriting other nested field. If you update a nested field without dot notation, you will overwrite the entire map field, for example:

Web


// Create our initial doc
db.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");
});

/*
Ending State, favorite.color and favorite.subject are no longer present:
/users
    /frank
        {
            name: "Frank",
            favorites: {
                food: "Ice Cream",
            },
            age: 12
        }
 */

Update elements in an array

If your document contains an array field, you can use arrayUnion() and arrayRemove() 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

var washingtonRef = 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")
});test.firestore.js

Swift

let washingtonRef = 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"])
])ViewController.swift

Objective-C

FIRDocumentReference *washingtonRef =
    [[self.db collectionWithPath:@"cities"] documentWithPath:@"DC"];

// Atomically add a new region to the "regions" array field.
[washingtonRef updateData:@{
  @"regions": [FIRFieldValue fieldValueForArrayUnion:@[@"greater_virginia"]]
}];

// Atomically remove a new region to the "regions" array field.
[washingtonRef updateData:@{
  @"regions": [FIRFieldValue fieldValueForArrayRemove:@[@"east_coast"]]
}];ViewController.m

Java

DocumentReference washingtonRef = 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"));DocSnippets.java

Kotlin+KTX

val washingtonRef = 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"))DocSnippets.kt

Java

DocumentReference washingtonRef = 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());ManageDataSnippets.java

Python

city_ref = db.collection(u'cities').document(u'DC')

# Atomically add a new region to the 'regions' array field.
city_ref.update({u'regions': firestore.ArrayUnion([u'greater_virginia'])})

# // Atomically remove a region from the 'regions' array field.
city_ref.update({u'regions': firestore.ArrayRemove([u'east_coast'])})snippets.py

C++

// This is not yet supported.

Node.js

let admin = require('firebase-admin');
// ...
let washingtonRef = db.collection('cities').doc('DC');

// Atomically add a new region to the "regions" array field.
let arrUnion = washingtonRef.update({
  regions: admin.firestore.FieldValue.arrayUnion('greater_virginia')
});
// Atomically remove a region from the "regions" array field.
let arrRm = washingtonRef.update({
  regions: admin.firestore.FieldValue.arrayRemove('east_coast')
});index.js

Go

// Not supported yet

PHP

$cityRef = $db->collection('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'])]
]);update_doc_array.php

Unity

// This is not yet supported in the Unity SDK

C#

DocumentReference washingtonRef = db.Collection("cities").Document("DC");

// Atomically add a new region to the "regions" array field.
await washingtonRef.UpdateAsync("Regions", FieldValue.ArrayUnion("greater_virginia"));

// Atomically remove a region from the "regions" array field.
await washingtonRef.UpdateAsync("Regions", FieldValue.ArrayRemove("east_coast"));Program.cs

Ruby

// Not supported yet

Increment a numeric value

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. If the field does not exist or if the current field value is not a numeric value, the operation sets the field to the given value.

Web

var washingtonRef = db.collection('cities').doc('DC');

// Atomically increment the population of the city by 50.
washingtonRef.update({
    population: firebase.firestore.FieldValue.increment(50)
});test.firestore.js

Swift

let washingtonRef = 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))
])ViewController.swift

Objective-C

FIRDocumentReference *washingtonRef =
    [[self.db collectionWithPath:@"cities"] documentWithPath:@"DC"];

// Atomically increment the population of the city by 50.
// Note that increment() with no arguments increments by 1.
[washingtonRef updateData:@{
  @"population": [FIRFieldValue fieldValueForIntegerIncrement:50]
}];ViewController.m

Java

DocumentReference washingtonRef = db.collection("cities").document("DC");

// Atomically increment the population of the city by 50.
washingtonRef.update("population", FieldValue.increment(50));DocSnippets.java

Kotlin+KTX

val washingtonRef = db.collection("cities").document("DC")

// Atomically increment the population of the city by 50.
washingtonRef.update("population", FieldValue.increment(50))DocSnippets.kt

Java

DocumentReference washingtonRef = db.collection("cities").document("DC");

// Atomically increment the population of the city by 50.
final ApiFuture<WriteResult> updateFuture = washingtonRef
    .update("population", FieldValue.increment(50));ManageDataSnippets.java

Python

washington_ref = db.collection(u'cities').document(u'DC')

washington_ref.update({"population": firestore.Increment(50)})snippets.py

C++

// This is not yet supported.

Node.js

let admin = require('firebase-admin');
// ...
let washingtonRef = db.collection('cities').doc('DC');

// Atomically increment the population of the city by 50.
let popIncrement = washingtonRef.update({
  population: admin.firestore.FieldValue.increment(50)
});index.js

Go

import (
	"context"
	"fmt"

	"cloud.google.com/go/firestore"
)

// updateDocumentIncrement increments the population of the DC document in the
// cities collection by 50.
func updateDocumentIncrement(projectID string) error {
	// projectID := "my-project"

	ctx := context.Background()

	client, err := firestore.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("firestore.NewClient: %v", err)
	}

	dc := client.Collection("cities").Doc("DC")
	_, err = dc.Update(ctx, []firestore.Update{
		{Path: "population", Value: firestore.Increment(50)},
	})
	if err != nil {
		return fmt.Errorf("Update: %v", err)
	}

	return nil
}
increment.go

PHP

$cityRef = $db->collection('cities')->document('DC');

// Atomically increment the population of the city by 50.
$cityRef->update([
    ['path' => 'regions', 'value' => FieldValue::incremet(50)]
]);update_doc_increment.php

Unity

// This is not yet supported in the Unity SDK.

C#

DocumentReference washingtonRef = db.Collection("cities").Document("DC");

// Atomically increment the population of the city by 50.
await washingtonRef.UpdateAsync("Regions", FieldValue.Increment(50));Program.cs

Ruby

city_ref = firestore.doc "cities/DC"
city_ref.update population: firestore.field_increment(50)add_data.rb

Increment operations are useful for implementing counters, but keep in mind that you can update a single document only once per second. If you need to update your counter above this rate, see the Distributed counters page.