dropIndexes can stop in-progress builds and drop built indexes (#435)

* dropIndexes can stop in progress builds and built indexes

* refactor into includes with replacements

* fix up includes

* updates behavior include

* review feedback

Author: jmd-mongo

source/includes/fact-drop-index-5.2.rst

@@ -0,0 +1,5 @@
+Starting in MongoDB 5.2, you can use |drop-index| to drop existing 
+indexes on the same collection even if there is a build in progress on 
+another index. In earlier versions, attempting to drop a different 
+index during an in-progress index build results in a 
+``BackgroundOperationInProgressForNamespace`` error.    

source/includes/fact-stop-in-progress-index-builds.rst

@@ -0,0 +1,16 @@
+Starting in MongoDB 4.4, if an index specified to |drop-index| is still 
+building, |drop-index| attempts to stop the in-progress build. Stopping 
+an index build has the same effect as dropping the built index. In 
+versions earlier than MongoDB 4.4, |drop-index| returns an error if 
+there are any index builds in progress on the collection.
+
+For replica sets, run |drop-index| on the :term:`primary`. 
+The primary stops the index build and creates an associated 
+"abortIndexBuild" :term:`oplog` entry. Secondaries which replicate
+the "abortIndexBuild" oplog entry stop the in-progress index build and
+discard the build job. See :ref:`index-build-process` for detailed
+documentation on the index build process.
+
+Use :dbcommand:`currentOp` to identify the index builds associated with 
+a :dbcommand:`createIndexes` or :method:`db.collection.createIndexes()`
+operation. See :ref:`currentOp-cmd-index-creation` for an example.

source/reference/command/dropIndexes.txt

@@ -73,6 +73,10 @@ dropIndexes
 Behavior
 --------
 
+.. |drop-index| replace:: :dbcommand:`dropIndexes`
+
+.. include:: /includes/fact-drop-index-5.2.rst
+
 Kill related queries only
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -105,40 +109,12 @@ instead of the index specification document.
 
 .. _dropIndexes-cmd-index-builds:
 
-Abort In-Progress Index Builds
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. versionadded:: 4.4
-
-   If an index specified to :dbcommand:`dropIndexes` is still building,
-   :dbcommand:`dropIndexes` attempts to abort the in-progress build.
-   Aborting an index build has the same effect as dropping the built
-   index. Prior to MongoDB 4.4, :dbcommand:`dropIndexes` would return an
-   error if the collection had any in-progress index builds.
-
-For replica sets, run :dbcommand:`dropIndexes` on the :term:`primary`.
-The primary aborts the index build and creates an associated
-"abortIndexBuild" oplog entry. Secondaries which replicate the
-"abortIndexBuild" oplog entry abort the in-progress index build and
-discard the build job. See :ref:`index-build-process` for detailed
-documentation on the index build process and the specific timing for
-terminating an in-progress index build.
-
-The indexes specified to :dbcommand:`dropIndexes` must be the entire set
-of in-progress builds associated to a single :dbcommand:`createIndexes`
-or :method:`db.collection.createIndexes()` operation. To drop a specific
-index out of a set of related in-progress builds, wait until the index
-builds complete and specify that index to :dbcommand:`dropIndexes`.
-
-For example, a :dbcommand:`createIndexes` /
-:method:`~db.collection.createIndexes()` operation creates three
-indexes. Assuming all three index builds are in-progress,
-:dbcommand:`dropIndexes` must specify all three indexes to abort the
-index builds.
-
-Use :dbcommand:`currentOp` to identify the index builds associated to a
-:dbcommand:`createIndexes` / :method:`~db.collection.createIndexes()`
-operation. See :ref:`currentOp-cmd-index-creation` for an example.
+Stop In-Progress Index Builds
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. |drop-index| replace:: :dbcommand:`dropIndexes`
+
+.. include:: /includes/fact-stop-in-progress-index-builds.rst
 
 Hidden Indexes
 ~~~~~~~~~~~~~~

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

@@ -64,10 +64,10 @@ Definition
 
              If an index specified to
              :method:`db.collection.dropIndex()` is still building,
-             :method:`~db.collection.dropIndex()` attempts to abort the
-             in-progress build. Aborting an index build has the same
+             :method:`db.collection.dropIndex()` attempts to stop the
+             in-progress build. Stopping an index build has the same
              effect as dropping the built index. Prior to MongoDB 4.4,
-             :method:`~db.collection.dropIndex()` returned an error if
+             :method:`db.collection.dropIndex()` returned an error if
              the specified index was still building. See
              :ref:`dropIndex-method-index-builds` for more complete
              documentation.
@@ -79,7 +79,9 @@ Definition
 Behavior
 --------
 
-.. include:: /includes/extracts/fact-method-dropIndex-query-behavior.rst
+.. |drop-index| replace:: :method:`db.collection.dropIndex()`
+
+.. include:: /includes/fact-drop-index-5.2.rst
 
 Resource Locking
 ~~~~~~~~~~~~~~~~
@@ -90,43 +92,12 @@ Resource Locking
 
 .. _dropIndex-method-index-builds:
 
-Aborts In-Progress Index Builds
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. versionadded:: 4.4
-
-   If an index specified to :method:`db.collection.dropIndex()` is still
-   being built, :method:`~db.collection.dropIndex()` attempts to abort
-   the build. Aborting an index build has the same effect as dropping
-   the built index. Prior to MongoDB 4.4,
-   :method:`~db.collection.dropIndex()` returned an error if the
-   specified index was still building.
-
-The index specified to :method:`~db.collection.dropIndex()` must be the
-only index associated to the index builder, i.e. the indexes built by a
-single :dbcommand:`createIndexes` or
-:method:`db.collection.createIndexes()` operation. If the associated
-index builder has other in-progress builds, wait until the builds
-complete and specify the index to :method:`~db.collection.dropIndex()`.
-
-For example, a :dbcommand:`createIndexes` /
-:method:`~db.collection.createIndexes()` operation creates three
-indexes. Assuming all three index builds are still in-progress,
-:method:`~db.collection.dropIndex()` cannot successfully abort any of
-the index builds and therefore cannot drop any of those indexes.
-
-Use :dbcommand:`currentOp` to identify the index builds associated to a
-:dbcommand:`createIndexes` / :method:`~db.collection.createIndexes()`
-operation. See :ref:`currentOp-cmd-index-creation` for an example.
-
-For replica sets or shard replica sets, aborting an index on the primary
-does not simultaneously abort secondary index builds.
-:method:`~db.collection.dropIndex()` attempts to abort the in-progress
-builds for the specified indexes on the :term:`primary` and if
-successful creates an associated "abort" oplog entry. :term:`Secondary
-<secondary>` members with replicated in-progress builds wait for a
-commit or abort oplog entry from the primary before either committing or
-aborting the index build.
+Stop In-Progress Index Builds
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. |drop-index| replace:: :method:`db.collection.dropIndex()`
+
+.. include:: /includes/fact-stop-in-progress-index-builds.rst
 
 Hidden Indexes
 ~~~~~~~~~~~~~~
@@ -151,7 +122,7 @@ Example
 -------
 
 Consider a ``pets`` collection. Calling the
-:method:`~db.collection.getIndexes()` method on the ``pets`` collection
+:method:`db.collection.getIndexes()` method on the ``pets`` collection
 returns the following indexes:
 
 .. code-block:: javascript

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

@@ -109,10 +109,9 @@ Definition
 Behavior
 --------
 
-Cannot Drop ``Ready`` Indexes During In-Progress Index Builds
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. |drop-index| replace:: :method:`db.collection.dropIndexes()`
 
-.. include:: /includes/fact-5.0-dropindexes-inprog.rst
+.. include:: /includes/fact-drop-index-5.2.rst
 
 Kill related queries only
 ~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -146,42 +145,12 @@ instead of the index specification document.
 
 .. _dropIndexes-method-index-builds:
 
-Aborts In-Progress Index Builds
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. versionadded:: 4.4
-
-   If an index specified to :method:`db.collection.dropIndexes()` is
-   still building, :method:`~db.collection.dropIndexes()` attempts to
-   abort the in-progress build. Aborting an index build has the same
-   effect as dropping the built index. Prior to MongoDB 4.4,
-   :method:`~db.collection.dropIndexes()` would return an error if the
-   collection had any in-progress index builds.
-
-For replica sets, run :method:`~db.collection.dropIndexes()` on the
-:term:`primary`. The primary aborts the index build and creates an
-associated "abortIndexBuild" oplog entry. Secondaries which replicate
-the "abortIndexBuild" oplog entry abort the in-progress index build and
-discard the build job. See :ref:`index-build-process` for detailed
-documentation on the index build process and the specific timing for
-terminating an in-progress index build.
-
-The indexes specified to :method:`~db.collection.dropIndexes()` must be
-the entire set of in-progress builds associated to a single
-:dbcommand:`createIndexes` or :method:`db.collection.createIndexes()`
-operation. To drop a specific index out of a set of related in-progress
-builds, wait until the index builds complete and specify that index to
-:method:`~db.collection.dropIndexes()`
-
-For example, a :dbcommand:`createIndexes` /
-:method:`~db.collection.createIndexes()` operation creates three
-indexes. Assuming all three index builds are in-progress,
-:method:`~db.collection.dropIndexes()` must specify all three indexes to
-abort the index builds and drop the indexes.
-
-Use :dbcommand:`currentOp` to identify the index builds associated to a
-:dbcommand:`createIndexes` / :method:`~db.collection.createIndexes()`
-operation. See :ref:`currentOp-cmd-index-creation` for an example.
+Stop In-Progress Index Builds
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. |drop-index| replace:: :method:`db.collection.dropIndexes()`
+
+.. include:: /includes/fact-stop-in-progress-index-builds.rst
 
 Hidden Indexes
 ~~~~~~~~~~~~~~

source/release-notes/5.2-compatibility.txt

@@ -24,3 +24,14 @@ Removed :binary:`~bin.mongod` Options
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. include:: /includes/5.2/removed-mongod-options.rst
+
+
+Existing Indexes Can Be Dropped During an Index Build
+-----------------------------------------------------
+
+Starting in MongoDB 5.2, you can use :dbcommand:`dropIndexes` or 
+:method:`db.collection.dropIndexes()` to drop existing indexes on the 
+same collection even if there is an index build in progress. In earlier 
+versions, attempting to drop a different index during an in-progress 
+index build results in a ``BackgroundOperationInProgressForNamespace``
+error.