replace Event

Document Pre- and Post-Images

Starting in MongoDB 6.0, you see a fullDocumentBeforeChange document with the fields before the document was changed (or deleted) if you perform these steps:

1. Enable the new changeStreamPreAndPostImages field for a collection using db.createCollection(), create, or collMod.

2. Set fullDocumentBeforeChange to "required" or "whenAvailable" in db.collection.watch().

Example fullDocumentBeforeChange document in the change stream output:

"fullDocumentBeforeChange" : {
   "_id" : ObjectId("599af247bb69cd89961c986d"),
   "userName" : "alice123",
   "name" : "Alice Smith"
}

For complete examples with the change stream output, see Change Streams with Document Pre- and Post-Images.

Pre- and post-images are not available for a change stream event if the images were:

• Not enabled on the collection at the time of a document update or delete operation.

• Removed after the pre- and post-image retention time set in expireAfterSeconds.

  • The following example sets expireAfterSeconds to 100 seconds on an entire cluster:

    use admin
    db.runCommand( {
       setClusterParameter:
          { changeStreamOptions: {
             preAndPostImages: { expireAfterSeconds: 100 }
          } }
    } )

  • The following example returns the current changeStreamOptions settings, including expireAfterSeconds:

    db.adminCommand( { getClusterParameter: "changeStreamOptions" } )

  • Setting expireAfterSeconds to off uses the default retention policy: pre- and post-images are retained until the corresponding change stream events are removed from the oplog.

  • If a change stream event is removed from the oplog, then the corresponding pre- and post-images are also deleted regardless of the expireAfterSeconds pre- and post-image retention time.

Additional considerations:

• Enabling pre- and post-images consumes storage space and adds processing time. Only enable pre- and post-images if you need them.

• Limit the change stream event size to less than 16 mebibytes. To limit the event size, you can:

  • Limit the document size to 8 megabytes. You can request pre- and post-images simultaneously in the change stream output if other change stream event fields like updateDescription are not large.

  • Request only post-images in the change stream output for documents up to 16 mebibytes if other change stream event fields like updateDescription are not large.

  • Request only pre-images in the change stream output for documents up to 16 mebibytes if:

    • document updates affect only a small fraction of the document structure or content, and

    • do not cause a replace change event. A replace event always includes the post-image.

• To request a pre-image, you set fullDocumentBeforeChange to required or whenAvailable in db.collection.watch(). To request a post-image, you set fullDocument using the same method.

• Pre-images are written to the config.system.preimages collection.

  • The config.system.preimages collection may become large. To limit the collection size, you can set expireAfterSeconds time for the pre-images as shown earlier.

  • Pre-images are removed asynchronously by a background process.