• Change Streams >
• Change Events

Change Events

Change Events

The following document represents all possible fields that a change stream response document can have.

copy

{
   _id : { <BSON Object> },
   "operationType" : "<operation>",
   "fullDocument" : { <document> },
   "fullDocumentBeforeChange" : { <document> },  // Added in MongoDB 6.0
   "ns" : {
      "db" : "<database>",
      "coll" : "<collection>"
   },
   "to" : {
      "db" : "<database>",
      "coll" : "<collection>"
   },
   "documentKey" : { "_id" : <value> },
   "updateDescription" : {
      "updatedFields" : { <document> },
      "removedFields" : [ "<field>", ... ],
      "truncatedArrays" : [
         { "field" : <field>, "newSize" : <integer> },
         ...
      ]
   },
   "operationDescription": { <document> },
   "collectionUUID": <uuid>,
   "clusterTime" : <Timestamp>,
   "wallTime" : <ISODate>,  // Added in MongoDB 6.0
   "txnNumber" : <NumberLong>,
   "lsid" : {
      "id" : <UUID>,
      "uid" : <BinData>
   }
}

Some fields are only available for certain operations, such as updates. The following table describes each field in the change stream response document:

Field	Type	Description
_id	document	A BSON object which serves as an identifier for the change stream event. This value is used as the resumeToken for the resumeAfter parameter when resuming a change stream. The _id object has the following form: copy { "_data" : <BinData|hex string> } The _data type depends on the MongoDB versions and, in some cases, the feature compatibility version (fCV) at the time of the change stream’s opening/resumption. See Resume Tokens for the full list of _data types. See Resume a Change Stream for an example of resuming a change stream by resumeToken.
operationType	string	The type of operation that occurred. Can be any of the following values: insert delete replace update drop rename dropDatabase invalidate createIndexes dropIndexes create modify shardCollection
fullDocument	document	The document created or modified by the insert, replace, delete, update operations (i.e. CRUD operations). For insert and replace operations, this represents the new document created by the operation. For delete operations, this field is omitted as the document no longer exists. For update operations, this field only appears if you configured the change stream with fullDocument set to updateLookup. This field then represents the most current majority-committed version of the document modified by the update operation. This document may differ from the changes described in updateDescription if other majority-committed operations modified the document between the original update operation and the full document lookup. Starting in MongoDB 6.0, if you enable the changeStreamPreAndPostImages field using db.createCollection(), create, or collMod, then fullDocument is the document after it was inserted, replaced, or updated (the document post-image). fullDocument is always included for insert events.
fullDocumentBeforeChange	document	The document before it was replaced, updated, or deleted (the document pre-image). To obtain fullDocumentBeforeChange, you must enable the changeStreamPreAndPostImages field for a collection using db.createCollection(), create, or collMod. New in version 6.0.
ns	document	The namespace (database and or collection) affected by the event.
ns.db	string	The name of the database.
ns.coll	string	The name of the collection. For dropDatabase operations, this field is omitted.
to	document	When operationType is rename, this document displays the new name for the ns collection. This document is omitted for all other values of operationType.
to.db	string	The new name of the database.
to.coll	string	The new name of the collection.
documentKey	document	A document that contains the _id of the document created or modified by the insert, replace, delete, update operations (i.e. CRUD operations). For sharded collections, also displays the full shard key for the document. The _id field is not repeated if it is already a part of the shard key.
updateDescription	document	A document describing the fields that were updated or removed by the update operation. This document and its fields only appears if the operationType is update.
updateDescription. updatedFields	document	A document whose keys correspond to the fields that were modified by the update operation. The value of each field corresponds to the new value of those fields, rather than the operation that resulted in the new value.
updateDescription. removedFields	array	An array of fields that were removed by the update operation.
updateDescription. truncatedArrays	array	An array of documents which record array truncations performed with pipeline-based updates using one or more of the following stages: $addFields $set $replaceRoot $replaceWith Note If the entire array is replaced, the truncations will be reported under updateDescription.updatedFields.
updateDescription. truncatedArrays. field	string	The name of the truncated field.
updateDescription. truncatedArrays. newSize	integer	The number of elements in the truncated array.
operationDescription	document	A document describing the operation performed. This document and its fields only appears for certain operationType values when the change stream uses expanded events. New in version 6.0.
operationDescription.dropTarget	UUID	Provides the UUID of the collection that was dropped in the rename operation. This field only appears when the operationType value is rename and when the rename operation sets a dropTarget value. New in version 6.0.
operationDescription.idIndex	document	The primary key index for a new collection. This field only appears when the operationType value is create. New in version 6.0.
operationDescription.index	document	Describes the index that was modified. This field only appears when the operationType value is modify. New in version 6.0.
operationDescription.indexes	array	An array of documents listing the indexes that were created or dropped by the operation. This field only appears when the operationType value is createIndexes or dropIndexes. New in version 6.0.
operationDescription.numInitialChunks	long	Numbers of chunks created on each shard during a shardCollection operation. This field only appears when the operationType value is shardCollection. New in version 6.0.
operationDescription.presplitHashedZones	boolean	Indicates whether the shards are pre-split into zones. This field only appears when the operationType value is shardCollection. New in version 6.0.
operationDescription.shardKey	document	Document showing the shard key for the collection. This field only appears when the operationType value is shardCollection. New in version 6.0.
operationDescription.to	document	When operationType : rename, this document displays the new name for the ns collection. This document is omitted for all other values of operationType. New in version 6.0.
operationDescription.to.db	string	Indicates the new dataname name of the renamed collection. New in version 6.0.
operationDescription.to.coll	string	Indicates the new collection name of the renamed collection. New in version 6.0.
operationDescription.unique	boolean	Indicates whether shard chunks were pre-split according to zones when the collection became sharded. This field only appears when the operationType value is shardCollection. New in version 6.0.
wallTime	ISODate	ISO date from the oplog entry associated with the event. New in version 6.0.
collectionUUID	UUID	UUID identifying the collection. New in version 6.0.
clusterTime	Timestamp	The timestamp from the oplog entry associated with the event. For events that happened as part of a multi-document transaction, the associated change stream notifications will have the same clusterTime value, namely the time when the transaction was committed. On a sharded cluster, events that occur on different shards can have the same clusterTime but be associated with different transactions or even not be associated with any transaction. To identify events for a single transaction, you can use the combination of lsid and txnNumber in the change stream event document. New in version 4.0.
wallTime	ISODate	The server date and time of the database operation. wallTime differs from clusterTime: clusterTime is the timestamp from the oplog entry associated with the database operation event. New in version 6.0.
txnNumber	NumberLong	The transaction number. Only present if the operation is part of a multi-document transaction. New in version 4.0.
lsid	Document	The identifier for the session associated with the transaction. Only present if the operation is part of a multi-document transaction. New in version 4.0.

