diff --git a/doc/examples/index.rst b/doc/examples/index.rst index 6b4fbd748..24169dabd 100644 --- a/doc/examples/index.rst +++ b/doc/examples/index.rst @@ -27,4 +27,5 @@ MongoDB, you can start it like so: gridfs high_availability mod_wsgi + tailable tls diff --git a/doc/examples/tailable.rst b/doc/examples/tailable.rst new file mode 100644 index 000000000..34f75b408 --- /dev/null +++ b/doc/examples/tailable.rst @@ -0,0 +1,41 @@ +Tailable Cursors +================ + +By default, MongoDB will automatically close a cursor when the client has +exhausted all results in the cursor. However, for `capped collections +`_ you may +use a `tailable cursor +`_ +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:: + + 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. + 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) +