Database Triggers

Automatically Resume a Suspended Trigger

You can configure a Trigger to automatically resume if the Trigger was suspended because the resume token is no longer in the oplog. The Trigger does not process any missed change stream events between when the resume token is lost and when the resume process completes.

Manually Resume a Suspended Trigger

When you manually resume a suspended Trigger, your App attempts to resume the Trigger at the next change stream event after the change stream stopped. If the resume token is no longer in the cluster oplog, the Trigger must be started without a resume token. This means the Trigger begins listening to new events but does not process any missed past events.

You can adjust the oplog size to keep the resume token for more time after a suspension by scaling your Atlas cluster. Maintain an oplog size a few times greater than your cluster's peak oplog throughput (GB/hour) to reduce the risk of a suspended trigger's resume token dropping off the oplog before the trigger executes. View your cluster's oplog throughput in the Oplog GB/Hour graph in the Atlas cluster metrics.

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

Disable Event Ordering for Burst Operations

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.

Disable Collection-Level Preimages

Document preimages require your cluster to record additional data about each operation on a collection. Once you enable preimages for any trigger on a collection, your cluster stores preimages for every operation on the collection.

The additional storage space and compute overhead may degrade trigger performance depending on your cluster configuration.

To avoid the storage and compute overhead of preimages, you must disable preimages for the entire underlying MongoDB collection. This is a separate setting from any individual trigger's preimage setting.

If you disable collection-level preimages, then no active trigger on that collection can use preimages. However, if you delete or disable all preimage triggers on a collection, then you can also disable collection-level preimages.

To learn how, see Disable Preimages for a Collection.

Use Match Expressions to Limit Trigger Invocations

You can limit the number of Trigger invocations by specifying a $match expression in the Match Expression field. App Services evaluates the match expression against the change event document and invokes the Trigger only if the expression evaluates to true for the given change event.

The match expression is a JSON document that specifies the query conditions using the MongoDB read query syntax.

We recommend only using match expressions when the volume of Trigger events measurably becomes a performance issue. Until then, receive all events and handle them individually in the Trigger function code.

The exact shape of the change event document depends on the event that caused the trigger to fire. For details, see the reference for each event type:

• insert

• update

• replace

• delete

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

{
  "fullDocument.needsTriggerResponse": true
}

Use Project Expressions to Reduce Input Data Size

In the Project Expression field, limit the number of fields that the Trigger processes by using a $project expression.

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

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