DOCS-10668: Change stream invalidate events

Author: nlarew

source/administration/change-streams-production-recommendations.txt

@@ -12,10 +12,10 @@ Change Streams Production Recommendations
    :depth: 1
    :class: singlecol
 
-If you drop a collection with change streams opened against it, the change
-stream cursors close when they advance to that point in the oplog. Change
-stream cursors with the ``fullDocument : updateLookup`` option may return
-``null`` for the lookup document.
+If you drop or rename a collection or database with change streams
+opened against it, the change stream cursors close when they advance to
+that point in the oplog. Change stream cursors with the ``fullDocument :
+updateLookup`` option may return ``null`` for the lookup document.
 
 Attempting to resume a change stream against a dropped collection results in
 an error. Any data changes that occurred on the collection between the last

source/includes/fact-cannot-resume-invalidated-change-stream.rst

@@ -0,0 +1,4 @@
+.. note::
+   :ref:`Invalidated <change-event-invalidate>` change streams cannot be
+   resumed. Attempting to resume a change stream against a dropped or
+   renamed collection results in an error.

source/reference/change-events.txt

@@ -132,19 +132,19 @@ The following example illustrates an ``insert`` event:
 
    {
       _id: { < Resume Token > },
-      operationType: ‘insert’,
+      operationType: 'insert',
       ns: {
-         db: ‘engineering’, 
-         coll: ‘users’
+         db: 'engineering', 
+         coll: 'users'
       },
       documentKey: {
-         userName: ‘alice123’, 
+         userName: 'alice123', 
          _id: ObjectId("599af247bb69cd89961c986d")
       },
       fullDocument: {
          _id: ObjectId("599af247bb69cd89961c986d"), 
-         userName: ‘alice123’,
-         name: ‘Alice’
+         userName: 'alice123',
+         name: 'Alice'
       }
    }
 
@@ -164,19 +164,19 @@ The following example illustrates an ``update`` event:
 
    {
       _id: { < Resume Token > },
-      operationType: ‘update’,
+      operationType: 'update',
       ns: { 
-         db: ‘engineering’, 
-         coll: ‘users’
+         db: 'engineering', 
+         coll: 'users'
       },
       documentKey: {
          _id: ObjectId("58a4eb4a30c75625e00d2820")
       },
       updateDescription: {
          updatedFields: {
-            email: ‘[email protected]’
+            email: '[email protected]'
          },
-         removedFields: [‘phoneNumber’]
+         removedFields: ['phoneNumber']
       }
    }
 
@@ -187,26 +187,26 @@ opened with the ``fullDocument : updateLookup`` option:
 
    {
       _id: { < Resume Token > },
-      operationType: ‘update’,
+      operationType: 'update',
       ns: { 
-         db: ‘engineering’, 
-         coll: ‘users’
+         db: 'engineering', 
+         coll: 'users'
       },
       documentKey: {
          _id: ObjectId("58a4eb4a30c75625e00d2820")
       },
       updateDescription: {
          updatedFields: {
-            email: ‘[email protected]’
+            email: '[email protected]'
          },
-         removedFields: [‘phoneNumber’]
+         removedFields: ['phoneNumber']
       },
       fullDocument: { 
          _id: ObjectId("58a4eb4a30c75625e00d2820"),
-         name: ‘Alice’,
-         userName: ‘alice123’,
-         email: ‘[email protected]’,
-         team: ‘replication’
+         name: 'Alice',
+         userName: 'alice123',
+         email: '[email protected]',
+         team: 'replication'
       }
    }
 
@@ -225,18 +225,18 @@ The following example illustrates a ``replace`` event:
 
    {
       _id: { < Resume Token > },
-      operationType: ‘replace’,
+      operationType: 'replace',
       ns: {
-         db: ‘engineering’, 
-         coll: ‘users’
+         db: 'engineering', 
+         coll: 'users'
       },
       documentKey: { 
          _id: ObjectId("599af247bb69cd89961c986d")
       },
       fullDocument: {
          _id: ObjectId("599af247bb69cd89961c986d"), 
-         userName: ‘alice123’,
-         name: ‘Alice’
+         userName: 'alice123',
+         name: 'Alice'
       }
    }
 
@@ -263,10 +263,10 @@ The following example illustrates a ``delete`` event:
             "$oid":"599af247bb69cd89961c986d"
          }
       },
-      operationType: ‘delete’,
+      operationType: 'delete',
       ns: {
-         db: ‘engineers’, 
-         coll: ‘users’
+         db: 'engineers',
+         coll: 'users'
       },
       documentKey: {
          _id: ObjectId("599af247bb69cd89961c986d")
@@ -275,3 +275,28 @@ The following example illustrates a ``delete`` event:
 
 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.
+
+
+.. _change-event-invalidate:
+
+``invalidate`` Event
+--------------------
+
+The following example illustrates an ``invalidate`` event:
+
+.. code-block:: none
+
+   {
+      _id: { < Resume Token > },
+      operationType: 'invalidate'
+   }
+
+All fields except for ``_id`` and ``operationType`` are omitted.
+
+``invalidate`` events occur after a :dbcommand:`dropDatabase`,
+:dbcommand:`drop`, or :dbcommand:`renameCollection` command that
+affects the watched collection. ``invalidate`` events close the change
+stream cursor and signal that any locally cached data is out
+of sync with the server.
+
+.. include:: /includes/fact-cannot-resume-invalidated-change-stream.rst

source/tutorial/change-streams-example.txt

@@ -350,6 +350,8 @@ notification after a specific notification.
 As long as that operation has not rolled off the :term:`oplog`, the
 change stream can successfully resume notifications.
 
+.. include:: /includes/fact-cannot-resume-invalidated-change-stream.rst
+
 See :ref:`change-stream-output` for more information on the change stream
 response document format.