Firestore Add Data

The contents of this page are based on the original Firebase Documentation

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 setData method:

db.collection("cities").document("LA").set({
    "name": "Los Angeles",
    "state": "CA",
    "country": "USA"
}, function onDocAdded(path:String, error:FirestoreError):void {
    if (error) {
        trace("Error getting documents: " + error);
    } else {
        trace("Document successfully written!");
    }
});

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:

db.collection("cities").document("BJ").setData({"capital": true}, null, true);

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.

Add a document

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

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

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 addDocument():

var ref: DocumentReference;
ref = db.collection("cities").addDocument({
    "name": "Tokyo",
    "country": "Japan"});

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 document():

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

// later...
newCityRef.setData({
    // ...
});

Behind the scenes, .addDocument(...) and .document() .setData(...) 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 updateData() method:

var washingtonRef:DocumentReference = db.collection("cities").document("DC");
washingtonRef.updateData({"capital": true});

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 updateData():

// Create an initial document to update.
var frankDocRef:DocumentReference = 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"
});

Server Timestamp

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

db.collection("objects").document("some-id").updateData({
    "lastUpdated": FieldValue.serverTimestamp()
});

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.

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

// Atomically increment the population of the city by 50.
washingtonRef.updateData({
    "population": FieldValue.increment(50)
});