insert Event

The following example illustrates an insert event:

copy

{
   _id: { < Resume Token > },
   operationType: 'insert',
   clusterTime: <Timestamp>,
   wallTime: <ISODate>,
   ns: {
      db: 'engineering',
      coll: 'users'
   },
   documentKey: {
      userName: 'alice123',
      _id: ObjectId("599af247bb69cd89961c986d")
   },
   fullDocument: {
      _id: ObjectId("599af247bb69cd89961c986d"),
      userName: 'alice123',
      name: 'Alice'
   }
}

The documentKey field includes both the _id and the userName field. This indicates that the engineering.users collection is sharded, with a shard key on userName and _id.

The fullDocument document represents the version of the document at the time of the insert.

update Event

The following example illustrates an update event:

copy

{
   _id: { < Resume Token > },
   operationType: 'update',
   clusterTime: <Timestamp>,
   wallTime: <ISODate>,
   ns: {
      db: 'engineering',
      coll: 'users'
   },
   documentKey: {
      _id: ObjectId("58a4eb4a30c75625e00d2820")
   },
   updateDescription: {
      updatedFields: {
         email: 'alice@10gen.com'
      },
      removedFields: ['phoneNumber'],
      truncatedArrays: [ {
         "field" : "vacation_time",
         "newSize" : 36
      } ]
   }
}

The following example illustrates an update event for change streams opened with the fullDocument : updateLookup option:

copy

{
   _id: { < Resume Token > },
   operationType: 'update',
   clusterTime: <Timestamp>,
   wallTime: <ISODate>,
   ns: {
      db: 'engineering',
      coll: 'users'
   },
   documentKey: {
      _id: ObjectId("58a4eb4a30c75625e00d2820")
   },
   updateDescription: {
      updatedFields: {
         email: 'alice@10gen.com'
      },
      removedFields: ['phoneNumber'],
      truncatedArrays: [ {
         "field" : "vacation_time",
         "newSize" : 36
      } ]
   },
   fullDocument: {
      _id: ObjectId("58a4eb4a30c75625e00d2820"),
      name: 'Alice',
      userName: 'alice123',
      email: 'alice@10gen.com',
      team: 'replication'
   }
}

