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.

You can use a $match expression document to filter change events based on field values. For more information, see Query on Embedded Documents in the MongoDB server manual.

Example

An online store wants to notify its customers whenever one of their orders changes location. They record each order in the store.orders collection as a document that resembles the following:

{
  _id: ObjectId("59cf1860a95168b8f685e378"),
  customerId: ObjectId("59cf17e1a95168b8f685e377"),
  orderDate: ISODate("2018-06-26T16:20:42.313Z"),
  shipDate: ISODate("2018-06-27T08:20:23.311Z"),
  orderContents: [
    { qty: 1, name: "Earl Grey Tea Bags - 100ct", price: NumberDecimal("10.99") }
  ],
  shippingLocation: [
    { location: "Memphis", time: ISODate("2018-06-27T18:22:33.243Z") },
  ]
}

To automate this process, the store creates a database Trigger that listens for UPDATE change events in the store.orders collection. When the trigger observes an UPDATE event, it passes the change event object to its associated Function, textShippingUpdate. The Function checks the change event for any changes to the shippingLocation field and, if it was updated, sends a text message to the customer with the new location of the order.

exports = async function (changeEvent) {
  // Destructure out fields from the change stream event object
  const { updateDescription, fullDocument } = changeEvent;
  // Check if the shippingLocation field was updated
  const updatedFields = Object.keys(updateDescription.updatedFields);
  const isNewLocation = updatedFields.some(field =>
    field.match(/shippingLocation/)
  );
  // If the location changed, text the customer the updated location.
  if (isNewLocation) {
    const { customerId, shippingLocation } = fullDocument;
    const twilio = context.services.get("myTwilioService");
    const mongodb = context.services.get("mongodb-atlas");
    const customers = mongodb.db("store").collection("customers");
    const { location } = shippingLocation.pop();
    const customer = await customers.findOne({ _id: customer_id })
    twilio.send({
      to: customer.phoneNumber,
      from: context.values.get("ourPhoneNumber"),
      body: `Your order has moved! The new location is ${location}.`
    });
  }
};

Configuration

Database Triggers have the following configuration options:

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

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

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

Database change event objects have the following general form:

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

Suspended Triggers

Database Triggers may enter a suspended state in response to an event that prevents the Trigger's change stream from continuing. Events that can suspend a Trigger include:

• invalidate events such as dropDatabase, renameCollection, or those caused by a network disruption
• the token required to resume the change stream is no longer in the cluster oplog
• importing a Realm app with the replace strategy instead of the merge strategy and consequently removing the database user that created the Trigger's change stream

When resuming the suspended Trigger, Realm attempts to resume the Trigger at the next change stream event after the change stream stopped. However, if the resume token is no longer in the cluster oplog, the Trigger begins listening to new events but does not process any missed past events. You can adjust your oplog size to keep the resume token around for more time after a suspension.

Last Cluster Time Processed

All Triggers keep track of the last time the Trigger executed, known as the latest execution in the Realm UI. Database Triggers also keep track of the last cluster time processed: the last time the change stream backing that Trigger emitted an event. You can access these timestamps in the list of Triggers that displays when you first navigate to the Triggers section from the sidebar.

The difference between the latest execution and the last cluster time processed represents the latency between when an event occurs in your database, and when the Trigger finishes responding to that event. If latency is consistently large, you can reduce it with the following mitigations:

• Optimize the Trigger's Linked Function to speed up execution.
• If your Trigger uses Event Ordering, consider switching ordering off to reduce latency.
• Add resources by upgrading your MongoDB Atlas cluster.