diff --git a/config/sphinx_local.yaml b/config/sphinx_local.yaml index 1378e419ec1..aa2ce61e36b 100644 --- a/config/sphinx_local.yaml +++ b/config/sphinx_local.yaml @@ -68,6 +68,7 @@ theme: - /reference/operator/query-modifier - /reference/operator/update - /reference/replication + - /reference/read-concern - /reference/security - /reference/sharding - /reference/write-concern diff --git a/source/images/read-concern-write-timeline.svg b/source/images/read-concern-write-timeline.svg new file mode 100644 index 00000000000..89999c39f01 --- /dev/null +++ b/source/images/read-concern-write-timeline.svg @@ -0,0 +1,90 @@ + + + + + + + + + Secondary + 2 + + + + + + + + + + + + + + + + + + + + + + + + + + + t + 0 + + + t + 1 + + + t + 2 + + + w: "majority" + + + Acknowledge + + + Primary + + + t + 3 + + + t + 4 + + + Secondary + 1 + + + + + + + t + 5 + + + + + + + + + + + t + 6 + + + diff --git a/source/includes/fact-read-concern-write-timeline.rst b/source/includes/fact-read-concern-write-timeline.rst new file mode 100644 index 00000000000..a73c549f4e9 --- /dev/null +++ b/source/includes/fact-read-concern-write-timeline.rst @@ -0,0 +1,105 @@ +Consider the following timeline of a write operation Write\ :sub:`0` to +a three member replica set: + +.. note:: + + For simplification, the example assumes: + + - All writes prior to Write\ :sub:`0` have been successfully + replicated to all members. + + - Write\ :sub:`prev` is the previous write before Write\ :sub:`0`. + + - No other writes have occured after Write\ :sub:`0`. + +.. figure:: /images/read-concern-write-timeline.svg + :alt: Timeline of a write operation to a three member replica set. + :figwidth: 330px + +.. list-table:: + :header-rows: 1 + :widths: 10 45 25 25 + + * - Time + - Event + - Most Recent Write + - Most Recent w: "majority" write + + * - t\ :sub:`0` + - Primary applies Write\ :sub:`0` + + - | **Primary**: Write\ :sub:`0` + | **Secondary**\ :sub:`1`: Write\ :sub:`prev` + | **Secondary**\ :sub:`2`: Write\ :sub:`prev` + + - | **Primary**: Write\ :sub:`prev` + | **Secondary**\ :sub:`1`: Write\ :sub:`prev` + | **Secondary**\ :sub:`2`: Write\ :sub:`prev` + + + + * - t\ :sub:`1` + - Secondary\ :sub:`1` applies write\ :sub:`0` + + - | **Primary**: Write\ :sub:`0` + | **Secondary**\ :sub:`1`: Write\ :sub:`0` + | **Secondary**\ :sub:`2`: Write\ :sub:`prev` + + + - | **Primary**: Write\ :sub:`prev` + | **Secondary**\ :sub:`1`: Write\ :sub:`prev` + | **Secondary**\ :sub:`2`: Write\ :sub:`prev` + + * - t\ :sub:`2` + - Secondary\ :sub:`2` applies write\ :sub:`0` + - | **Primary**: Write\ :sub:`0` + | **Secondary**\ :sub:`1`: Write\ :sub:`0` + | **Secondary**\ :sub:`2`: Write\ :sub:`0` + + + - | **Primary**: Write\ :sub:`prev` + | **Secondary**\ :sub:`1`: Write\ :sub:`prev` + | **Secondary**\ :sub:`2`: Write\ :sub:`prev` + + * - t\ :sub:`3` + - Primary is aware of successful replication to Secondary\ :sub:`1` and sends acknowledgement to client + - | **Primary**: Write\ :sub:`0` + | **Secondary**\ :sub:`1`: Write\ :sub:`0` + | **Secondary**\ :sub:`2`: Write\ :sub:`0` + + - | **Primary**: Write\ :sub:`0` + | **Secondary**\ :sub:`1`: Write\ :sub:`prev` + | **Secondary**\ :sub:`2`: Write\ :sub:`prev` + + * - t\ :sub:`4` + - Primary is aware of successful replication to Secondary\ :sub:`2` + + - | **Primary**: Write\ :sub:`0` + | **Secondary**\ :sub:`1`: Write\ :sub:`0` + | **Secondary**\ :sub:`2`: Write\ :sub:`0` + + - | **Primary**: Write\ :sub:`0` + | **Secondary**\ :sub:`1`: Write\ :sub:`prev` + | **Secondary**\ :sub:`2`: Write\ :sub:`prev` + + * - t\ :sub:`5` + - Secondary\ :sub:`1` receives notice (through regular replication mechanism) to update its snapshot of its most recent w: "majority" write + + - | **Primary**: Write\ :sub:`0` + | **Secondary**\ :sub:`1`: Write\ :sub:`0` + | **Secondary**\ :sub:`2`: Write\ :sub:`0` + + - | **Primary**: Write\ :sub:`0` + | **Secondary**\ :sub:`1`: Write\ :sub:`0` + | **Secondary**\ :sub:`2`: Write\ :sub:`prev` + + * - t\ :sub:`6` + - Secondary\ :sub:`2` receives notice (through regular replication mechanism) to update its snapshot of its most recent w: "majority" write + + - | **Primary**: Write\ :sub:`0` + | **Secondary**\ :sub:`1`: Write\ :sub:`0` + | **Secondary**\ :sub:`2`: Write\ :sub:`0` + + - | **Primary**: Write\ :sub:`0` + | **Secondary**\ :sub:`1`: Write\ :sub:`0` + | **Secondary**\ :sub:`2`: Write\ :sub:`0` diff --git a/source/includes/fact-readConcern-syntax.rst b/source/includes/fact-readConcern-syntax.rst index a2f25c8fdba..4c0ece57f43 100644 --- a/source/includes/fact-readConcern-syntax.rst +++ b/source/includes/fact-readConcern-syntax.rst @@ -4,11 +4,4 @@ The readConcern option has the following syntax: .. code-block:: javascript - readConcern: { level: , - afterClusterTime: } - -.. important:: - - Do not manually set the ``afterClusterTime``. MongoDB drivers set - this value automatically for operations associated with - :ref:`causally consistent sessions `. + readConcern: { level: } diff --git a/source/reference/read-concern-available.txt b/source/reference/read-concern-available.txt new file mode 100644 index 00000000000..bdd2cd82a0d --- /dev/null +++ b/source/reference/read-concern-available.txt @@ -0,0 +1,89 @@ +.. default-domain:: mongodb + +.. class:: hidden + + .. readconcern:: "available" + +============================ +Read Concern ``"available"`` +============================ + +.. meta:: + :description: read concern, available read concern, read isolation + :keywords: read concern, available read concern, read isolation + +.. versionadded:: 3.6 + +A query with read concern `"available"` returns the instance's most +recent data. Read concern `"available"` provides no guarantee that the +data has been written to a majority of the replica set members (i.e. +may be rolled back). + +Read concern `"available"` is the default for reads against secondaries +if the reads are not associated with :ref:`causally consistent sessions +`. + +For a sharded cluster, :readconcern:`"available"` read concern provides +greater tolerance for partitions since it does not wait to ensure +consistency guarantees. However, a query with +:readconcern:`"available"` read concern may return orphan documents if +the shard is undergoing chunk migrations since the +:readconcern:`"available"` read concern, unlike :readconcern:`"local"` +read concern, does not contact the shard's primary nor the config +servers for updated :doc:`metadata +`. + +For unsharded collections (including collections in a standalone +deployment or a replica set deployment), :readconcern:`"local"` and +:readconcern:`"available"` read concerns behave identically. + +.. include:: /includes/fact-readConcern-most-recent-data-in-node.rst + +.. seealso:: :parameter:`orphanCleanupDelaySecs` + +Causally Consistent Sessions +---------------------------- + +Read concern :readconcern:`available` is unavailable for use with +causally consistent sessions. + +Example +------- + +.. include:: /includes/fact-read-concern-write-timeline.rst + +Then, the following tables summarizes the state of the data that a read +operation with :readconcern:`"available"` read concern would see at +time ``T``. + +.. figure:: /images/read-concern-write-timeline.svg + :alt: Timeline of a write operation to a three member replica set. + :figwidth: 330px + +.. list-table:: + :header-rows: 1 + :widths: 40 30 30 + + * - Read Target + - Time ``T`` + - State of Data + + * - Primary + - After t\ :sub:`0` + - Data reflects Write\ :sub:`0`. + + * - Secondary\ :sub:`1` + - Before t\ :sub:`1` + - Data reflects Write\ :sub:`prev` + + * - Secondary\ :sub:`1` + - After t\ :sub:`1` + - Data reflects Write\ :sub:`0` + + * - Secondary\ :sub:`2` + - Before t\ :sub:`2` + - Data reflects Write\ :sub:`prev` + + * - Secondary\ :sub:`2` + - After t\ :sub:`2` + - Data reflects Write\ :sub:`0` diff --git a/source/reference/read-concern-linearizable.txt b/source/reference/read-concern-linearizable.txt new file mode 100644 index 00000000000..e201c775ec1 --- /dev/null +++ b/source/reference/read-concern-linearizable.txt @@ -0,0 +1,94 @@ +.. default-domain:: mongodb + +.. class:: hidden + + .. readconcern:: "linearizable" + +=============================== +Read Concern ``"linearizable"`` +=============================== + +.. versionadded:: 3.4 + +The query returns data that reflects all successful +majority-acknowledged writes that completed prior to the start of the +read operation. The query may wait for concurrently executing writes to +propagate to a majority of replica set members before returning results. + +If a majority of your replica set members crash and restart after the +read operation, documents returned by the read operation are durable if +:rsconf:`writeConcernMajorityJournalDefault` is set to the default +state of ``true``. + +.. include:: /includes/extracts/no-journaling-rollback.rst + +You can specify linearizable read concern for read operations on +the :replstate:`primary ` only. + +Linearizable read concern guarantees only apply if read +operations specify a query filter that uniquely identifies a +single document. + +.. tip:: + + Always use ``maxTimeMS`` with linearizable read concern in case a + majority of data bearing members are unavailable. ``maxTimeMS`` + ensures that the operation does not block indefinitely and instead + ensures that the operation returns an error if the read concern + cannot be fulfilled. + +Causally Consistent Sessions +---------------------------- + +Read concern :readconcern:`linearizable` is unavailable for use with +causally consistent sessions. + +Real Time Order +--------------- + +Combined with :writeconcern:`"majority"` write concern, +:readconcern:`"linearizable"` read concern enables multiple threads to +perform reads and writes on a single document as if a single thread +performed these operations in real time; that is, the corresponding +schedule for these reads and writes is considered linearizable. + +Read Your Own Writes +-------------------- + +.. versionchanged:: 3.6 + +.. include:: /includes/fact-read-own-writes.rst + +Performance Comparisons +----------------------- + +Unlike :readconcern:`"majority"`, :readconcern:`"linearizable"` read +concern confirms with secondary members that the read operation is +reading from a primary that is capable of confirming writes with +:writeconcern:`{ w: "majority" } <"majority">` write concern. +[#edge-cases-2-primaries]_ As such, reads with linearizable read +concern may be significantly slower than reads with +:readconcern:`"majority"` or :readconcern:`"local"` read concerns. + +Always use ``maxTimeMS`` with linearizable read concern in case a +majority of data bearing members are unavailable. ``maxTimeMS`` ensures +that the operation does not block indefinitely and instead ensures that +the operation returns an error if the read concern cannot be fulfilled. + +For example: + +.. code-block:: javascript + + db.restaurants.find( { _id: 5 } ).readConcern("linearizable").maxTimeMS(10000) + + db.runCommand( { + find: "restaurants", + filter: { _id: 5 }, + readConcern: { level: "linearizable" }, + maxTimeMS: 10000 + } ) + +.. [#edge-cases-2-primaries] + + .. include:: /includes/footnote-two-primaries-edge-cases.rst + diff --git a/source/reference/read-concern-local.txt b/source/reference/read-concern-local.txt new file mode 100644 index 00000000000..96be6feaef9 --- /dev/null +++ b/source/reference/read-concern-local.txt @@ -0,0 +1,75 @@ +.. default-domain:: mongodb + +.. class:: hidden + + .. readconcern:: "local" + +======================== +Read Concern ``"local"`` +======================== + +.. meta:: + :description: read concern, local read concern, read isolation + :keywords: read concern, local read concern, read isolation + + +A query with read concern ``"local"`` returns the instance's most +recent data. Read concern ``"local"`` provides no guarantee that the +data has been written to a majority of the replica set members (i.e. +may be rolled back). + +Read concern ``"local"`` is the default for: + +- read operations against primary + +- read operations against secondaries if the reads are associated with + :ref:`causally consistent sessions `. + +.. include:: /includes/fact-readConcern-most-recent-data-in-node.rst + +Causally Consistent Sessions +---------------------------- + +Read concern :readconcern:`local` is available for use with causally +consistent sessions. + +Example +------- + +.. include:: /includes/fact-read-concern-write-timeline.rst + +Then, the following tables summarizes the state of the data that a read +operation with :readconcern:`"local"` read concern would see at +time ``T``. + +.. figure:: /images/read-concern-write-timeline.svg + :alt: Timeline of a write operation to a three member replica set. + :figwidth: 330px + +.. list-table:: + :header-rows: 1 + + * - Read Target + - Time ``T`` + - State of Data + + * - Primary + - After t\ :sub:`0` + - Data reflects Write\ :sub:`0`. + + * - Secondary\ :sub:`1` + - Before t\ :sub:`1` + - Data reflects Write\ :sub:`prev` + + * - Secondary\ :sub:`1` + - After t\ :sub:`1` + - Data reflects Write\ :sub:`0` + + * - Secondary\ :sub:`2` + - Before t\ :sub:`2` + - Data reflects Write\ :sub:`prev` + + * - Secondary\ :sub:`2` + - After t\ :sub:`2` + - Data reflects Write\ :sub:`0` + diff --git a/source/reference/read-concern-majority.txt b/source/reference/read-concern-majority.txt new file mode 100644 index 00000000000..726ddb5f8f2 --- /dev/null +++ b/source/reference/read-concern-majority.txt @@ -0,0 +1,97 @@ +.. default-domain:: mongodb + +.. class:: hidden + + .. readconcern:: "majority" + +=========================== +Read Concern ``"majority"`` +=========================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +A query with read concern ``"majority"`` returns the instance's most +recent data that has been acknowledged by a majority of the replica set +members. + +.. include:: /includes/fact-enable-majority-readConcern.rst + +.. include:: /includes/fact-readConcern-most-recent-data-in-node.rst + + +Example +------- + +.. include:: /includes/fact-read-concern-write-timeline.rst + +Then, the following tables summarizes the state of the data that a read +operation with :readconcern:`"majority"` read concern would see at +time ``T``. + +.. figure:: /images/read-concern-write-timeline.svg + :alt: Timeline of a write operation to a three member replica set. + :figwidth: 330px + + +.. list-table:: + :header-rows: 1 + + * - Read Target + - Time ``T`` + - State of Data + + * - Primary + - Before t\ :sub:`3` + - Data reflects Write\ :sub:`prev` + + * - Primary + - After t\ :sub:`3` + - Data reflects Write\ :sub:`0` + + * - Secondary\ :sub:`1` + - Before t\ :sub:`5` + - Data reflects Write\ :sub:`prev` + + * - Secondary\ :sub:`1` + - After t\ :sub:`5` + - Data reflects Write\ :sub:`0` + + * - Secondary\ :sub:`2` + - Before or at t\ :sub:`6` + - Data reflects Write\ :sub:`prev` + + * - Secondary\ :sub:`2` + - After t\ :sub:`6` + - Data reflects Write\ :sub:`0` + +Storage Engine Support +---------------------- + +Read concern :readconcern:`"majority"` is available for the +WiredTiger storage engine. + +.. tip:: + + The :dbcommand:`serverStatus` command returns the + :serverstatus:`storageEngine.supportsCommittedReads` field which + indicates whether the storage engine supports ``"majority"`` read + concern. + +Causally Consistent Sessions +---------------------------- + +Read concern :readconcern:`majority` is available for use with causally +consistent sessions. + +Read Your Own Writes +-------------------- + +.. versionchanged:: 3.6 + +.. include:: /includes/fact-read-own-writes.rst + + diff --git a/source/reference/read-concern.txt b/source/reference/read-concern.txt index b38162e2ad5..bd567acad98 100644 --- a/source/reference/read-concern.txt +++ b/source/reference/read-concern.txt @@ -4,8 +4,6 @@ Read Concern ============ -.. versionadded:: 3.2 - .. default-domain:: mongodb .. contents:: On this page @@ -14,24 +12,19 @@ Read Concern :depth: 1 :class: singlecol -.. versionchanged:: 3.4 - Adds support for :readconcern:`"linearizable"` read concern level. - -.. versionchanged:: 3.6 - Adds support for: +The ``readConcern`` option allows you to control the recency, +consistency, and isolation properties of the data read from replica +sets and replica set shards. - - :readconcern:`"available"` read concern level. +Through the effective use of :doc:`write concerns +` and read concerns, you can adjust the level +of consistency and availability guarantees as appropriate, such as +waiting for stronger consistency guarantees, or loosening consistency +requirements to provide higher availability. - - :ref:`afterClusterTime` for :readconcern:`"local"` and - :readconcern:`"majority"` read concern levels. -The ``readConcern`` query option for replica sets and replica set -shards determines which data to return from a query. - -.. code-block:: javascript - - readConcern: { level: <"majority"|"local"|"linearizable"|"available"> } - readConcern: { level: <"majority"|"local"> , afterClusterTime: } +MongoDB drivers updated for MongoDB 3.2 or later support specifying +read concern. .. _read-concern-levels: @@ -47,52 +40,63 @@ The following read concern levels are available: * - ``level`` - Description - * - .. readconcern:: "local" - - - Default for reads against primary if ``level`` is unspecified - and for reads against secondaries if ``level`` is unspecified but - :ref:`afterClusterTime` is specified. + * - :readconcern:`"local"` - The query returns the instance's most recent data. Provides no + - The query returns the instance's most recent data. Provides no guarantee that the data has been written to a majority of the replica set members (i.e. may be rolled back). - * - .. readconcern:: "available" + Default for: + - reads against primary + + - reads against secondaries if the reads are + associated with :ref:`causally consistent sessions `. + + Read concern :readconcern:`local` is available for use with + causally consistent sessions. + + For more information, see the :readconcern:`"local"` reference + page. - - Default for reads against secondaries when - :ref:`afterClusterTime` and ``level`` are unspecified. + * - :readconcern:`"available"` - The query returns the instance's most recent data. Provides no + - The query returns the instance's most recent data. Provides no guarantee that the data has been written to a majority of the replica set members (i.e. may be rolled back). - For unsharded collections (including collections in a standalone - deployment or a replica set deployment), :readconcern:`"local"` - and :readconcern:`"available"` read concerns behave identically. + Default for reads against secondaries if the reads are not + associated with :ref:`causally consistent sessions `. - For a sharded cluster, :readconcern:`"available"` read concern - provides greater tolerance for partitions since it does not wait - to ensure consistency guarantees. However, a query with - :readconcern:`"available"` read concern may return orphan - documents if the shard is undergoing chunk migrations since the - :readconcern:`"available"` read concern, unlike - :readconcern:`"local"` read concern, does not contact the - shard's primary nor the config servers for updated - :doc:`metadata `. + For sharded collections, :readconcern:`"available"` read concern + provides the lowest latency reads possible among the various read + concerns but at the expense of consistency as + :readconcern:`"available"` read concern can return orphan + documents. - .. seealso:: :parameter:`orphanCleanupDelaySecs` + Read concern :readconcern:`available` is unavailable for use + with causally consistent sessions. + + For more information, see the :readconcern:`"available"` + reference page. .. versionadded:: 3.6 - * - .. readconcern:: "majority" + * - :readconcern:`"majority"` - - The query returns the instance's most recent data acknowledged - as having been written to a majority of members in the replica - set. + - The query returns the instance's most recent data that has been + acknowledged by a majority of the replica set members. The + documents returned by the read operation are durable, even in + the event of failure. .. include:: /includes/fact-enable-majority-readConcern.rst - * - .. readconcern:: "linearizable" + Read concern :readconcern:`majority` is available for use with + causally consistent sessions. + + For more information, see the :readconcern:`"majority"` + reference page. + + * - :readconcern:`"linearizable"` - The query returns data that reflects all successful majority-acknowledged writes that completed prior to the start @@ -110,6 +114,9 @@ The following read concern levels are available: You can specify linearizable read concern for read operations on the :replstate:`primary ` only. + Read concern :readconcern:`linearizable` is unavailable for use + with causally consistent sessions. + Linearizable read concern guarantees only apply if read operations specify a query filter that uniquely identifies a single document. @@ -122,62 +129,38 @@ The following read concern levels are available: indefinitely and instead ensures that the operation returns an error if the read concern cannot be fulfilled. - Linearizable read concern is available for both MMAPv1 and - WiredTiger. See :ref:`read-concern-storage-engine-drivers`. - - .. versionadded:: 3.4 + For more information, see the :readconcern:`"linearizable"` + reference page. .. include:: /includes/fact-readConcern-most-recent-data-in-node.rst -.. _read-concern-storage-engine-drivers: - -Storage Engine and Drivers Support ----------------------------------- - -.. list-table:: - :header-rows: 1 - :widths: 50 30 20 - - * - Read Concern - - WiredTiger - - MMAPv1 - - * - :readconcern:`"local"` - - |checkmark| - - |checkmark| - - * - :readconcern:`"majority"` - - |checkmark| - - - - * - :readconcern:`"linearizable"` - - |checkmark| - - |checkmark| +For more information on each read concern level, see: -.. tip:: +.. toctree:: + :titlesonly: - The :dbcommand:`serverStatus` command returns the - :serverstatus:`storageEngine.supportsCommittedReads` field which - indicates whether the storage engine supports ``"majority"`` read - concern. + /reference/read-concern-local + /reference/read-concern-available + /reference/read-concern-majority + /reference/read-concern-linearizable -MongoDB drivers updated for 3.2 and later versions support specifying -a read concern option. - -.. include:: /includes/unicode-checkmark.rst - -``readConcern`` Option +``readConcern`` Syntax ---------------------- -.. versionchanged:: 3.6 - -Use the ``readConcern`` option to specify the read concern level [#after-cluster-time]_ : +You can specify a ``readConcern`` level [#after-cluster-time]_ as an +option: .. code-block:: javascript - readConcern: { level: <"majority"|"local"|"linearizable"> } + readConcern: { level: <"majority"|"local"|"linearizable"|"available"> } + +.. note:: -The ``readConcern`` option is available for the following operations: + For operations in :ref:`causally consistent sessions + `, only :readconcern:`"local"` and + :readconcern:`"majority"` levels are available. + +The following operations support the ``readConcern`` option: - :dbcommand:`find` command @@ -194,15 +177,21 @@ The ``readConcern`` option is available for the following operations: - :dbcommand:`geoSearch` command +- :dbcommand:`group` command + To specify the read concern level for the :binary:`~bin.mongo` shell method :method:`db.collection.find()`, use the :method:`cursor.readConcern()` -method. +method: + +.. code-block:: javascript + + db.collection.find().readConcern(<"majority"|"local"|"linearizable"|"available">) .. [#after-cluster-time] For :ref:`causally consistent sessions `, - MongoDB drivers automatically specifies the :ref:`afterClusterTime` - value in the read concern. + MongoDB drivers automatically specifies the :ref:`afterClusterTime + ` value in the read concern. Considerations -------------- @@ -252,22 +241,26 @@ For example: maxTimeMS: 10000 } ) +.. [#edge-cases-2-primaries] + + .. include:: /includes/footnote-two-primaries-edge-cases.rst + .. _afterClusterTime: -``afterClusterTime`` -~~~~~~~~~~~~~~~~~~~~ +Read Operations and Causally Consistent Sessions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. versionadded:: 3.6 -MongoDB 3.6 introduces the ``afterClusterTime`` option that can be set -by the drivers. 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 :binary:`~bin.mongod` must wait to service the request. +MongoDB 3.6 introduces support for :ref:`causally consistent sessions +`. For read operations associated with causally consistent +session, MongoDB 3.6 introduces the ``afterClusterTime`` read concern +option to be set automatically by the drivers for operations associated +with causally consistent sessions. -Read operations with a specified ``afterClusterTime`` -return data that meet both the :ref:`read concern level ` -requirement and the specified ``afterClusterTime`` requirement. +The ``afterClusterTime`` read concern option is available for +:readconcern:`"local"` and :readconcern:`"majority"` read +concern levels: .. important:: @@ -275,24 +268,18 @@ requirement and the specified ``afterClusterTime`` requirement. this value automatically for operations associated with causally consistent sessions. -Causally consistent sessions use the ``afterClusterTime`` value to -provide causal consistency. - -``afterClusterTime`` is available for :readconcern:`"local"` (default) -and :readconcern:`"majority"` read concern levels: - .. code-block:: javascript readConcern: { level: <"majority"|"local"> , afterClusterTime: } -For read operations not associated with causally consistent sessions, -i.e. where ``afterClusterTime`` is unset, reads against secondary -members have the default read concern level :readconcern:`"available"`, -meaning that queries will return the instance’s most recent data. -:readconcern:`"available"` provides no guarantee that data has been -written to a majority of the replica set members. It might be rolled -back. +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 +:binary:`~bin.mongod` must wait to service the request. -.. [#edge-cases-2-primaries] +Read operations with a specified ``afterClusterTime`` return data that +meet both the :ref:`read concern level ` +requirement and the specified ``afterClusterTime`` requirement. - .. include:: /includes/footnote-two-primaries-edge-cases.rst +For read operations not associated with causally consistent sessions, +``afterClusterTime`` is unset.