Reorg read concern in prep for 4.0

Author: kay-kim

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

source/images/read-concern-write-timeline.svg

@@ -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`

source/includes/fact-read-concern-write-timeline.rst

@@ -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
+<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
+</core/sharded-cluster-config-servers>`.
+
+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`

source/reference/read-concern-available.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 <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
+