The fullDocument document represents the most current majority-committed version of the updated document. The fullDocument document may vary from the document at the time of the update operation depending on the number of interleaving majority-committed operations that occur between the update operation and the document lookup.

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:

    copy

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

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

    copy

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

Important

Backward-Incompatible Feature

Starting in MongoDB 6.0, if you are using document pre- and post-images for change streams, you must disable changeStreamPreAndPostImages for each collection using the collMod command before you can downgrade to an earlier MongoDB version.

See also

• For change stream events and output, see Change Events.
• To watch a collection for changes, see db.collection.watch.
• For complete examples with the change stream output, see Change Streams with Document Pre- and Post-Images.

replace Event

The following example illustrates a replace event:

copy

{
   _id: { < Resume Token > },
   operationType: 'replace',
   clusterTime: <Timestamp>,
   wallTime: <ISODate>,
   ns: {
      db: 'engineering',
      coll: 'users'
   },
   documentKey: {
      _id: ObjectId("599af247bb69cd89961c986d")
   },
   fullDocument: {
      _id: ObjectId("599af247bb69cd89961c986d"),
      userName: 'alice123',
      name: 'Alice'
   }
}

A replace operation uses the update command, and consists of two stages:

• Delete the original document with the documentKey and
• Insert the new document using the same documentKey

The fullDocument of a replace event represents the document after the insert of the replacement document.

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:

    copy

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

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

    copy

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

Important

Backward-Incompatible Feature

Starting in MongoDB 6.0, if you are using document pre- and post-images for change streams, you must disable changeStreamPreAndPostImages for each collection using the collMod command before you can downgrade to an earlier MongoDB version.

See also

• For change stream events and output, see Change Events.
• To watch a collection for changes, see db.collection.watch.
• For complete examples with the change stream output, see Change Streams with Document Pre- and Post-Images.

delete Event

The following example illustrates a delete event:

copy

{
   _id: { < Resume Token > },
   operationType: 'delete',
   clusterTime: <Timestamp>,
   wallTime: <ISODate>,
   ns: {
      db: 'engineering',
      coll: 'users'
   },
   documentKey: {
      _id: ObjectId("599af247bb69cd89961c986d")
   }
}

The fullDocument document is omitted as the document no longer exists at the time the change stream cursor sends the delete event to the client.

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:

    copy

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

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

    copy

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

Important

Backward-Incompatible Feature

Starting in MongoDB 6.0, if you are using document pre- and post-images for change streams, you must disable changeStreamPreAndPostImages for each collection using the collMod command before you can downgrade to an earlier MongoDB version.

See also

• For change stream events and output, see Change Events.
• To watch a collection for changes, see db.collection.watch.
• For complete examples with the change stream output, see Change Streams with Document Pre- and Post-Images.

drop Event

New in version 4.0.1.

A drop event occurs when a collection is dropped from a database. The following example illustrates a drop event:

copy

{
   _id: { < Resume Token > },
   operationType: 'drop',
   clusterTime: <Timestamp>,
   wallTime: <ISODate>,
   ns: {
      db: 'engineering',
      coll: 'users'
   }
}

A drop event leads to an invalidate event for change streams opened against its ns collection.

rename Event

New in version 4.0.1.

A rename event occurs when a collection is renamed. The following example illustrates a rename event:

copy

{
   _id: { < Resume Token > },
   operationType: 'rename',
   clusterTime: <Timestamp>,
   wallTime: <ISODate>,
   ns: {
      db: 'engineering',
      coll: 'users'
   },
   to: {
      db: 'engineering',
      coll: 'people'
   },
   operationDescription: {
      to: {
         db: 'engineering',
         coll: 'people'
      }
   }
}

A rename event leads to an invalidate event for change streams opened against its ns collection or to collection.

Changed in version 6.0.

Starting in MongoDB 6.0, when the showExpandedEvents option is enabled for the change stream, the rename event includes an operationDescription document. This document provides a to field showing the changed database and collection and a dropTarget field indicating whether the rename operation removed the collection before the rename.

dropDatabase Event

New in version 4.0.1.

A dropDatabase event occurs when a database is dropped. The following example illustrates a dropDatabase event:

copy

{
   _id: { < Resume Token > },
   operationType: 'dropDatabase',
   clusterTime: <Timestamp>,
   wallTime: <ISODate>,
   ns: {
      db: 'engineering'
   }
}

