Navigation

Change Events

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"
   },
   "documentKey" : { "_id" : <ObjectId> },
   "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.

Use this document as a resumeToken for the resumeAfter parameter when resuming a change stream.

If the featureCompatibilityVersion (fcv) is set to "4.0" or greater, newly opened change streams return a hex-encoded string for the resume token data, i.e. the _id._data value. This change allows for the ability to compare and sort the resume tokens. If the fcv is 3.6, newly opened change streams return a BinData for the resume token data.

Important

The fcv value at the time of the cursor’s opening determine the resume token data type. That is, the modification of the fcv does not affect the resume tokens for change streams already opened before the fcv change.

Regardless of the fcv value, a 4.0 replica set or a sharded cluster can resume a change stream using either the BinData or string resume token.

operationType string

The type of operation that occurred. Can be any of the following values:

  • insert
  • delete
  • replace
  • update
  • invalidate
fullDocument document

The document created or modified by the operation.

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 of the database and collection the change stream is open against.
ns.db string The name of the database.
ns.coll string The name of the collection.
documentKey document The ObjectID of the document created or modified by the operation. 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.

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:

{
   _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:

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

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

{
   _id: { < Resume Token > },
   operationType: 'update',
   clusterTime: <Timestamp>,
   ns: {
      db: 'engineering',
      coll: 'users'
   },
   documentKey: {
      _id: ObjectId("58a4eb4a30c75625e00d2820")
   },
   updateDescription: {
      updatedFields: {
         email: 'alice@10gen.com'
      },
      removedFields: ['phoneNumber']
   },
   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.

replace Event

The following example illustrates a replace event:

{
   _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:

{
   _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.

invalidate Event

The following example illustrates an invalidate event:

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

For change stream opened against a collection, invalidate events occur after a dropDatabase, drop, or renameCollection command that affects the watched collection.

For change stream opened against a database, invalidate events occur after a dropDatabase, drop, or renameCollection command that affects the watched database.

For change stream opened against the deployment, invalidate events occur after a dropDatabase, drop, or renameCollection command occurs in the deployment.

invalidate events close the change stream cursor.

You cannot resume a change stream after an invalidate event (for example, a collection drop or rename) closes the stream.