DOCS-11040: db.collection.watch()

Author: ravindk89

source/includes/apiargs-method-db.collection.watch-options.yaml

@@ -0,0 +1,79 @@
+name: resumeAfter
+position: 1
+description: |
+  
+  Directs :method:`~db.collection.watch` to attempt resuming
+  notifications starting after the operation specified in the resume
+  token. 
+
+  Each change stream event document includes a resume token as the
+  ``_id`` field. Pass the *entire* ``_id`` field of the change event
+  document that represents the operation you want to resume after.
+
+optional: true
+type: document
+operation: db.collection.watch
+interface: method
+arg_name: field
+---
+name: fullDocument
+position: 2
+description: |
+
+  By default, :method:`~db.collection.watch()` returns the delta of
+  those fields modified by an update operation, instead of the entire
+  updated document.
+
+  Set ``fullDocument`` to ``"updateLookup"`` to direct
+  :method:`~db.collection.watch()` to look up the most current 
+  majority-committed version of the updated document.
+  :method:`~db.collection.watch()` returns a ``fullDocument`` field with
+  the document lookup in addition to the ``updateDescription`` delta.
+
+optional: true
+type: string
+operation: db.collection.watch
+interface: method
+arg_name: field
+---
+name: batchSize
+position: 3
+description: |
+  Specifies the maximum number of change events to return in each
+  batch of the response from the MongoDB cluster. 
+
+  Has the same functionality as :method:`cursor.batchSize()`.
+optional: true
+type: int
+operation: db.collection.watch
+interface: method
+arg_name: field
+---
+name: maxAwaitTimeMS
+position: 4
+description: |
+  
+  The maximum amount of time in milliseconds the server waits for new
+  data changes to report to the change stream cursor before returning an
+  empty batch.
+
+  Defaults to ``1000`` milliseconds.
+
+optional: true
+type: int
+operation: db.collection.watch
+interface: method
+arg_name: field
+---
+name: collation
+position: 5
+description: |
+  Pass a :ref:`collation document <collation-document-fields>`
+  to specify a :doc:`collation </reference/collation>` for the 
+  change stream cursor.
+optional: true
+type: document
+operation: db.collection.watch
+interface: method
+arg_name: field
+...

source/includes/apiargs-method-db.collection.watch-param.yaml

@@ -0,0 +1,38 @@
+arg_name: param
+description: |
+
+  A sequence of one or more of the following aggregation stages:
+
+  - :pipeline:`$match`
+  - :pipeline:`$project`
+  - :pipeline:`$addFields`
+  - :pipeline:`$replaceRoot`
+  - :pipeline:`$redact`
+
+  See :doc:`/aggregation` for complete documentation on the aggregation
+  framework.
+
+interface: method
+name: pipeline
+operation: db.collection.watch
+optional: false
+position: 1
+type: array
+---
+arg_name: param
+description: |
+
+  Additional options that modify the behavior of
+  :method:`~db.collection.watch()`.
+
+  You must pass an empty array ``[]`` to the ``pipeline``
+  parameter if you are not specifying a pipeline but are
+  are passing the ``options`` document.
+
+interface: method
+name: options
+operation: db.collection.watch
+optional: true
+position: 2
+type: document
+...

source/includes/ref-toc-method-collection.yaml

@@ -170,6 +170,10 @@ name: ":method:`db.collection.updateMany()`"
 file: /reference/method/db.collection.updateMany
 description: "Modifies multiple documents in a collection."
 ---
+name: ":method:`db.collection.watch()`"
+file: /reference/method/db.collection.watch
+description: "Establishes a Change Stream on a collection."
+---
 name: ":method:`db.collection.validate()`"
 file: /reference/method/db.collection.validate
 description: "Performs diagnostic operations on a collection."

source/includes/ref-toc-method-cursor.yaml

@@ -10,6 +10,10 @@ name: ":method:`cursor.close()`"
 file: /reference/method/cursor.close
 description: "Close a cursor and free associated server resources."
 ---
+name: ":method:`cursor.isClosed()`"
+file: /reference/method/cursor.isClosed
+description: "Returns ``true`` if the cursor is closed."
+---
 name: ":method:`cursor.collation()`"
 file: /reference/method/cursor.collation
 description: "Specifies the collation for the cursor returned by the :method:`db.collection.find()`."
@@ -38,6 +42,10 @@ name: ":method:`cursor.hint()`"
 file: /reference/method/cursor.hint
 description: "Forces MongoDB to use a specific index for a query."
 ---
+name: ":method:`cursor.isExhausted()`"
+file: /reference/method/cursor.isExhausted
+description: "Returns ``true`` if the cursor is closed *and* there are no objects remaining in the batch."
+---
 name: ":method:`cursor.itcount()`"
 file: /reference/method/cursor.itcount
 description: "Computes the total number of documents in the cursor client-side by fetching and iterating the result set."

source/reference/change-events.txt

@@ -155,6 +155,8 @@ with a shard key on ``userName`` and ``_id``.
 The ``fullDocument`` document represents the version of the document at the
 time of the insert.
 
+.. _change-streams-update-event:
+
 ``update`` Event
 ----------------
 

source/reference/method/cursor.isClosed.txt

@@ -0,0 +1,23 @@
+=================
+cursor.isClosed()
+=================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+.. method:: cursor.isClosed()
+
+   :returns: Boolean.
+
+   :method:`cursor.isClosed()` returns ``true`` if the server has
+   closed the cursor. 
+
+   A closed cursor may still have documents remaining in the last
+   received batch. Use :method:`cursor.isExhausted()` or 
+   :method:`cursor.hasNext()` to check if the cursor is fully
+   exhausted.

source/reference/method/cursor.isExhausted.txt

@@ -0,0 +1,57 @@
+====================
+cursor.isExhausted()
+====================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+.. method:: cursor.isExhausted()
+
+   :returns: Boolean.
+
+   :method:`cursor.isExhausted()` returns ``true`` if the cursor
+   is closed *and* there are no remaining objects in the batch.
+
+   Use :method:`~cursor.isExhausted()` to support iterating cursors
+   that remain open even if there are no documents remaining in the
+   current batch, such as :method:`tailable <cursor.tailable()>` or
+   :method:`change stream <db.collection.watch()>` cursors.
+
+Example
+-------
+
+Consider the following ``while`` loop iterating through updates to
+a :method:`change stream <db.collection.watch()>` cursor:
+
+.. code-block:: javascript
+
+   watchCursor = db.collection.watch();
+
+   while (watchCursor.hasNext()) {
+      watchCursor.next();
+   }
+
+A change stream cursor can return an empty batch if no new data changes
+have occured within a set period of time. This causes the while loop
+to exit prematurely as :method:`cursor.hasNext()` returns ``false``
+when it detects the empty batch. However, the change stream cursor 
+is still open and able to return more documents in the future.
+
+Use :method:`cursor.isExhausted()` to ensure the while loop only exits
+when the cursor is closed *and* there are no documents remaining in the
+batch:
+
+.. code-block:: javascript
+
+   watchCursor = db.collection.watch();
+
+   while (!watchCursor.isExhausted()) {
+      if (watchCursor.hasNext()){
+         watchCursor.next();
+      }
+   }