Docs Menu

Docs HomeAtlas App Services

Document Preimages

On this page

  • Overview
  • Performance
  • Enable Document Preimages
  • View Preimage-Enabled Collections
  • Disable Preimages for a Collection

Every database trigger execution has a related change event. You can configure these change events to include document preimages. A preimage is a snapshot of a document before a change.

Example

Consider updateOne in a collection with preimages:

pets.updateOne(
{ name: "Fido" },
{ $inc: { age: 1 } }
)

Preimages add the following data to write operation change events

  • the document preimage in the fullDocumentBeforeChange field

    Preimage - the full document as it existed before the change
    {
    "name": "Fido",
    "age": 3
    }
  • the document postimage in the fullDocument field

    Postimage - the full document immediately after the change
    {
    "name": "Fido",
    "age": 4
    }

For clusters running MongoDB version 6.0 and newer, triggers use the cluster's built-in change stream preimages feature. Older versions of MongoDB store preimages directly in the oplog. Both of these add storage and compute overhead for each operation on the collection which may cause performance issues for collections with a high write throughput.

You can enable preimages when you configure a database trigger. Document Preimage is a setting on trigger configuration. Toggle this to enable document preimages for the collection.

To view the list of collections that store document preimages:

  1. Navigate to the Linked Data Source configuration screen.

  2. Expand the Advanced Configuration section.

This section contains the Preimage Preferences by Collection table.

This table lists every collection that stores preimages in the oplog. Enabling preimages for a collection applies to all collections. This includes collections tied to triggers in a different App. Collections with no triggers that use preimages also appear here.

You can disable collection-level preimages in the App Services UI.

To disable preimages for a collection:

  1. (Optional) Disable document preimages for triggers in the collection. Triggers with preimages continue to fire after disabling preimages. But they don't have the fullDocumentBeforeChange field in change events. This includes triggers in other App Services Apps.

  2. Terminate sync, if the collection is part of a synced cluster.

  3. View the Preimage Preferences By Collection table. Press the Disable button for a collection. This turns off preimages for that collection.

  4. Re-enable Sync, if the collection is part of a synced cluster.

Warning

Restore Sync after Terminating Sync

When you terminate and re-enable Atlas Device Sync, clients can no longer Sync. Your client must implement a client reset handler to restore Sync. This handler can discard or attempt to recover unsynchronized changes.

←  Wire ProtocolInternal Database Usage →