DOCS-5324 quorum reads with findAndModify

Author: kay-kim

source/includes/fact-findAndModify-update-comparison.rst

@@ -13,7 +13,7 @@ When updating a document, |operation| and the
   method, you cannot specify which single document to update when
   multiple documents match.
 
-- By default, |operation| method returns |return-object|. To
+- By default, |operation| returns |return-object|. To
   obtain the updated document, use the ``new`` option.
 
   The :method:`~db.collection.update()` method returns a

source/includes/steps-findAndModify-quorum-reads.yaml

@@ -0,0 +1,92 @@
+title: Create a unique index.
+stepnum: 1
+ref: quorum-read-unique-index
+pre: |
+  Create a unique index on the fields that will be used to specify an
+  exact match in the :method:`db.collection.findAndModify()` operation.
+
+  This tutorial will use an exact match on the ``sku`` field. As such,
+  create a unique index on the ``sku`` field.
+action:
+  language: javascript
+  code: |
+    db.products.createIndex( { sku: 1 }, { unique: true } )
+---
+title: Use ``findAndModify`` to read committed data.
+stepnum: 2
+ref: quorum-read-findAndModify
+pre: |
+  Use the :method:`db.collection.findAndModify()` method to make a
+  trivial update to the document you want to read and return the
+  modified document. To specify the document to read, you must use an
+  exact match query that is supported by a unique index.
+
+  The following :method:`~db.collection.findAndModify()` operation
+  specifies an exact match on the uniquely indexed field ``sku`` and
+  increments the field named ``_dummy_field`` in the matching document.
+action:
+  language: javascript
+  code: |
+    var updatedDocument = db.products.findAndModify(
+       {
+         query: { sku: "abc123" },
+         update: { $inc: { _dummy_field: 1 } },
+         new: true
+       }
+    );
+---
+title: Issue ``getLastError`` to determine quorum read.
+stepnum: 3
+ref: quorum-read-gle
+pre: |
+  To determine if the read from the
+  :method:`~db.collection.findAndModify()` was a true quorum read,
+  issue a :dbcommand:`getLastError` command with :writeconcern:`w:
+  "majority"`.
+
+  While not necessary to the procedure, the
+  :dbcommand:`getLastError` command also includes a :ref:`wc-wtimeout`
+  value of ``5000`` milliseconds to prevent the operation from blocking
+  forever if the write cannot propagate to a majority of voting members.
+action:
+  language: javascript
+  code: |
+    var gle = db.runCommand( { getLastError: 1, w: "majority", wtimeout: 5000 } );
+
+    if ( (gle.ok != 1) || (gle.err != null) ) {
+      print("The document returned from findAndModify() may reflect data that is not durable and subject to rollback.");
+      printjson(gle);
+    } else {
+      printjson(updatedDocument);
+    }
+post: |
+   The :dbcommand:`getLastError` determines whether the update from
+   the :method:`~db.collection.findAndModify()` operation has
+   propagated to the majority of the replica set's voting members.
+
+   Even in situations where two nodes in the replica set believe that
+   they are the primary, only one will be able to complete the write
+   with :writeconcern:`w: "majority"`. As such, the
+   :dbcommand:`getLastError` with :writeconcern:`w: "majority"` write
+   concern can confirm whether the client has connected to the true
+   primary to perform the :method:`~db.collection.findAndModify()`
+   operation.
+
+   .. note::
+      :ref:`wc-wtimeout` causes :dbcommand:`getLastError` to return
+      with an error after the specified time limit, even if the
+      required write concern will eventually succeed. As such, if the
+      :dbcommand:`getLastError` times out, it cannot determine whether
+      the document returned by :method:`~db.collection.findAndModify()`
+      is or is not the result of a quorum read. For quorum reads,
+      ignore the document returned by
+      :method:`~db.collection.findAndModify()` and repeat the
+      :method:`~db.collection.findAndModify()` and
+      :dbcommand:`getLastError`.
+
+      Since the quorum read procedure only increments a dummy field in
+      the document, you can safely repeat the
+      :method:`~db.collection.findAndModify()` and
+      :dbcommand:`getLastError`, adjusting the :ref:`wc-wtimeout` as
+      necessary.
+...

source/includes/toc-crud-tutorials.yaml

@@ -52,4 +52,8 @@ file: /tutorial/create-an-auto-incrementing-field
 description: |
   Describes how to create an incrementing sequence number for the
   ``_id`` field using a Counters Collection or an Optimistic Loop.
+---
+file: /tutorial/perform-findAndModify-quorum-reads
+description: |
+  Perform quorum reads using ``findAndModify``.
 ...

source/reference/command/findAndModify.txt

@@ -418,3 +418,5 @@ The method returns the deleted document:
      },
      "ok" : 1
    }
+
+.. seealso:: :doc:`/tutorial/perform-findAndModify-quorum-reads`

source/reference/method/db.collection.findAndModify.txt

@@ -287,3 +287,5 @@ The method returns the deleted document:
       "state" : "active",
       "rating" : 3
    }
+
+.. seealso:: :doc:`/tutorial/perform-findAndModify-quorum-reads`

