Database Triggers¶

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.

Important

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:

Click Triggers under MongoDB Cluster in the left navigation menu.
Select the Database Triggers tab.
Click Add Database Trigger in the top right to open the Trigger configuration page.
Enter configuration values for the Trigger and click Save at the bottom of the page.

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.

A database trigger that is marked Suspended in the UI

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.

Note

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.

The resume database trigger modal in the UI

Reference¶

Database Trigger Configuration¶

Database Triggers have the following configuration parameters:

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.

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.

Note

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.

{
  "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:

{
  "_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:

{
  "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:

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

Give Feedback

← Triggers Authentication Triggers →