Navigation

Database Triggers

On this page

Overview

Database Triggers allow you to execute server-side logic whenever a document is added, updated, or removed in a linked MongoDB Atlas 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 upon the insertion of a new document.

Database Triggers use MongoDB change streams to listen for changes to documents in a collection and pass database events to their associated Trigger function.

Change Stream Limitations

MongoDB Realm opens a single change stream for each collection with at least one enabled Trigger and limits the total number of open change streams on each linked cluster across all Realm apps based on the cluster’s size. See change stream limitations for more information.

Note

Database Triggers are only available for MongoDB Atlas clusters that are running MongoDB version 3.6 or newer.

Create a Database Trigger

To create a database Trigger in the Realm 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.
../../_images/db-trigger-example-config-1.png
../../_images/db-trigger-example-config-2.png

To create a database trigger with realm-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.

    copy 
    realm-cli import

Note

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

Restart a Database Trigger

Database Triggers may enter a suspended state in response to an event that prevents the Trigger’s change stream from continuing, such as a network disruption or change to the underlying cluster. When a Trigger enters a suspended state, it does not receive change events and will not fire.

Note

In the event of a suspended or failed trigger, Realm sends the project owner an email alerting them of the issue.

You can attempt to restart a suspended Trigger from the Realm UI or by importing an application directory with realm-cli.

1

Find the Suspended Trigger

On the Database Triggers tab of the Triggers page, find the trigger that you want to resume in the list of triggers. MongoDB Realm marks suspended triggers with a Status of Suspended.

../../_images/suspended-db-trigger.png
2

Restart the Trigger

Click Restart in the trigger’s Actions column. You can choose to restart the trigger with a change stream resume token or open a new change stream. Indicate whether or not to use a resume token and then click Resume Database Trigger.

Resume Tokens

If you use a resume token, Realm attempts to resume the trigger’s underlying change stream at the event immediately following the last change event it processed. If successful, the trigger processes any events that occurred while it was suspended. If you do not use a resume token, the trigger begins listening for new events but will not fire for any events that occurred while it was suspended.

../../_images/resume-database-trigger-modal.png
1

Export Your Realm Application

MongoDB Realm automatically attempts to resume any suspended triggers included in an imported application directory. To begin restarting a suspended trigger, export a copy of your application from the Export tab of the Settings page in the Realm UI, or by running the following command from an authenticated instance of realm-cli:

copy 
realm-cli export --app-id=<App ID>.
2

Verify that the Trigger Configuration File Exists

If you exported a new copy of your application, it should already include an up-to-date configuration file for the suspended trigger. You can confirm that the configuration file exists by looking in the /triggers directory for a trigger configuration file with the same name as the trigger.

3

Import Your Application Directory

After you have verified that the trigger configuration file exists, import the trigger configuration by running the following command from the root of your exported application directory:

copy 
realm-cli import

Reference

Database Trigger Configuration

Database Triggers have the following configuration parameters:

Configuration files for database Triggers have the following form:

copy
/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>,
     "unordered": <boolean>,
     "match": <document>,
     "project": <document>
   },
   "disabled": <boolean>
}
Field Description

Trigger Type

type
 Required. The type of the Trigger. Set this value to DATABASE for database Triggers

Trigger Name

name
 Required. The name of the Trigger.

Linked Function

function_name
 Required. The name of the Realm 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. Format each operation type 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.

Event Ordering

config.unordered

Default: Enabled.

Indicates whether event ordering is enabled for this Trigger.

Optional. Default: false.

If true, indicates that event ordering is disabled for this trigger.

If event ordering is enabled, multiple executions of this Trigger will occur sequentially based on the timestamps of the change events. If event ordering is disabled, multiple executions of this Trigger will occur independently.

Tip

Consider disabling event ordering if your trigger fires on a collection that receives short bursts of events (e.g. inserting data as part of a daily batch job).

Ordered Triggers wait to execute a Function for a particular event until the Functions of previous events have finished executing. As a consequence, ordered Triggers are effectively rate-limited by the run time of each sequential Trigger function. This may cause a significant delay between the database event and the Trigger firing if a sufficiently large number of Trigger executions are currently in the queue.

Unordered Triggers execute functions in parallel if possible, which can be significantly faster (depending on your use case) but does not guarantee that multiple executions of a Trigger Function occur in event order.

Match Expression

config.match

Optional. A $match expression document that Realm uses to filter which change events cause the Trigger to fire. The Trigger evaluates all change event objects that it receives against this match expression and only executes if the expression evaluates to true for a given change event.

Use Dot-Notation for Embedded Fields

MongoDB performs a full equality match for embedded documents in a match expression. If you want to match a specific field in an embedded document, refer to the field directly using dot-notation. For more information, see Query on Embedded Documents in the MongoDB server manual.

Example

The following Match Expression configures a trigger to fire only if the change event object specifies that the status field in a document changed.

copy 
{
  "updateDescription.updatedFields.status": {
    "$exists": true
  }
}

Project Expression

config.project

Optional. A $project expression document that Realm uses to filter the fields that appear in change event objects.

Example

A trigger is configured with the following Project Expression:

copy 
{
  "_id": 0,
  "operationType": 1,
  "updateDescription.updatedFields.status": 1
}

The change event object that Realm passes to the trigger function only includes the fields specifed in the projection, as in the following example:

copy 
{
  "operationType": "update",
  "updateDescription": {
    "updatedFields": {
      "status": "InProgress"
    }
  }
}

Database Change Events

Database change events represent individual changes in a specific collection of your linked MongoDB Atlas 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 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 deleted from the collection.

Database change event objects have the following general form:

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

© MongoDB, Inc 2008-present. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc.