Cloud Firestore triggers

With Cloud Functions, you can handle events in Cloud Firestore with no need to update client code. You can make Cloud Firestore changes via the DocumentSnapshot interface or via the Admin SDK.

In a typical lifecycle, a Cloud Firestore function does the following:

1. Waits for changes to a particular document.
2. Triggers when an event occurs and performs its tasks (see What can I do with Cloud Functions? for examples of use cases).
3. Receives a data object that contains a snapshot of the data stored in the specified document. For onWrite or onUpdate events, the data object contains two snapshots that represent the data state before and after the triggering event.

Distance between the location of the Firestore instance and the location of the function can create significant network latency. To optimize performance, consider specifying the function location where applicable.

Cloud Firestore function triggers

The Cloud Functions for Firebase SDK exports a functions.firestore object that allows you to create handlers tied to specific Cloud Firestore events.

If you don't have a project enabled for Cloud Functions for Firebase yet, then read Get Started: Write and Deploy Your First Functions to configure and set up your Cloud Functions for Firebase project.

Writing Cloud Firestore-triggered functions

Define a function trigger

To define a Cloud Firestore trigger, specify a document path and an event type:

const functions = require('firebase-functions');

exports.myFunction = functions.firestore
  .document('...')
  .onWrite((change, context) => { /* ... */ });

Document paths can reference either a specific document or a wildcard pattern.

Specify a single document

If you want to trigger an event for any change to a specific document then you can use the following function.

// Listen for any change on document `marie` in collection `users`
exports.myFunctionName = functions.firestore
    .document('users/marie').onWrite((change, context) => {
      // ... Your code here
    });
index.js

Specify a group of documents using wildcards

If you want to attach a trigger to a group of documents, such as any document in a certain collection, then use a {wildcard} in place of the document ID:

// Listen for changes in all documents in the 'users' collection
exports.useWildcard = functions.firestore
    .document('users/{userId}')
    .onWrite((change, context) => {
      // If we set `/users/marie` to {name: "Marie"} then
      // context.params.userId == "marie"
      // ... and ...
      // change.after.data() == {name: "Marie"}
    });
index.js

In this example, when any field on any document in users is changed, it matches a wildcard called userId.

If a document in users has subcollections, and a field in one of those subcollections' documents is changed, the userId wildcard is not triggered.

Wildcard matches are extracted from the document path and stored into context.params. You may define as many wildcards as you like to substitute explicit collection or document IDs, for example:

// Listen for changes in all documents in the 'users' collection and all subcollections
exports.useMultipleWildcards = functions.firestore
    .document('users/{userId}/{messageCollectionId}/{messageId}')
    .onWrite((change, context) => {
      // If we set `/users/marie/incoming_messages/134` to {body: "Hello"} then
      // context.params.userId == "marie";
      // context.params.messageCollectionId == "incoming_messages";
      // context.params.messageId == "134";
      // ... and ...
      // change.after.data() == {body: "Hello"}
    });
index.js

Event Triggers

Trigger a function when a new document is created

You can trigger a function to fire any time a new document is created in a collection by using an onCreate() handler with a wildcard. This example function calls createUser every time a new user profile is added:

exports.createUser = functions.firestore
    .document('users/{userId}')
    .onCreate((snap, context) => {
      // Get an object representing the document
      // e.g. {'name': 'Marie', 'age': 66}
      const newValue = snap.data();

      // access a particular field as you would any JS property
      const name = newValue.name;

      // perform desired operations ...
    });
index.js

Trigger a function when a document is updated

You can also trigger a function to fire when a document is updated using the onUpdate() function with a wildcard. This example function calls updateUser if a user changes their profile:

exports.updateUser = functions.firestore
    .document('users/{userId}')
    .onUpdate((change, context) => {
      // Get an object representing the document
      // e.g. {'name': 'Marie', 'age': 66}
      const newValue = change.after.data();

      // ...or the previous value before this update
      const previousValue = change.before.data();

      // access a particular field as you would any JS property
      const name = newValue.name;

      // perform desired operations ...
    });
