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.
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.
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.
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
.
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.

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.
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.

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 Note This option only affects 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 | |||||||||||||
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
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
| |||||||||||||
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:
The change event object that Realm passes to the trigger function only includes the fields specifed in the projection, as in the following example:
|
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> }