Skip to content

Commit 652e54b

Browse files
npentreljeff-allen-mongo
authored andcommitted
DOCSP-8629: Address Snapshot Reads Outside Txns
1 parent 945a6c2 commit 652e54b

File tree

6 files changed

+142
-40
lines changed

6 files changed

+142
-40
lines changed

source/core/inmemory.txt

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -229,3 +229,8 @@ For each sharded collection that should reside across the
229229
sh.addTagRange("salesdb.orders", { shardKey: MinKey }, { shardKey: MaxKey }, "persisted")
230230

231231
For the ``inmem`` shard, create a database or move the database.
232+
233+
.. note::
234+
235+
Read concern level :readconcern:`"snapshot"` is not officially supported
236+
with the in-memory storage engine.
Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
For reads on a sharded cluster, you cannot use read concern
2+
:readconcern:`"snapshot"` if the operation involves a shard that has
3+
:ref:`disabled read concern "majority" <disable-read-concern-majority>`.

source/reference/read-concern-majority.txt

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -187,6 +187,13 @@ If ``false``, read concern "majority" is disabled.
187187

188188
.. include:: /includes/extracts/transactions-read-concern-majority.rst
189189

190+
.. topic:: Read Concern ``"snapshot"``
191+
192+
Disabling :readconcern:`"majority"` read concern affects read
193+
operations on sharded clusters.
194+
195+
.. include:: /includes/fact-readConcern-snapshot-disable-majority.rst
196+
190197
.. topic:: Rollback Considerations
191198

192199
.. include:: /includes/fact-disable-majority-rc-rollbacks.rst

source/reference/read-concern-snapshot.txt

Lines changed: 76 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -13,9 +13,11 @@ Read Concern ``"snapshot"``
1313
:keywords: read concern, snapshot read concern, read isolation, transactions, multi-document transactions
1414

1515
.. versionadded:: 4.0
16+
.. versionchanged:: 5.0
1617

17-
Read concern ``"snapshot"`` is only available for :doc:`multi-document
18-
transactions </core/transactions>`.
18+
Read concern ``"snapshot"`` is available for :doc:`multi-document
19+
transactions </core/transactions>`, and starting in MongoDB 5.0, certain
20+
read operations outside of multi-document transactions.
1921