index.js

Trigger a function when a document is deleted

You can also trigger a function when a document is deleted using the onDelete() function with a wildcard. This example function calls deleteUser when a user deletes their user profile:

exports.deleteUser = functions.firestore
    .document('users/{userID}')
    .onDelete((snap, context) => {
      // Get an object representing the document prior to deletion
      // e.g. {'name': 'Marie', 'age': 66}
      const deletedValue = snap.data();

      // perform desired operations ...
    });
index.js

Trigger a function for all changes to a document

If you don't care about the type of event being fired, you can listen for all changes in a Cloud Firestore document using the onWrite() function with a wildcard. This example function calls modifyUser if a user is created, updated, or deleted:

exports.modifyUser = functions.firestore
    .document('users/{userID}')
    .onWrite((change, context) => {
      // Get an object with the current document value.
      // If the document does not exist, it has been deleted.
      const document = change.after.exists ? change.after.data() : null;

      // Get an object with the previous document value (for update or delete)
      const oldDocument = change.before.data();

      // perform desired operations ...
    });
index.js

Reading and Writing Data

When a function is triggered, it provides a snapshot of the data related to the event. You can use this snapshot to read from or write to the document that triggered the event, or use the Firebase Admin SDK to access other parts of your database.

Event Data

Reading Data

When a function is triggered, you might want to get data from a document that was updated, or get the data prior to update. You can get the prior data by using change.before.data(), which contains the document snapshot before the update. Similarly, change.after.data() contains the document snapshot state after the update.

exports.updateUser = functions.firestore
    .document('users/{userId}')
    .onUpdate((change, context) => {
      // Get an object representing the current document
      const newValue = change.after.data();

      // ...or the previous value before this update
      const previousValue = change.before.data();
    });
index.js

You can access properties as you would in any other object. Alternatively, you can use the get function to access specific fields:

// Fetch data using standard accessors
const age = snap.data().age;
const name = snap.data()['name'];

// Fetch data using built in accessor
const experience = snap.get('experience');
index.js

Writing Data

Each function invocation is associated with a specific document in your Cloud Firestore database. You can access that document as a DocumentReference in the ref property of the snapshot returned to your function.

This DocumentReference comes from the Cloud Firestore Node.js SDK and includes methods like update(), set(), and remove() so you can easily modify the document that triggered the function.

// Listen for updates to any `user` document.
exports.countNameChanges = functions.firestore
    .document('users/{userId}')
    .onUpdate((change, context) => {
      // Retrieve the current and previous value
      const data = change.after.data();
      const previousData = change.before.data();

      // We'll only update if the name has changed.
      // This is crucial to prevent infinite loops.
      if (data.name == previousData.name) return null;

      // Retrieve the current count of name changes
      let count = data.name_change_count;
      if (!count) {
        count = 0;
      }

      // Then return a promise of a set operation to update the count
      return change.after.ref.set({
        name_change_count: count + 1
      }, {merge: true});
    });
index.js

Data outside the trigger event

Cloud Functions execute in a trusted environment, which means they are authorized as a service account on your project. You can perform reads and writes using the Firebase Admin SDK:

const admin = require('firebase-admin');
admin.initializeApp();

const db = admin.firestore();

exports.writeToFirestore = functions.firestore
  .document('some/doc')
  .onWrite((change, context) => {
    db.doc('some/otherdoc').set({ ... });
  });

Limitations and guarantees

While developing your applications, keep in mind that Cloud Firestore triggers are currently in beta which may result in unexpected behavior.

A few known limitations include:

• It may take up to 10 seconds for a function to be triggered after a change to Cloud Firestore data.
• As with all background functions, event ordering is not guaranteed. In addition, a single event may result in multiple Cloud Functions invocations, so for the highest quality ensure your functions are written to be idempotent.