DOCSP-7693 resumable index build

Author: mungitoperrito

source/core/index-creation.txt

@@ -195,15 +195,15 @@ For sharded clusters, the index build occurs only on shards
 containing data for the collection being indexed.
 
 .. warning::
- 
-  Avoid dropping any index on a collection while an index is being 
+
+  Avoid dropping any index on a collection while an index is being
   replicated on the secondaries.
-  
-  If you attempt to drop an index from a collection on a :term:`primary` 
-  node while the collection has a background index building on the 
-  :term:`secondary` nodes, the two indexing operations will conflict 
-  with each other. 
-  
+
+  If you attempt to drop an index from a collection on a :term:`primary`
+  node while the collection has a background index building on the
+  :term:`secondary` nodes, the two indexing operations will conflict
+  with each other.
+ 
   As a result, reads will be halted across all namespaces and
   replication will halt until the background index build completes. 
   When the build finishes the dropIndex action will execute, then 
@@ -247,16 +247,26 @@ Build Failure and Recovery
 Interrupted Index Builds on a Primary ``mongod``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-If the primary :binary:`~bin.mongod` shuts down during the index build,
-the build progress is lost. The :binary:`~bin.mongod` automatically
-recovers the index build and restarts it from the beginning.
+Starting in MongoDB 5.0, if the primary :binary:`~bin.mongod` shuts
+down cleanly during the index build and the 
+:ref:`commitQuorum <createIndexes-cmd-commitQuorum>` is set to the
+default ``votingMembers``, then the index build progress is saved to
+disk. The :binary:`~bin.mongod` automatically recovers the index build
+when it is restarted and continues from the saved checkpoint. In earler
+versions, if the index build was interrupted it had to be restarted
+from the beginning.
 
 Interrupted Index Builds on a Secondary ``mongod``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-If a secondary shuts down during the index build, the index build job is
-persisted. Restarting the :binary:`~bin.mongod` automatically recovers
-the index build and restarts it from the beginning.
+Starting in MongoDB 5.0, if a secondary :binary:`~bin.mongod` shuts
+down cleanly during the index build and the 
+:ref:`commitQuorum <createIndexes-cmd-commitQuorum>` is set to the
+default ``votingMembers``, then the index build progress is saved to
+disk. The :binary:`~bin.mongod` automatically recovers the index build
+when it is restarted and continues from the saved checkpoint. In earler
+versions, if the index build was interrupted it had to be restarted
+from the beginning.
 
 Prior to MongoDB 4.4, the startup process stalls behind any recovered
 index builds. The secondary could fall out of sync with the replica set
@@ -282,6 +292,12 @@ the index build.
 Rollbacks during Build Process
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+Starting in MongoDB 5.0, if a node is rolled back to a prior state
+during the index build, the index build progress is saved to disk. If
+there is still work to be done when the rollback concludes, the
+:binary:`~bin.mongod` automatically recovers the index build and
+continues from the saved checkpoint.
+
 Starting in version 4.4, MongoDB can pause an in-progress 
 index build to perform a :doc:`rollback </core/replica-set-rollbacks>`.
 
@@ -341,6 +357,20 @@ filter the current operations for index creation operations, see
 The :data:`~currentOp.msg` field includes a percentage-complete
 measurement of the current stage in the index build process. 
 
+Observe Stopped and Resumed Index Builds in the Logs
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+While an index is being built, progress is written to the 
+:doc:`MongoDB log</reference/log-messages>`. If an index build is
+stopped and resumed there will be log messages with fields like these:
+
+.. code-block:: sh
+   :copyable: false
+
+    "msg":"Index build: wrote resumable state to disk",
+   
+    "msg":"Found index from unfinished build",
+
 Terminate In Progress Index Builds
 ----------------------------------
 

source/reference/command/createIndexes.txt

@@ -97,6 +97,10 @@ Definition
           marks the ``indexes`` as ready. A "voting" member is any
           replica set member where :rsconf:`members[n].votes` is greater
           than ``0``.
+
+          Starting in MongoDB v5.0 it is possible to resume some
+          :ref:`interupted index builds<index-operations-build-failure>`
+          when the commit quorum is set to ``"votingMembers"``. 
 
           Supports the following values:
 

source/reference/command/setIndexCommitQuorum.txt

@@ -74,8 +74,12 @@ setIndexCommitQuorum
           must report a successful :ref:`index build
           <index-operations-replicated-build>` before the primary
           marks the ``indexes`` as ready. A "voting" member is any
-          replica set member where :rsconf:`members[n].votes` is greater
-          than ``0``.
+          replica set member where :rsconf:`members[n].votes` is
+          greater than ``0``.
+          
+          Starting in MongoDB v5.0 it is possible to resume some
+          :ref:`interupted index builds<index-operations-build-failure>`
+          when the commit quorum is set to ``"votingMembers"``. 
 
           Supports the following values:
 

source/release-notes/5.0.txt

@@ -106,9 +106,20 @@ Drivers
 Indexes
 -------
 
+New Error Messages
+~~~~~~~~~~~~~~~~~~
+
 The :method:`db.collection.createIndex()` and :method:`db.collection.createIndexes()`
 operations have new error messages when options are specified incorrectly.
 
+Interrupted Index Builds
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+If a node in a replica set is cleanly shutdown or rolls back during an
+index build, the index build progress is now
+:ref:`saved to disk<index-operations-build-failure>`. When the server
+restarts, index creation resumes from the saved position.
+
 .. _5.0-rel-notes-removed-commands:
 
 Removed Commands