DOCSP-36990 cursors (#20)

Author: jordan-smith721

source/fundamentals/crud/cursors.txt

@@ -1,46 +1,65 @@
-.. uses tailable.rst
+.. _pymongo-cursors:
 
+================
 Tailable Cursors
 ================
 
-By default, MongoDB will automatically close a cursor when the client has
-exhausted all results in the cursor. However, for `capped collections
-<https://mongodb.com/docs/manual/core/capped-collections/>`_ you may
-use a `tailable cursor
-<https://mongodb.com/docs/manual/core/tailable-cursors/>`_
-that remains open after the client exhausts the results in the initial cursor.
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: oplog
+
+Overview
+--------
+
+By default, MongoDB automatically closes a cursor when the client has
+exhausted all results in the cursor. However, for :manual:`capped collections </core/capped-collections/>`,
+you can use a :manual:`tailable cursor </core/tailable-cursors/>` that remains
+open after the client exhausts the results in the initial cursor.
 
-The following is a basic example of using a tailable cursor to tail the oplog
-of a replica set member:
+Example
+-------
+
+The following example uses a tailable cursor to tail the oplog
+of a replica-set member:
 
 .. code-block:: python
 
-  import time
-
-  import pymongo
-
-  client = pymongo.MongoClient()
-  oplog = client.local.oplog.rs
-  first = oplog.find().sort('$natural', pymongo.ASCENDING).limit(-1).next()
-  print(first)
-  ts = first['ts']
-
-  while True:
-      # For a regular capped collection CursorType.TAILABLE_AWAIT is the
-      # only option required to create a tailable cursor. When querying the
-      # oplog, the oplog_replay option enables an optimization to quickly
-      # find the 'ts' value we're looking for. The oplog_replay option
-      # can only be used when querying the oplog. Starting in MongoDB 4.4
-      # this option is ignored by the server as queries against the oplog
-      # are optimized automatically by the MongoDB query engine.
-      cursor = oplog.find({'ts': {'$gt': ts}},
-                          cursor_type=pymongo.CursorType.TAILABLE_AWAIT,
-                          oplog_replay=True)
-      while cursor.alive:
-          for doc in cursor:
-              ts = doc['ts']
-              print(doc)
-          # We end up here if the find() returned no documents or if the
-          # tailable cursor timed out (no new documents were added to the
-          # collection for more than 1 second).
-          time.sleep(1)
+   import time
+
+   import pymongo
+
+   client = pymongo.MongoClient()
+   oplog = client.local.oplog.rs
+   first = oplog.find().sort('$natural', pymongo.ASCENDING).limit(-1).next()
+   print(first)
+   ts = first['ts']
+ 
+   while True:
+       cursor = oplog.find({'ts': {'$gt': ts}},
+                           cursor_type=pymongo.CursorType.TAILABLE_AWAIT,
+                           oplog_replay=True)
+       while cursor.alive:
+           for doc in cursor:
+               ts = doc['ts']
+               print(doc)
+           # You end up here if the find() method returns no documents, or if the
+           # tailable cursor times out (no new documents are added to the
+           # collection for more than 1 second).
+           time.sleep(1)
+
+For a capped collection, ``CursorType.TAILABLE_AWAIT`` is the
+only option required to create a tailable cursor. When querying the
+oplog, the ``oplog_replay`` option enables an optimization to quickly
+find the ``ts`` value. You can use the ``oplog_replay`` option
+only when querying the oplog. Starting in MongoDB 4.4,
+the server ignores this option, because the MongoDB query engine automatically
+optimizes queries against the oplog.