source/reference/write-concern.txt

@@ -40,31 +40,32 @@ concern on to the shard.
 ``w`` Option
 ~~~~~~~~~~~~
 
-The ``w`` option provides the ability to disable write concern entirely
-*as well as* specify the write concern for :term:`replica sets <replica
-set>`.
+The ``w`` option provides the ability to specify the write concern for
+:term:`replica sets <replica set>` *as well as* disable write concern
+entirely.
 
 MongoDB uses ``w: 1`` as the default write concern. ``w: 1``
 provides basic receipt acknowledgment.
 
-The ``w`` option accepts the following values:
+Using the ``w`` option, the following ``w: <value>`` write concerns are
+available:
 
 .. list-table::
    :header-rows: 1
-   :widths: 25 75
+   :widths: 30 70
 
    * - Value
 
      - Description
 
-   * - ``1``
+   * - .. writeconcern:: w: 1
 
      - Provides acknowledgment of write operations on a standalone
        :program:`mongod` or the :term:`primary` in a replica set.
 
        This is the default write concern for MongoDB.
 
-   * - ``0``
+   * - .. writeconcern:: w: 0
 
      - Disables basic acknowledgment of write operations, but returns
        information about socket exceptions and networking errors to the
@@ -75,7 +76,7 @@ The ``w`` option accepts the following values:
        the server will require that :program:`mongod` acknowledge
        the write operation.
 
-   * - <Number greater than 1>
+   * - .. writeconcern:: w: <Number greater than 1>
 
      - Guarantees that write operations have propagated successfully to
        the specified number of replica set members including the
@@ -89,7 +90,7 @@ The ``w`` option accepts the following values:
        members to become available, which means MongoDB blocks
        indefinitely.
 
-   * - ``"majority"``
+   * - .. writeconcern:: w: "majority"
 
      - Confirms that write operations have propagated to the majority
        of voting nodes: a majority of the replica set's
@@ -103,7 +104,7 @@ The ``w`` option accepts the following values:
 
        .. include:: /includes/fact-master-slave-majority.rst
 
-   * - <tag set>
+   * - .. writeconcern:: w: <tag set>
 
      - By specifying a :ref:`tag set
        <replica-set-configuration-tag-sets>`, you can have fine-grained

source/tutorial/perform-findAndModify-quorum-reads.txt

@@ -0,0 +1,82 @@
+====================================
+Perform Quorum Reads on Replica Sets
+====================================
+
+.. default-domain:: mongodb
+
+Overview
+--------
+
+When reading from replica sets, in some edge cases, clients can
+read stale data even when specifying a :readmode:`primary` read
+preference. [#edge-cases-2-primaries]_ Clients may also see results of
+writes before they are made durable and before they have propagated to
+enough replica set members to avoid rollbacks.
+
+This tutorial outlines a procedure that uses
+:method:`db.collection.findAndModify()` to read data that is not stale
+and cannot be rolled back. To do so, the procedure uses the
+:method:`db.collection.findAndModify()` method to modify a dummy field
+in a document and issues a :dbcommand:`getLastError` command to confirm
+that the :method:`db.collection.findAndModify()` operation has
+propagated to enough members to avoid rollbacks. Specifically, the
+procedure requires that:
+
+- :method:`db.collection.findAndModify()` use an **exact** match query,
+  and a :doc:`unique index </core/index-unique>` **must exist** to
+  satisfy the query.
+
+- :method:`db.collection.findAndModify()` must actually modify a
+  document; i.e. result in a change to the document.
+
+- :dbcommand:`getLastError` must use the write concern
+  :writeconcern:`w: "majority"`.
+
+Prerequisites
+-------------
+
+This tutorial reads from a collection named ``products``. Initialize
+the collection using the following operation.
+
+.. code-block:: javascript
+
+   db.products.insert( [
+      {
+        _id: 1,
+        sku: "xyz123",
+        description: "hats",
+        available: [ { quantity: 25, size: "S" }, { quantity: 50, size: "M" } ],
+        _dummy_field: 0
+      },
+      {
+        _id: 2,
+        sku: "abc123",
+        description: "socks",
+        available: [ { quantity: 10, size: "L" } ],
+        _dummy_field: 0
+      },
+      {
+        _id: 3,
+        sku: "ijk123",
+        description: "t-shirts",
+        available: [ { quantity: 30, size: "M" }, { quantity: 5, size: "L" } ],
+        _dummy_field: 0
+      }
+   ] )
+
+The documents in this collection contain a dummy field named
+``_dummy_field`` that will be incremented by the
+:method:`db.collection.findAndModify()` in the tutorial. If the field
+does not exist, the :method:`db.collection.findAndModify()` operation
+will add the field to the document. The purpose of the field is to
+ensure that the :method:`db.collection.findAndModify()` results in a
+modification to the document.
+
+Procedure
+---------
+
+.. include:: /includes/steps/findAndModify-quorum-reads.rst
+
+.. [#edge-cases-2-primaries]
+
+   .. include:: /includes/footnote-two-primaries-edge-cases.rst