2022
- If the transaction is not part of a :ref:`causally consistent session
2123
<sessions>`, upon transaction commit with write concern
@@ -29,19 +31,26 @@ transactions </core/transactions>`.
2931
causal consistency with the operation immediately preceding the
3032
transaction start.
3133

34+
Outside of multi-document transactions, read concern
35+
:readconcern:`"snapshot"` is available on primaries and secondaries for
36+
the following read operations :
37+
38+
- :dbcommand:`find`
39+
- :dbcommand:`aggregate`
40+
- :dbcommand:`distinct` (on unsharded collections)
41+
42+
All other read commands prohibit :readconcern:`"snapshot"`.
43+
44+
.. note::
45+
46+
.. include:: /includes/fact-readConcern-snapshot-disable-majority.rst
47+
3248
Operations
3349
----------
3450

3551
For a list of all operations that accept read concerns, see
3652
:ref:`read-concern-operations`.
3753

38-
Read Concern on Capped Collections
39-
----------------------------------
40-
41-
Starting in version 5.0, you cannot use read concern
42-
:readconcern:`"snapshot"` when reading from a
43-
:doc:`capped </core/capped-collections>` collection.
44-
4554
Read Concern and Transactions
4655
-----------------------------
4756

@@ -64,4 +73,62 @@ the transaction. If you use read concern :readconcern:`"snapshot"`, the
6473
transaction errors and aborts. For more information, see
6574
:ref:`transactions-disabled-rc-majority`.
6675

76+
.. _atClusterTime:
77+
78+
Read Concern and ``atClusterTime``
79+
----------------------------------
80+
81+
.. versionadded:: 5.0
6782

83+
Outside of multi-document transaction, reads with read concern
84+
:readconcern:`"snapshot"` support the optional parameter
85+
``atClusterTime``. The parameter ``atClusterTime`` allows you to specify
86+
the timestamp for the read. To satisfy a read request with a specified
87+
``atClusterTime`` of T, the :binary:`~bin.mongod` performs the request
88+
based on the data available at time T.
89+
90+
You can obtain the ``operationTime`` or ``clusterTime`` of an operation
91+
from the response of :doc:`db.runCommand()
92+
</reference/method/db.runCommand/>` or from the :method:`Session`
93+
object.
94+
95+
The following command performs a find operation with read concern
96+
:readconcern:`"snapshot"` and specifies that the operation should read
97+
data from the snapshot at cluster time ``Timestamp(1613577600, 1)``.
98+
99+
.. code-block:: javascript
100+
101+
db.runCommand( {
102+
find: "restaurants",
103+
filter: { _id: 5 },
104+
readConcern: {
105+
level: "snapshot",
106+
atClusterTime: Timestamp(1613577600, 1)
107+
},
108+
} )
109+
110+
If the parameter ``atClusterTime`` is not supplied, the
111+
:binary:`~bin.mongos`, or in single member replica sets the
112+
:binary:`~bin.mongod`, selects the timestamp of the latest
113+
majority-committed snapshot as the ``atClusterTime`` and returns it to
114+
the client.
115+
116+
Outside of transactions, :readconcern:`"snapshot"` reads are
117+
guaranteed to read from majority-committed data.
118+
119+
.. note:
120+
121+
- If you perform a read operation with :readconcern:`"snapshot"`
122+
against a delayed replica set member, the returned majority-committed
123+
data could be stale.
124+
125+
- It is not possible to specify ``atClusterTime`` for
126+
:readconcern:`"snapshot"` inside of :ref:`causally consistent
127+
sessions <sessions>`.
128+
129+
Read Concern on Capped Collections
130+
----------------------------------
131+
132+
Starting in version 5.0, you cannot use read concern
133+
:readconcern:`"snapshot"` when reading from a
134+
:doc:`capped </core/capped-collections>` collection.

source/reference/read-concern.txt

Lines changed: 42 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -187,33 +187,40 @@ The following read concern levels are available:
187187

188188
* - :readconcern:`"snapshot"`
189189

190-
- | If the transaction is not part of a :ref:`causally consistent
190+
- | If a transaction is not part of a :ref:`causally consistent
191191
session <sessions>`, upon transaction commit with write
192192
concern :writeconcern:`"majority"`, the transaction operations
193193
are guaranteed to have read from a snapshot of
194194
majority-committed data.
195195

