diff --git a/source/core/inmemory.txt b/source/core/inmemory.txt index bad1d647fd6..d5430b59ca5 100644 --- a/source/core/inmemory.txt +++ b/source/core/inmemory.txt @@ -229,3 +229,8 @@ For each sharded collection that should reside across the sh.addTagRange("salesdb.orders", { shardKey: MinKey }, { shardKey: MaxKey }, "persisted") For the ``inmem`` shard, create a database or move the database. + +.. note:: + + Read concern level :readconcern:`"snapshot"` is not officially supported + with the in-memory storage engine. \ No newline at end of file diff --git a/source/includes/fact-readConcern-snapshot-disable-majority.rst b/source/includes/fact-readConcern-snapshot-disable-majority.rst new file mode 100644 index 00000000000..8f1378fb9a6 --- /dev/null +++ b/source/includes/fact-readConcern-snapshot-disable-majority.rst @@ -0,0 +1,3 @@ +For reads on a sharded cluster, you cannot use read concern +:readconcern:`"snapshot"` if the operation involves a shard that has +:ref:`disabled read concern "majority" `. diff --git a/source/reference/read-concern-majority.txt b/source/reference/read-concern-majority.txt index 1e06d2c198a..0fd5b2eaa3d 100644 --- a/source/reference/read-concern-majority.txt +++ b/source/reference/read-concern-majority.txt @@ -187,6 +187,13 @@ If ``false``, read concern "majority" is disabled. .. include:: /includes/extracts/transactions-read-concern-majority.rst +.. topic:: Read Concern ``"snapshot"`` + + Disabling :readconcern:`"majority"` read concern affects read + operations on sharded clusters. + + .. include:: /includes/fact-readConcern-snapshot-disable-majority.rst + .. topic:: Rollback Considerations .. include:: /includes/fact-disable-majority-rc-rollbacks.rst diff --git a/source/reference/read-concern-snapshot.txt b/source/reference/read-concern-snapshot.txt index 80a51344093..903d253f147 100644 --- a/source/reference/read-concern-snapshot.txt +++ b/source/reference/read-concern-snapshot.txt @@ -13,9 +13,11 @@ Read Concern ``"snapshot"`` :keywords: read concern, snapshot read concern, read isolation, transactions, multi-document transactions .. versionadded:: 4.0 +.. versionchanged:: 5.0 -Read concern ``"snapshot"`` is only available for :doc:`multi-document -transactions `. +Read concern ``"snapshot"`` is available for :doc:`multi-document +transactions `, and starting in MongoDB 5.0, certain +read operations outside of multi-document transactions. - If the transaction is not part of a :ref:`causally consistent session `, upon transaction commit with write concern @@ -29,19 +31,26 @@ transactions `. causal consistency with the operation immediately preceding the transaction start. +Outside of multi-document transactions, read concern +:readconcern:`"snapshot"` is available on primaries and secondaries for +the following read operations : + +- :dbcommand:`find` +- :dbcommand:`aggregate` +- :dbcommand:`distinct` (on unsharded collections) + +All other read commands prohibit :readconcern:`"snapshot"`. + +.. note:: + + .. include:: /includes/fact-readConcern-snapshot-disable-majority.rst + Operations ---------- For a list of all operations that accept read concerns, see :ref:`read-concern-operations`. -Read Concern on Capped Collections ----------------------------------- - -Starting in version 5.0, you cannot use read concern -:readconcern:`"snapshot"` when reading from a -:doc:`capped ` collection. - Read Concern and Transactions ----------------------------- @@ -64,4 +73,62 @@ the transaction. If you use read concern :readconcern:`"snapshot"`, the transaction errors and aborts. For more information, see :ref:`transactions-disabled-rc-majority`. +.. _atClusterTime: + +Read Concern and ``atClusterTime`` +---------------------------------- + +.. versionadded:: 5.0 +Outside of multi-document transaction, reads with read concern +:readconcern:`"snapshot"` support the optional parameter +``atClusterTime``. The parameter ``atClusterTime`` allows you to specify +the timestamp for the read. To satisfy a read request with a specified +``atClusterTime`` of T, the :binary:`~bin.mongod` performs the request +based on the data available at time T. + +You can obtain the ``operationTime`` or ``clusterTime`` of an operation +from the response of :doc:`db.runCommand() +` or from the :method:`Session` +object. + +The following command performs a find operation with read concern +:readconcern:`"snapshot"` and specifies that the operation should read +data from the snapshot at cluster time ``Timestamp(1613577600, 1)``. + +.. code-block:: javascript + + db.runCommand( { + find: "restaurants", + filter: { _id: 5 }, + readConcern: { + level: "snapshot", + atClusterTime: Timestamp(1613577600, 1) + }, + } ) + +If the parameter ``atClusterTime`` is not supplied, the +:binary:`~bin.mongos`, or in single member replica sets the +:binary:`~bin.mongod`, selects the timestamp of the latest +majority-committed snapshot as the ``atClusterTime`` and returns it to +the client. + +Outside of transactions, :readconcern:`"snapshot"` reads are +guaranteed to read from majority-committed data. + +.. note: + + - If you perform a read operation with :readconcern:`"snapshot"` + against a delayed replica set member, the returned majority-committed + data could be stale. + + - It is not possible to specify ``atClusterTime`` for + :readconcern:`"snapshot"` inside of :ref:`causally consistent + sessions `. + +Read Concern on Capped Collections +---------------------------------- + +Starting in version 5.0, you cannot use read concern +:readconcern:`"snapshot"` when reading from a +:doc:`capped ` collection. diff --git a/source/reference/read-concern.txt b/source/reference/read-concern.txt index 0a484b6c79f..e66ae6e162c 100644 --- a/source/reference/read-concern.txt +++ b/source/reference/read-concern.txt @@ -187,33 +187,40 @@ The following read concern levels are available: * - :readconcern:`"snapshot"` - - | If the transaction is not part of a :ref:`causally consistent + - | If a transaction is not part of a :ref:`causally consistent session `, upon transaction commit with write concern :writeconcern:`"majority"`, the transaction operations are guaranteed to have read from a snapshot of majority-committed data. - | If the transaction is part of a :ref:`causally consistent + | If a transaction is part of a :ref:`causally consistent session `, upon transaction commit with write concern :writeconcern:`"majority"`, the transaction operations are guaranteed to have read from a snapshot of majority-committed data that provides causal consistency with the operation immediately preceding the transaction start. - Availability: - - Read concern :readconcern:`"snapshot"` is only available - for use with multi-document transactions. - - - For transactions on a sharded cluster, if any operation in - the transaction involves a shard that has :ref:`disabled - read concern "majority" `, - you cannot use read concern :readconcern:`"snapshot"` for - the transaction. You can only use read concern - :readconcern:`"local"` or :readconcern:`"majority"` for the - transaction. - - - + **Availability:** + + Read concern :readconcern:`"snapshot"` is available for + + - All read operations inside multi-document transactions with the + read concern set at the transaction level. + - The following methods outside of multi-document + transactions: + + - :dbcommand:`find` + - :dbcommand:`aggregate` + - :dbcommand:`distinct` (on unsharded collections) + + All other read operations prohibit + :readconcern:`"snapshot"`. + + .. important:: + + .. include:: /includes/fact-readConcern-snapshot-disable-majority.rst + + .. include:: /includes/fact-readConcern-most-recent-data-in-node.rst @@ -296,14 +303,10 @@ Causally Consistent Sessions and Available Read Concerns ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ For operations in a :ref:`causally consistent session -`, :readconcern:`"local"` and -:readconcern:`"majority"` levels are available. However, to guarantee -causal consistency, you must use :readconcern:`"majority"`. For -details, see :ref:`causal-consistency`. - -If a multi-document transaction is associated with a causally -consistent session, :readconcern:`"snapshot"` is also available for the -the transaction. +`, :readconcern:`"local"`, +:readconcern:`"majority"`, and :readconcern:`"snapshot"` levels are +available. However, to guarantee causal consistency, you must use +:readconcern:`"majority"`. For details, see :ref:`causal-consistency`. .. _read-concern-operations: @@ -402,9 +405,10 @@ The following operations support read concern: .. [#distinct] Read concern :readconcern:`"snapshot"` is available only for - multi-document transactions. In a transaction, you cannot use the - ``distinct`` command or its helpers on a sharded collection. - + certain read operations and for multi-document transactions. In a + transaction, you cannot use the ``distinct`` command or its helpers + on a sharded collection. + The following write operations can also accept a read concern if part of a multi-document transaction: @@ -494,10 +498,10 @@ of a multi-document transaction: .. [#snapshot] Read concern :readconcern:`"snapshot"` is available only for - multi-document transactions, and for transactions, you set the read - concern at the transaction level. The operations that support - :readconcern:`"snapshot"` correspond to the CRUD operations - available in transactions. For more information, see + certain read operations and multi-document transactions. For transactions, you + set the read concern at the transaction level. The transaction + operations that support :readconcern:`"snapshot"` correspond to the + CRUD operations available in transactions. For more information, see :ref:`transactions-read-concern`. Read Concern not Supported on ``local`` Database @@ -581,6 +585,13 @@ with causally consistent sessions. such as to be consistent with the operations of another client session. For an example, see :ref:`causal-consistency-examples`. +.. note:: + + It is not possible to specify :ref:`atClusterTime ` in + conjunction with ``afterClusterTime``. To use :ref:`atClusterTime + ` with read concern `"snapshot"` you have to disable + :ref:`causally consistent sessions `. + To satisfy a read request with an ``afterClusterTime`` value of ``T``, a :binary:`~bin.mongod` must perform the request after its oplog reaches time ``T``. If its oplog has not reached time ``T``, the diff --git a/source/release-notes/5.0.txt b/source/release-notes/5.0.txt index c914ae7f99c..f813a76a7ed 100644 --- a/source/release-notes/5.0.txt +++ b/source/release-notes/5.0.txt @@ -119,6 +119,15 @@ Removed Commands Networking ---------- +.. _5.0-snapshot-reads: + +Snapshot Reads +-------------- + +Starting in MongoDB 5.0, read concern :readconcern:`"snapshot"` is +supported for some read operations outside of multi-document +transactions on primaries and secondaries. + .. _5.0-rel-notes-general: General Improvements