A dropDatabase command generates a drop event for each collection in the database before generating a dropDatabase event for the database.

A dropDatabase event leads to an invalidate event for change streams opened against its ns.db database.

invalidate Event

The following example illustrates an invalidate event:

copy

{
   _id: { < Resume Token > },
   operationType: 'invalidate',
   clusterTime: <Timestamp>,
   wallTime: <ISODate>
}

For change streams opened up against a collection, a drop event, rename event, or dropDatabase event that affects the watched collection leads to an invalidate event.

For change streams opened up against a database, a dropDatabase event that affects the watched database leads to an invalidate event.

invalidate events close the change stream cursor.

You cannot use resumeAfter to resume a change stream after an invalidate event (for example, a collection drop or rename) closes the stream. Starting in MongoDB 4.2, you can use startAfter to start a new change stream after an invalidate event.

createIndexes Event

New in version 6.0.

A createIndexes event occurs when an index is created on the collection and the change stream has the showExpandedEvents option set to true.

The following example shows a createIndexes event:

copy

{
   _id: { <ResumeToken> },
   operationType: 'createIndexes',
   clusterTime: Timestamp({ t: 1651257835, i: 1 }),
   collectionUUID: UUID("06bced37-7cc8-4267-96aa-a58a422153d8"),
   wallTime: ISODate("2022-04-29T18:43:55.160Z"),
   ns: {
      db: 'test',
      coll: 'authors'
   },
   operationDescription: {
      indexes: [
         { v: 2, key: { name: 1 }, name: 'name_1' }
      ]
   }
}

dropIndexes Event

New in version 6.0.

A dropIndexes event occurs when an index is dropped from the collection and the change stream has the showExpandedEvents option set to true.

The following example shows a dropIndexes event:

copy

{
   _id: { <ResumeToken> },
   operationType: 'dropIndexes',
   clusterTime: <Timestamp>
   collectionUUID: <uuid>,
   wallTime: <isodate>,
   ns: {
      db: 'test',
      coll: 'authors' },
   operationDescription: {
      indexes: [
         { v: 2, key: { name: 1 }, name: 'name_1' }
      ]
   }
}

modify Event

New in version 6.0.

A modify event occurs when a collection is modified, such as when the collMod command adds or remove options from a collection or view.

The following example shows a modify event:

copy

{
   _id: { <ResumeToken> },
   operationType: 'modify',
   clusterTime: Timestamp({ t: 1654878543, i: 1 }),
   collectionUUID: UUID("47d6baac-eeaa-488b-98ae-893f3abaaf25"),
   wallTime: ISODate("2022-06-10T16:29:03.704Z"),
   ns: {
      db: 'test',
      coll: 'authors' },
   operationDescription: {
      index: {
         name: 'age_1',
         hidden: true
      }
   },
   stateBeforeChange: {
      collectionOptions: { uuid: UUID("47d6baac-eeaa-488b-98ae-893f3abaaf25") },
      indexOptions: {
         hidden: false
      }
   }
}

create Event

New in version 6.0.

A create event occurs when a collection is created, such as when the create command explicitly adds a collection to a database.

The following example shows a create event:

copy

{
   _id: { <ResumeToken> },
   operationType: 'create',
   clusterTime: Timestamp({ t: 1654894547, i: 24 }),
   collectionUUID: UUID("98046a1a-b649-4e5b-9c75-67594221ce19"),
   wallTime: ISODate("2022-06-10T20:55:47.947Z"),
   ns: {
      db: 'test',
      coll: 'names'
   },
   operationDescription: {
      idIndex: { v: 2, key: { _id: 1 }, name: '_id_' }
   }
}

shardCollection Event

New in version 6.0.

A shardCollection event occurs when a collection is sharded.

The following example shows a shardCollection event:

copy

{
   _id: { <ResumeToken> },
   operationType: 'shardCollection',
   clusterTime: Timestamp({ t: 1654894852, i: 52 }),
   collectionUUID: UUID("98046a1a-b649-4e5b-9c75-67594221ce19"),
   wallTime: ISODate("2022-06-10T21:00:52.854Z"),
   ns: {
      db: 'test',
      coll: 'authors'
   },
   operationDescription: {
      shardKey: { age: 'hashed' },
      unique: false,
      numInitialChunks: Long("0"),
      presplitHashedZones: false
   }
}

←   Change Streams Production Recommendations Replication  →

© MongoDB, Inc 2008-present. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc.