Firestore triggers
You can configure your Cloud Run functions to be triggered by events in a Firestore database. Once triggered, your function can read and update a Firestore database in response to these events through the Firestore APIs and client libraries.
In a typical lifecycle, a Firestore function does the following:
Waits for changes to a particular document.
Triggers when an event occurs and performs its tasks.
Receives a data object with a snapshot of the affected document. For
write
orupdate
events, the data object contains snapshots representing document state before and after the triggering event.
Event types
Firestore supports create
, update
, delete
, and write
events. The
write
event encompasses all modifications to a document.
Event type | Trigger |
---|---|
google.cloud.firestore.document.v1.created (default) |
Triggered when a document is written to for the first time. |
google.cloud.firestore.document.v1.updated |
Triggered when a document already exists and has any value changed. |
google.cloud.firestore.document.v1.deleted |
Triggered when a document with data is deleted. |
google.cloud.firestore.document.v1.written |
Triggered when a document is created, updated or deleted. |
Wildcards are written in triggers using curly braces, as follows:
"projects/YOUR_PROJECT_ID/databases/(default)/documents/collection/{document_wildcard}"
Specify the document path
To trigger your function, specify a document path to listen to. The document path must be in the same Google Cloud project as the function.
Here are a few examples of valid document paths:
users/marie
: valid trigger. Monitors a single document,/users/marie
.users/{username}
: valid trigger. Monitors all user documents. Wildcards are used to monitor all documents in the collection.users/{username}/addresses
: invalid trigger. Refers to the subcollectionaddresses
, not a document.users/{username}/addresses/home
: valid trigger. Monitors the home address document for all users.users/{username}/addresses/{addressId}
: valid trigger. Monitors all address documents.users/{user=**}
: valid trigger. Monitors all user documents and any documents in subcollections under each user document such as/users/userID/address/home
or/users/userID/phone/work
.
Wildcards and parameters
If you don't know the specific document you want to monitor, use a {wildcard}
instead of the document ID:
users/{username}
listens for changes to all user documents.
In this example, when any field on any document in users
is changed, it
matches a wildcard called {username}
.
If a document in users
has
subcollections, and a
field in one of those subcollections' documents is changed, the {username}
wildcard is not triggered. If your goal is to respond to events in
subcollections also, use the multi-segment wildcard {username=**}
.
Wildcard matches are extracted from document paths. You can define as many
wildcards as you like to substitute explicit collection or document IDs. You can
use up to one multi-segment wildcard like {username=**}
.
Event structures
This trigger invokes your function with an event similar to this:
{ "oldValue": { // Update and Delete operations only A Document object containing a pre-operation document snapshot }, "updateMask": { // Update operations only A DocumentMask object that lists changed fields. }, "value": { // A Document object containing a post-operation document snapshot } }
Each Document
object contains one or more Value
objects. See the
Value
documentation
for type references. This is especially useful if you're using a typed language
(like Go) to write your functions.
Examples
The following examples demonstrate how to write functions that respond to a Firestore trigger.
Before you begin
- Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Google Cloud project.
-
Enable the Cloud Functions, Cloud Build, Artifact Registry, Eventarc, Logging, Pub/Sub, and Cloud Run APIs.
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Google Cloud project.
-
Enable the Cloud Functions, Cloud Build, Artifact Registry, Eventarc, Logging, Pub/Sub, and Cloud Run APIs.
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
- Prepare your development environment.
If you already have the gcloud CLI installed, update it by running the following command:
gcloud components update
Set up your Firestore database
You need a Firestore database to test the samples in this document. It must be in place before you deploy your functions. If you don't already have a Firestore database, create one as follows:
Go to the Firestore Data page.
Click Select Native Mode.
Choose the region (location) where your database is to reside. This choice is permanent.
Click Create database.
The Firestore data model consists of collections that contain documents. A document contains a set of key-value pairs.
The functions you create in this tutorial are triggered when you make changes to a document inside of a specified collection.
Example 1: Hello Firestore function
The following sample Cloud Run function prints the fields of a triggering Firestore event:
Node.js
Use protobufjs to decode the event
data. Include the google.events.cloud.firestore.v1
data.proto
in your source.
Python
Go
Java
C#
Deploy the Hello Firestore function
If you haven't already done so, set up your Firestore database.
To deploy the Hello Firestore function with a Firestore trigger, run the following command in the directory that contains the sample code (or in the case of Java, the
pom.xml
file):gcloud functions deploy FUNCTION_NAME \ --gen2 \ --runtime=RUNTIME \ --region=REGION \ --trigger-location=TRIGGER REGION \ --source=. \ --entry-point=ENTRY_POINT \ --trigger-event-filters=type=google.cloud.firestore.document.v1.written \ --trigger-event-filters=database='(default)' \ --trigger-event-filters-path-pattern=document='users/{username}'
Replace the following:
FUNCTION_NAME
: A name for your deployed function.RUNTIME
: The language runtime your function uses.REGION
: The region in which to deploy your function.TRIGGER_REGION
: The location of the trigger, which must be the same as the region of the Firestore database.ENTRY_POINT
: The entry point to your function in your source code. This is the code that is executed when your function runs.
Use the other fields as is:
--trigger-event-filters=type=google.cloud.firestore.document.v1.written
specifies that the function is triggered when a document is created, updated or deleted, per thegoogle.cloud.firestore.document.v1.written
event type.--trigger-event-filters=database='(default)'
specifies the Firebase database. For the default database name, use(default)
.--trigger-event-filters-path-pattern=document='users/{username}'
provides the path pattern of the documents that should be monitored for relevant changes. This path pattern states that all documents in theusers
collection should be monitored. For more information, see Understand path patterns.
Test the Hello Firestore function
To test the Hello Firestore function, set up a collection called
users
in your Firestore database:
On the Firestore data page, click Start a collection.
Specify
users
as the collection ID.To start adding the collection's first document, under Add its first document accept the auto-generated Document ID.
Add at least one field for the document, specifying a name and value. In this example the name is "username" and the value is "rowan:"
When you're done, click Save.
This action creates a new document, thereby triggering your function.
To confirm that your function was triggered, click the linked name of the function in the Google Cloud console Cloud Run functions Overview page to open the Function details page.
Open the Logs tab and look for this string:
Function triggered by change to: //firestore.googleapis.com/projects/your-project-id/databases/(default)'
Example 2: Convert to Uppercase function
This example retrieves the value added by the user, converts the string at that location to uppercase, and replaces the value with the uppercase string:
Node.js
Use protobufjs to decode the event
data. Include the google.events.cloud.firestore.v1
data.proto
in your source.
Python
Go
Java
C#
Deploy the Convert to Uppercase function
If you haven't already done so, set up your Firestore database.
Use the following command to deploy a function that is triggered by write events on the document
companies/{CompanyId}
:gcloud functions deploy FUNCTION_NAME \ --gen2 \ --runtime=RUNTIME \ --trigger-location=TRIGGER REGION \ --region=REGION \ --source=. \ --entry-point=ENTRY_POINT \ --set-env-vars GOOGLE_CLOUD_PROJECT=PROJECT_ID \ --trigger-event-filters=type=google.cloud.firestore.document.v1.written \ --trigger-event-filters=database='(default)' \ --trigger-event-filters-path-pattern=document='messages/{pushId}'
Replace the following:
FUNCTION_NAME
: A name for your deployed function.RUNTIME
: The language runtime your function uses.REGION
: The region in which to deploy your function.TRIGGER_REGION
: The location of the trigger, which must be the same as the region of the Firestore database.ENTRY_POINT
: The entry point to your function in your source code. This is the code that is executed when your function runs.PROJECT_ID
: The unique identifier of the project.
Use the other fields as is:
--trigger-event-filters=type=google.cloud.firestore.document.v1.written
specifies that the function is triggered when a document is created, updated or deleted, per thegoogle.cloud.firestore.document.v1.written
event type.--trigger-event-filters=database='(default)'
specifies the Firestore database. For the default database name, use(default)
.--trigger-event-filters-path-pattern=document='messages/{pushId}'
provides the path pattern of the documents that should be monitored for relevant changes. This path pattern states that all documents in themessages
collection should be monitored. For more information, see Understand path patterns.
Test the Convert to Uppercase function
To test the Convert to Uppercase function you just deployed, set up
a collection called messages
in your
Firestore database:
Go to the Firestore data page.
Click Start a collection.
Specify
messages
as the collection ID.To start adding the collection's first document, under Add its first document accept the auto-generated Document ID.
To trigger your deployed function, add a document where the field name is "original" and the field value is a lowercase word, for example:
When you save the document, you can see the lowercase word in the value field convert to uppercase.
If you subsequently edit the field value to contain lowercase letters, that triggers the function again, converting all lowercase letters to uppercase.
Limitations
- Ordering is not guaranteed. Rapid changes can trigger function invocations in an unexpected order.
- Events are delivered at least once, but a single event may result in multiple function invocations. Avoid depending on exactly-once mechanics, and write idempotent functions.
- A trigger is associated with a single database. You cannot create a trigger that matches multiple databases.
- Deleting a database does not automatically delete any triggers for that database. The trigger stops delivering events but continues to exist until you delete the trigger.