Change Events

Change Events

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

  1. {
  2.    _id : { <BSON Object> },
  3.    "operationType" : "<operation>",
  4.    "fullDocument" : { <document> },
  5.    "ns" : {
  6.       "db" : "<database>",
  7.       "coll" : "<collection"
  8.    },
  9.    "to" : {
  10.       "db" : "<database>",
  11.       "coll" : "<collection"
  12.    },
  13.    "documentKey" : { "_id" : <value> },
  14.    "updateDescription" : {
  15.       "updatedFields" : { <document> },
  16.       "removedFields" : [ "<field>", ... ]
  17.    }
  18.    "clusterTime" : <Timestamp>,
  19.    "txnNumber" : <NumberLong>,
  20.    "lsid" : {
  21.       "id" : <UUID>,
  22.       "uid" : <BinData>
  23.    }
  24. }

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

FieldTypeDescription
_iddocumentMetadata related to the operation. Acts as the resumeTokenfor the resumeAfter parameter when resuming a change stream.
  1. {   "_data" : <BinData|hex string>}
The _data type depends on the MongoDB versionsand, in some cases, the feature compatibility version (fcv) atthe time of the change stream’s opening/resumption. For details,see Resume Tokens.
operationTypestringThe type of operation that occurred. Can be any of the followingvalues:- insert- delete- replace- update- drop- rename- dropDatabase- invalidate
fullDocumentdocumentThe document created or modified by the insert, replace,delete, update operations (i.e. CRUD operations).For insert and replace operations, this represents the newdocument created by the operation.For delete operations, this field is omitted as the document nolonger exists.For update operations, this field only appears if you configuredthe change stream with fullDocument set to updateLookup. Thisfield then represents the most current majority-committed version ofthe document modified by the update operation. Thisdocument may differ from the changes described in updateDescriptionif other majority-committed operations modified the document betweenthe original update operation and the full document lookup.
nsdocumentThe namespace (database and or collection) affected by the event.
ns.dbstringThe name of the database.
ns.collstringThe name of the collection.For dropDatabase operations, this field is omitted.
todocumentWhen operationType : rename, this document displays the new name forthe ns collection. This document is omitted for all othervalues of operationType.
to.dbstringThe new name of the database.
to.collstringThe new name of the collection.
documentKeydocumentA 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 thedocument. The _id field is not repeated if it is already apart of the shard key.
updateDescriptiondocumentA document describing the fields that were updated or removedby the update operation.This document and its fields only appears if the operationType isupdate.
updateDescription.updatedFieldsdocumentA document whose keys correspond to the fields that were modified by theupdate operation. The value of each field corresponds to the newvalue of those fields, rather than the operation that resulted in thenew value.
updateDescription.removedFieldsarrayAn array of fields that were removed by the update operation.
clusterTimeTimestampThe timestamp from the oplog entry associated with the event.For events that happened as part of a multi-documenttransaction, the associated change streamnotifications will have the same clusterTime value, namelythe time when the transaction was committed.On a sharded cluster, events that occur on different shards canhave the same clusterTime but be associated with differenttransactions or even not be associcated with any transaction. Toidentify events for a single transaction, you can use thecombination of lsid and txnNumber in the change streamevent document.New in version 4.0.
txnNumberNumberLongThe transaction number.Only present if the operation is part of a multi-documenttransaction.New in version 4.0.
lsidDocumentThe identifier for the session associated with the transaction.Only present if the operation is part of a multi-documenttransaction.New in version 4.0.

insert Event

The following example illustrates an insert event:

  1. {
  2.    _id: { < Resume Token > },
  3.    operationType: 'insert',
  4.    clusterTime: <Timestamp>,
  5.    ns: {
  6.       db: 'engineering',
  7.       coll: 'users'
  8.    },
  9.    documentKey: {
  10.       userName: 'alice123',
  11.       _id: ObjectId("599af247bb69cd89961c986d")
  12.    },
  13.    fullDocument: {
  14.       _id: ObjectId("599af247bb69cd89961c986d"),
  15.       userName: 'alice123',
  16.       name: 'Alice'
  17.    }
  18. }

The documentKey field includes both the _id and the userNamefield. 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 thetime of the insert.

update Event

