Navigation

Database Triggers

Overview

Database triggers allow you to execute server-side logic whenever a document is added, updated, or removed in a linked MongoDB cluster. You can use database triggers to implement complex data interactions, including updating information in one document when a related document changes or interacting with a service when a new document is inserted.

Database triggers use MongoDB change streams to listen for changes in watched collections and map them to database events. Stitch will only open change streams for collections with at least one enabled trigger.

Note

Database triggers are only available for MongoDB Clusters that are running MongoDB version 3.6 or newer.

Create a Database Trigger

To create a database trigger in the Stitch UI:

  1. Click Triggers under MongoDB Cluster in the left-hand navigation.
  2. Select the Database Triggers tab.
  3. Click Add Database Trigger in the top right to open the trigger configuration page.
  4. Enter configuration values for the trigger and click Save at the bottom of the page.

To create a database trigger with stitch-cli:

  1. Add a database trigger configuration file to the triggers subdirectory of a local application directory.

  2. Import the application directory into your application.

    stitch-cli import
    

Note

Stitch does not enforce specific filenames for trigger configuration files. However, once imported, Stitch will rename each configuration file to match the name of the trigger it defines, e.g. mytrigger.json.

Reference

Database Trigger Configuration

Database triggers have the following configuration parameters:

Configuration files for database triggers have the following form:

/triggers/<trigger name>.json
{
   "type": <string>,
   "name": <string>,
   "function_name": <string>,
   "config": {
     "service_name": <string>,
     "database": <string>,
     "collection": <string>,
     "operation_types": [<string>, ...],
     "full_document": <boolean>,
     "match": <document>
   },
   "disabled": <boolean>
}
Field Description

Trigger Type

type
Required. The type of the trigger. For database triggers, this value should be set to DATABASE.

Trigger Name

name
Required. The name of the trigger.

Linked Function

function_name
Required. The name of the Stitch function that the trigger executes whenever it fires. The trigger passes the database event object that caused it to fire as the only argument to this function.

Cluster

config.service_name
Required. The name of the MongoDB Service that the trigger is associated with.

Database Name

config.database
Required. The MongoDB database that contains the watched collection.

Collection Name

config.collection
Required. The name of the collection that the trigger watches for change events.

Operation Types

config.operation_types
Required. A list of one or more database operation types that cause the trigger to fire. Each operation type must be formatted as a fully-capitalized string, e.g. "INSERT".

Full Document

config.full_document

Required. If true, indicates that UPDATE change events should include the most current majority-committed version of the modified document in the fullDocument field.

Note

This option only affects UPDATE change events. INSERT and REPLACE events always include the fullDocument field. DELETE events never include the fullDocument field. For more information, see the change events reference page.

Warning

Update operations executed from MongoDB Compass or the MongoDB Atlas Data Explorer fully replace the previous document. As a result, update operations from these clients will generate REPLACE change events rather than UPDATE events.

Match Expression

config.match
Optional. A $match expression document that Stitch includes in the underlying change stream pipeline for the trigger. This is useful when you want to filter change events beyond their operation type. The trigger will only fire if the expression evaluates to true for a given change event.

Database Change Events

Database change events represent individual changes in a specific collection of your linked MongoDB cluster.

Every database event has the same operation type and structure as the change event object that was emitted by the underlying change stream. Change events have the following operation types:

Operation Type Description
INSERT Represents a new document that was added to the collection.
UPDATE Represents a change to an existing document in the collection.
REPLACE Represents a new document that replaced a document in the collection.
DELETE Represents a document that was deleted from the collection.

Database change event objects have the following general form:

{
   _id : <ObjectId>,
   "operationType": <string>,
   "fullDocument": <document>,
   "ns": {
      "db" : <string>,
      "coll" : <string>
   },
   "documentKey": {
     "_id": <ObjectId>
   },
   "updateDescription": <document>,
   "clusterTime": <Timestamp>
}

Database Trigger Limitations

Stitch limits the number of database triggers that you can create for each linked cluster in your application. The limit is based on the size of the cluster.

Cluster Size Maximum Number of Triggers
M0 5
M2 10
M5 10
M10 100
M20 100
M30+ 1000
R40+ 1000