Skip to content

Commit 44a4fab

Browse files
committed
PYTHON-2775 Add docs for snapshot reads (#662)
(cherry picked from commit a142125)
1 parent 60f7ac7 commit 44a4fab

File tree

1 file changed

+39
-5
lines changed

1 file changed

+39
-5
lines changed

pymongo/client_session.py

Lines changed: 39 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,8 @@
4444
Transactions
4545
============
4646
47+
.. versionadded:: 3.7
48+
4749
MongoDB 4.0 adds support for transactions on replica set primaries. A
4850
transaction is associated with a :class:`ClientSession`. To start a transaction
4951
on a session, use :meth:`ClientSession.start_transaction` in a with-statement.
@@ -76,23 +78,55 @@
7678
A session may only have a single active transaction at a time, multiple
7779
transactions on the same session can be executed in sequence.
7880
79-
.. versionadded:: 3.7
80-
8181
Sharded Transactions
8282
^^^^^^^^^^^^^^^^^^^^
8383
84+
.. versionadded:: 3.9
85+
8486
PyMongo 3.9 adds support for transactions on sharded clusters running MongoDB
85-
4.2. Sharded transactions have the same API as replica set transactions.
87+
>=4.2. Sharded transactions have the same API as replica set transactions.
8688
When running a transaction against a sharded cluster, the session is
8789
pinned to the mongos server selected for the first operation in the
8890
transaction. All subsequent operations that are part of the same transaction
8991
are routed to the same mongos server. When the transaction is completed, by
9092
running either commitTransaction or abortTransaction, the session is unpinned.
9193
92-
.. versionadded:: 3.9
93-
9494
.. mongodoc:: transactions
9595
96+
Snapshot Reads
97+
==============
98+
99+
.. versionadded:: 3.12
100+
101+
MongoDB 5.0 adds support for snapshot reads. Snapshot reads are requested by
102+
passing the ``snapshot`` option to
103+
:meth:`~pymongo.mongo_client.MongoClient.start_session`.
104+
If ``snapshot`` is True, all read operations that use this session read data
105+
from the same snapshot timestamp. The server chooses the latest
106+
majority-committed snapshot timestamp when executing the first read operation
107+
using the session. Subsequent reads on this session read from the same
108+
snapshot timestamp. Snapshot reads are also supported when reading from
109+
replica set secondaries.
110+
111+
.. code-block:: python
112+
113+
# Each read using this session reads data from the same point in time.
114+
with client.start_session(snapshot=True) as session:
115+
order = orders.find_one({"sku": "abc123"}, session=session)
116+
inventory = inventory.find_one({"sku": "abc123"}, session=session)
117+
118+
Snapshot Reads Limitations
119+
^^^^^^^^^^^^^^^^^^^^^^^^^^
120+
121+
Snapshot reads sessions are incompatible with ``causal_consistency=True``.
122+
Only the following read operations are supported in a snapshot reads session:
123+
124+
- :meth:`~pymongo.collection.Collection.find`
125+
- :meth:`~pymongo.collection.Collection.find_one`
126+
- :meth:`~pymongo.collection.Collection.aggregate`
127+
- :meth:`~pymongo.collection.Collection.count_documents`
128+
- :meth:`~pymongo.collection.Collection.distinct` (on unsharded collections)
129+
96130
Classes
97131
=======
98132
"""

0 commit comments

Comments
 (0)