Database Triggers

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.


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

To open the database trigger configuration screen in the Realm UI, click Triggers in the left navigation menu, select the Database Triggers tab, and then click Add a Trigger.

Configure the trigger and then click Save at the bottom of the page to add it to your current deployment draft.

A database trigger has the following configuration options:

Trigger Type
Required. The type of the Trigger. Set this value to DATABASE for database Triggers
Trigger Name
Required. The name of the Trigger.
Linked Function
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.
Required. The name of the MongoDB Service that the Trigger is associated with.
Database Name
Required. The MongoDB database that contains the watched collection.
Collection Name
Required. The name of the collection that the Trigger watches for change events.
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

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


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.


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

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.


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


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.


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


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


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


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

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.

The resume database trigger modal in the UI

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
Represents a new document added to the collection.
Represents a change to an existing document in the collection.
Represents a new document that replaced a document in the collection.
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