DOCS-15411 commit quorum v write concern (#2009)

* DOCS-15411 commitQuorum-and-writeConcerns

* DOCS-15411 commitQuorum-and-writeConcerns

* Staging fixes

* Staging fixes

* Review feedback

* Staging fixes

* Review Feedback

* Review Feedback

* Review feedback

* Review feedback

* Staging fixes

* Review feedback

* Review feedback

* Commit feedback

Author: Dave Cuthbert

source/core/index-creation.txt

@@ -226,6 +226,11 @@ index build, use the :dbcommand:`setIndexCommitQuorum` command.
    - For rolling index builds on sharded clusters, see
      :doc:`/tutorial/build-indexes-on-sharded-clusters`.
 
+Commit Quorum Contrasted with Write Concern
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: /includes/indexes/commit-quorum-vs-write-concern.rst
+
 .. _index-operations-build-failure:
 
 Build Failure and Recovery

source/includes/indexes/commit-quorum-vs-write-concern.rst

@@ -0,0 +1,22 @@
+There are important differences between :ref:`commit quorums
+<createIndexes-cmd-commitQuorum>` and :ref:`write concerns
+<write-concern>`:
+
+- Index builds use **commit quorums**.
+- Write operations use **write concerns**. 
+
+Each data-bearing node in a cluster is a voting member.
+
+The **commit quorum** specifies how many data-bearing voting members, or
+which voting members, including the primary, must be prepared to commit
+a :ref:`simultaneous index build <index-operations-simultaneous-build>`.
+before the primary will execute the commit.
+
+The **write concern** is the level of acknowledgement that the write has
+propagated to the specified number of instances.
+
+The **commit quorum** specifies how many nodes must be *ready* to finish
+the index build before the primary commits the index build. In contrast,
+when the primary has committed the index build, the **write concern**
+specifies how many nodes must *finish* the index build before the
+command returns.

source/includes/indexes/commit-quorum.rst

@@ -0,0 +1,23 @@
+Index creation is a :ref:`multistage process <index-build-process>`. 
+Starting in MongoDB 4.4, the index creation process uses the ``commit
+quorum`` to minimize replication lag on secondary nodes.
+
+When a secondary node receives a ``commitIndexBuild`` oplog entry, the 
+node stops further oplog applications until the local index build can be
+committed. Index builds can take anywhere from moments to days to
+complete, so the replication lag can be significant if the secondary
+node builds more slowly than the primary. 
+
+To manage the replication lag, the commit quorum delays committing the
+index build on the primary node until a minimum number of secondaries
+are also ready to commit the index build. 
+
+The commit quorum does not guarantee that indexes on secondaries are
+ready for use when the command completes. To ensure that a specific
+number of secondaries are ready for use, set an appropriate :ref:`write
+concern <write-concern>`.
+
+If a secondary node that is not included in the commit quorum receives
+a ``commitIndexBuild`` oplog entry, the node may block replication until
+its index build is complete.
+

source/includes/indexes/template-commit-quorum-intro.rst

@@ -0,0 +1,8 @@
+To set the :ref:`commit quorum <createIndexes-cmd-commitQuorum>`, use
+|updateMethod-name| to specify the ``commitQuorum`` value.
+
+``commitQuorum`` specifies how many data-bearing voting members, or
+which voting members, including the primary, must be prepared to commit
+the index build before the primary will execute the commit. The default
+commit quorum is ``votingMembers``, which means all data-bearing
+members.

source/reference/command/createIndexes.txt

@@ -7,7 +7,7 @@ createIndexes
 .. contents:: On this page
    :local:
    :backlinks: none
-   :depth: 1
+   :depth: 2
    :class: singlecol
 
 Definition
@@ -730,6 +730,11 @@ Transactions
 .. |operation| replace:: :dbcommand:`createIndexes`
 
 
+Commit Quorum Contrasted with Write Concern
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: /includes/indexes/commit-quorum-vs-write-concern.rst
+
 Example
 -------
 
@@ -991,12 +996,8 @@ Create Index With Commit Quorum
 
 .. include:: /includes/extracts/4.4-changes-index-builds-simultaneous.rst
 
-Specify the :ref:`commitQuorum <createIndexes-cmd-commitQuorum>` option
-to the :dbcommand:`createIndexes` operation to set the minimum
-number of data-bearing voting members (i.e commit quorum), including the
-primary, which must complete the index build before the
-primary marks the indexes as ready. The default commit quorum is
-``votingMembers``, or all data-bearing replica set members.
+.. |updateMethod-name| replace::  :dbcommand:`createIndexes`
+.. include:: /includes/indexes/template-commit-quorum-intro.rst
 
 The following operation creates an index with a :ref:`commit quorum
 <createIndexes-cmd-commitQuorum>` of ``"majority"``, or a 

source/reference/command/setIndexCommitQuorum.txt

@@ -14,10 +14,9 @@ setIndexCommitQuorum
 
 .. dbcommand:: setIndexCommitQuorum
 
-   Changes the minimum number of data-bearing members (i.e commit
-   quorum), including the primary, that must complete an in-progress
-   :ref:`simultaneous index build <index-operations-simultaneous-build>`
-   before the primary marks those indexes as ready.
+   The ``setIndexCommitQuorum`` command sets minimum number of
+   data-bearing members that must be prepared to commit their local
+   index builds before the primary node will commit the index.
 
 Syntax
 ------
@@ -81,8 +80,9 @@ The command takes the following fields:
        :ref:`interrupted index builds <index-operations-build-failure>`
        when the commit quorum is set to ``"votingMembers"``. 
 
-       Replica set nodes in a commit quorum must have :rsconf:`members[n].buildIndexes` 
-       set to ``true``. If any voting nodes have ``members[n].buildIndexes`` 
+       To update the commitQuorum, member replica set nodes must have
+       :rsconf:`members[n].buildIndexes` set to ``true``. If any voting
+       nodes have ``members[n].buildIndexes`` 
        set to ``false``, you can't use the default ``"votingMembers"`` commit 
        quorum. Either configure all nodes with ``members[n].buildIndexes`` 
        set to ``true``, or select a different commit quorum. 
@@ -116,6 +116,8 @@ Behavior
 
 .. include:: /includes/extracts/4.4-changes-index-builds-simultaneous-fcv.rst
 
+.. include:: /includes/indexes/commit-quorum.rst
+
 Issuing :dbcommand:`setIndexCommitQuorum` has no effect on index builds
 started with :ref:`commitQuorum <createIndexes-cmd-commitQuorum>` of
 ``0``. 
@@ -125,6 +127,14 @@ started with :ref:`commitQuorum <createIndexes-cmd-commitQuorum>` of
    Replica set nodes with :ref:`buildIndexes <replica-set-configuration-buildIndexes>` 
    set to ``false`` can't be included in a commit quorum.
 
+.. _commit-quorum-contrasted-with-write-concern:
+
+Commit Quorum Contrasted with Write Concern
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: /includes/indexes/commit-quorum-vs-write-concern.rst
+
+
 Examples
 --------
 

source/reference/glossary.txt

@@ -193,6 +193,12 @@ Glossary
       indexes. See :doc:`/core/query-optimization` for details about
       query execution strategies.
 
+   commit quorum
+      During an :ref:`index build <index-operations-replicated-build>`
+      the :ref:`commit quorum <createIndexes-cmd-commitQuorum>`
+      specifies how many secondaries must be ready to commit their local
+      index build before the primary node will execute the commit.
+
    compound index
       An :term:`index` consisting of two or more keys. See
       :ref:`index-type-compound`.

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

@@ -9,7 +9,7 @@ db.collection.createIndex()
 .. contents:: On this page
    :local:
    :backlinks: none
-   :depth: 1
+   :depth: 2
    :class: singlecol
 
 Definition
@@ -1008,13 +1008,8 @@ Create Index With Commit Quorum
 
 .. include:: /includes/extracts/4.4-changes-index-builds-simultaneous.rst
 
-Specify the :ref:`commitQuorum <createIndex-method-commitQuorum>`
-parameter to the :method:`~db.collection.createIndex()` operation to set
-the minimum number of data-bearing voting members (i.e commit
-quorum), including the primary, which must complete the
-index build before the primary marks the indexes as ready. The default
-commit quorum is ``votingMembers``, or all data-bearing voting replica
-set members.
+.. |updateMethod-name| replace:: :method:`~db.collection.createIndex()`
+.. include:: /includes/indexes/template-commit-quorum-intro.rst
 
 The following operation creates an index with a :ref:`commit quorum
 <createIndex-method-commitQuorum>` of ``"majority"``, or a 

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

@@ -7,7 +7,7 @@ db.collection.createIndexes()
 .. contents:: On this page
    :local:
    :backlinks: none
-   :depth: 1
+   :depth: 2
    :class: singlecol
 
 Definition
@@ -1004,12 +1004,8 @@ Create Indexes With Commit Quorum
 
 .. include:: /includes/extracts/4.4-changes-index-builds-simultaneous.rst
 
-Specify the :ref:`commitQuorum <createIndexes-method-commitQuorum>`
-parameter to the :method:`~db.collection.createIndexes` operation to set
-the minimum number of data-bearing voting members (i.e commit
-quorum), including the primary, which must complete the index build
-before the primary marks the indexes as ready. The default commit quorum
-is ``votingMembers``, or all data-bearing voting replica set members.
+.. |updateMethod-name| replace:: :method:`~db.collection.createIndexes()`
+.. include:: /includes/indexes/template-commit-quorum-intro.rst
 
 The following operation creates an index with a :ref:`commit quorum
 <createIndexes-method-commitQuorum>` of ``"majority"``:

source/reference/write-concern.txt

@@ -488,3 +488,12 @@ The following table shows the possible write concern ``provenance``
 values and their significance:
 
 .. include:: /includes/fact-wc-provenance-table.rst
+
+
+.. _write-concern-contrasted-with-commit-quorum:
+
+Write Concern Contrasted with Commit Quorum
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: /includes/indexes/commit-quorum-vs-write-concern.rst
+