DOCSP-8629: Address Snapshot Reads Outside Txns

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.

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" <disable-read-concern-majority>`.

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

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 </core/transactions>`.
+Read concern ``"snapshot"`` is available for :doc:`multi-document
+transactions </core/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
   <sessions>`, upon transaction commit with write concern
@@ -29,19 +31,26 @@ transactions </core/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 </core/capped-collections>` 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()
+</reference/method/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 <sessions>`.
+
+Read Concern on Capped Collections
+----------------------------------
+
+Starting in version 5.0, you cannot use read concern
+:readconcern:`"snapshot"` when reading from a
+:doc:`capped </core/capped-collections>` collection.

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 <sessions>`, 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 <sessions>`, 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" <disable-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
-<causal-consistency>`, :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.
+<causal-consistency>`, :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 <atClusterTime>` in
+   conjunction with ``afterClusterTime``. To use :ref:`atClusterTime
+   <atClusterTime>` with read concern `"snapshot"` you have to disable
+   :ref:`causally consistent sessions <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

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