The following example illustrates an update event:

  1. {
  2.    _id: { < Resume Token > },
  3.    operationType: 'update',
  4.    clusterTime: <Timestamp>,
  5.    ns: {
  6.       db: 'engineering',
  7.       coll: 'users'
  8.    },
  9.    documentKey: {
  10.       _id: ObjectId("58a4eb4a30c75625e00d2820")
  11.    },
  12.    updateDescription: {
  13.       updatedFields: {
  14.          email: 'alice@10gen.com'
  15.       },
  16.       removedFields: ['phoneNumber']
  17.    }
  18. }

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

  1. {
  2.    _id: { < Resume Token > },
  3.    operationType: 'update',
  4.    clusterTime: <Timestamp>,
  5.    ns: {
  6.       db: 'engineering',
  7.       coll: 'users'
  8.    },
  9.    documentKey: {
  10.       _id: ObjectId("58a4eb4a30c75625e00d2820")
  11.    },
  12.    updateDescription: {
  13.       updatedFields: {
  14.          email: 'alice@10gen.com'
  15.       },
  16.       removedFields: ['phoneNumber']
  17.    },
  18.    fullDocument: {
  19.       _id: ObjectId("58a4eb4a30c75625e00d2820"),
  20.       name: 'Alice',
  21.       userName: 'alice123',
  22.       email: 'alice@10gen.com',
  23.       team: 'replication'
  24.    }
  25. }

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

replace Event

The following example illustrates a replace event:

  1. {
  2.    _id: { < Resume Token > },
  3.    operationType: 'replace',
  4.    clusterTime: <Timestamp>,
  5.    ns: {
  6.       db: 'engineering',
  7.       coll: 'users'
  8.    },
  9.    documentKey: {
  10.       _id: ObjectId("599af247bb69cd89961c986d")
  11.    },
  12.    fullDocument: {
  13.       _id: ObjectId("599af247bb69cd89961c986d"),
  14.       userName: 'alice123',
  15.       name: 'Alice'
  16.    }
  17. }

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 theinsert of the replacement document.

delete Event

The following example illustrates a delete event:

  1. {
  2.    _id: { < Resume Token > },
  3.    operationType: 'delete',
  4.    clusterTime: <Timestamp>,
  5.    ns: {
  6.       db: 'engineering',
  7.       coll: 'users'
  8.    },
  9.    documentKey: {
  10.       _id: ObjectId("599af247bb69cd89961c986d")
  11.    }
  12. }

The fullDocument document is omitted as the document no longer exists at thetime 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. Thefollowing example illustrates a drop event:

  1. {
  2.    _id: { < Resume Token > },
  3.    operationType: 'drop',
  4.    clusterTime: <Timestamp>,
  5.    ns: {
  6.       db: 'engineering',
  7.       coll: 'users'
  8.    }
  9. }

A drop event leads to an invalidate eventfor 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 exampleillustrates a rename event:

  1. {
  2.    _id: { < Resume Token > },
  3.    operationType: 'rename',
  4.    clusterTime: <Timestamp>,
  5.    ns: {
  6.       db: 'engineering',
  7.       coll: 'users'
  8.    },
  9.    to: {
  10.       db: 'engineering',
  11.       coll: 'people'
  12.    }
  13. }

A rename event leads to aninvalidate event for change streams openedagainst its ns collection or to collection.

dropDatabase Event

New in version 4.0.1.

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

  1. {
  2.    _id: { < Resume Token > },
  3.    operationType: 'dropDatabase',
  4.    clusterTime: <Timestamp>,
  5.    ns: {
  6.       db: 'engineering'
  7.    }
  8. }

A dropDatabase command generates adrop event for each collection inthe database before generating a dropDatabase event for the database.

A dropDatabase event leads to aninvalidate event for change streams openedagainst its ns.db database.

invalidate Event

The following example illustrates an invalidate event:

  1. {
  2.    _id: { < Resume Token > },
  3.    operationType: 'invalidate',
  4.    clusterTime: <Timestamp>
  5. }

For change streams opened up against a collection, adrop event,rename event, ordropDatabase event that affects thewatched collection leads to aninvalidate event.

For change streams opened up against a database, adropDatabase event that affects thewatched database leads to aninvalidate event.

invalidate events close the change stream cursor.

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