Change Events¶

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

{
   _id : { <BSON Object> },
   "operationType" : "<operation>",
   "fullDocument" : { <document> },
   "ns" : {
      "db" : "<database>",
      "coll" : "<collection>"
   },
   "to" : {
      "db" : "<database>",
      "coll" : "<collection>"
   },
   "documentKey" : { "_id" : <value> },
   "updateDescription" : {
      "updatedFields" : { <document> },
      "removedFields" : [ "<field>", ... ]
   }
   "clusterTime" : <Timestamp>,
   "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	Metadata related to the operation. Acts as the `resumeToken` for the `resumeAfter` parameter when resuming a change stream. 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. For details, see Resume Tokens.
`operationType`	string	The type of operation that occurred. Can be any of the following values: `insert` `delete` `replace` `update` `drop` `rename` `dropDatabase` `invalidate`
`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.
`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 : 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.
`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 associcated 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.
`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>,
   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>,
   ns: {
      db: 'engineering',
      coll: 'users'
   },
   documentKey: {
      _id: ObjectId("58a4eb4a30c75625e00d2820")
   },
   updateDescription: {
      updatedFields: {
         email: '[email protected]'
      },
      removedFields: ['phoneNumber']
   }
}

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

copy

{
   _id: { < Resume Token > },
   operationType: 'update',
   clusterTime: <Timestamp>,
   ns: {
      db: 'engineering',
      coll: 'users'
   },
   documentKey: {
      _id: ObjectId("58a4eb4a30c75625e00d2820")
   },
   updateDescription: {
      updatedFields: {
         email: '[email protected]'
      },
      removedFields: ['phoneNumber']
   },
   fullDocument: {
      _id: ObjectId("58a4eb4a30c75625e00d2820"),
      name: 'Alice',
      userName: 'alice123',
      email: '[email protected]',
      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.

`replace` Event¶

The following example illustrates a replace event:

copy

{
   _id: { < Resume Token > },
   operationType: 'replace',
   clusterTime: <Timestamp>,
   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.

`delete` Event¶

The following example illustrates a delete event:

copy

{
   _id: { < Resume Token > },
   operationType: 'delete',
   clusterTime: <Timestamp>,
   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.

`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>,
   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>,
   ns: {
      db: 'engineering',
      coll: 'users'
   },
   to: {
      db: 'engineering',
      coll: 'people'
   }
}

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

`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>,
   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>
}

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.

← Change Streams Production Recommendations Replication →

Change Events¶

Change Events¶

insert Event¶

update Event¶

replace Event¶

delete Event¶

drop Event¶

rename Event¶

dropDatabase Event¶

invalidate Event¶

`insert` Event¶

`update` Event¶

`replace` Event¶

`delete` Event¶

`drop` Event¶

`rename` Event¶

`dropDatabase` Event¶

`invalidate` Event¶