196-
| If the transaction is part of a :ref:`causally consistent
196+
| If a transaction is part of a :ref:`causally consistent
197197
session <sessions>`, upon transaction commit with write
198198
concern :writeconcern:`"majority"`, the transaction operations
199199
are guaranteed to have read from a snapshot of
200200
majority-committed data that provides causal consistency with
201201
the operation immediately preceding the transaction start.
202202

203-
Availability:
204-
- Read concern :readconcern:`"snapshot"` is only available
205-
for use with multi-document transactions.
206-
207-
- For transactions on a sharded cluster, if any operation in
208-
the transaction involves a shard that has :ref:`disabled
209-
read concern "majority" <disable-read-concern-majority>`,
210-
you cannot use read concern :readconcern:`"snapshot"` for
211-
the transaction. You can only use read concern
212-
:readconcern:`"local"` or :readconcern:`"majority"` for the
213-
transaction.
214-
215-
216-
203+
**Availability:**
204+
205+
Read concern :readconcern:`"snapshot"` is available for
206+
207+
- All read operations inside multi-document transactions with the
208+
read concern set at the transaction level.
209+
- The following methods outside of multi-document
210+
transactions:
211+
212+
- :dbcommand:`find`
213+
- :dbcommand:`aggregate`
214+
- :dbcommand:`distinct` (on unsharded collections)
215+
216+
All other read operations prohibit
217+
:readconcern:`"snapshot"`.
218+
219+
.. important::
220+
221+
.. include:: /includes/fact-readConcern-snapshot-disable-majority.rst
222+
223+
217224

218225
.. include:: /includes/fact-readConcern-most-recent-data-in-node.rst
219226

@@ -296,14 +303,10 @@ Causally Consistent Sessions and Available Read Concerns
296303
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
297304

298305
For operations in a :ref:`causally consistent session
299-
<causal-consistency>`, :readconcern:`"local"` and
300-
:readconcern:`"majority"` levels are available. However, to guarantee
301-
causal consistency, you must use :readconcern:`"majority"`. For
302-
details, see :ref:`causal-consistency`.
303-
304-
If a multi-document transaction is associated with a causally
305-
consistent session, :readconcern:`"snapshot"` is also available for the
306-
the transaction.
306+
<causal-consistency>`, :readconcern:`"local"`,
307+
:readconcern:`"majority"`, and :readconcern:`"snapshot"` levels are
308+
available. However, to guarantee causal consistency, you must use
309+
:readconcern:`"majority"`. For details, see :ref:`causal-consistency`.
307310

308311
.. _read-concern-operations:
309312

@@ -402,9 +405,10 @@ The following operations support read concern:
402405
.. [#distinct]
403406

404407
Read concern :readconcern:`"snapshot"` is available only for
405-
multi-document transactions. In a transaction, you cannot use the
406-
``distinct`` command or its helpers on a sharded collection.
407-
408+
certain read operations and for multi-document transactions. In a
409+
transaction, you cannot use the ``distinct`` command or its helpers
410+
on a sharded collection.
411+
408412
The following write operations can also accept a read concern if part
409413
of a multi-document transaction:
410414

@@ -494,10 +498,10 @@ of a multi-document transaction:
494498
.. [#snapshot]
495499

496500
Read concern :readconcern:`"snapshot"` is available only for
497-
multi-document transactions, and for transactions, you set the read
498-
concern at the transaction level. The operations that support
499-
:readconcern:`"snapshot"` correspond to the CRUD operations
500-
available in transactions. For more information, see
501+
certain read operations and multi-document transactions. For transactions, you
502+
set the read concern at the transaction level. The transaction
503+
operations that support :readconcern:`"snapshot"` correspond to the
504+
CRUD operations available in transactions. For more information, see
501505
:ref:`transactions-read-concern`.
502506

503507
Read Concern not Supported on ``local`` Database
@@ -581,6 +585,13 @@ with causally consistent sessions.
581585
such as to be consistent with the operations of another client
582586
session. For an example, see :ref:`causal-consistency-examples`.
583587

588+
.. note::
589+
590+
It is not possible to specify :ref:`atClusterTime <atClusterTime>` in
591+
conjunction with ``afterClusterTime``. To use :ref:`atClusterTime
592+
<atClusterTime>` with read concern `"snapshot"` you have to disable
593+
:ref:`causally consistent sessions <sessions>`.
594+
584595
To satisfy a read request with an ``afterClusterTime`` value of ``T``,
585596
a :binary:`~bin.mongod` must perform the request after its oplog
586597
reaches time ``T``. If its oplog has not reached time ``T``, the

source/release-notes/5.0.txt

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -139,6 +139,15 @@ Removed Commands
139139
Networking
140140
----------
141141

142+
.. _5.0-snapshot-reads:
143+
144+
Snapshot Reads
145+
--------------
146+
147+
Starting in MongoDB 5.0, read concern :readconcern:`"snapshot"` is
148+
supported for some read operations outside of multi-document
149+
transactions on primaries and secondaries.
150+
142151
.. _5.0-rel-notes-general:
143152

144153
General Improvements

0 commit comments

Comments
 (0)