DOCSP-1557: index builds and replica sets/sharded clusters

Author: kay-kim

source/core/index-creation.txt

@@ -2,9 +2,9 @@
 .. _index-creation-operations:
 .. _index-operations:
 
-======================
-Index Build Operations
-======================
+================================================
+Index Build Operations on a Populated Collection
+================================================
 
 .. default-domain:: mongodb
 
@@ -14,24 +14,32 @@ Index Build Operations
    :depth: 1
    :class: singlecol
 
-By default, creating an index blocks all other operations on a
-database. When building an index on a collection, the database that
-holds the collection is unavailable for read or write operations until
-the index build completes. Any operation that requires a read or write
-lock on all databases (e.g. :command:`listDatabases`) will wait for the
-foreground index build to complete.
+By default, creating an index on a populated collection blocks all
+other operations on a database. When building an index on a populated
+collection, the database that holds the collection is unavailable for
+read or write operations until the index build completes. Any operation
+that requires a read or write lock on all databases (e.g.
+:command:`listDatabases`) will wait for the foreground index build to
+complete.
 
 .. index:: index; background creation
 .. _index-creation-background:
 
 Background Construction
 -----------------------
 
-For potentially long running index building operations, consider the
-``background`` operation so that the MongoDB database remains available
-during the index building operation. For example, to create an index in
-the background of the ``zipcode`` field of the ``people`` collection,
-issue the following:
+.. note::
+
+   The following section refers to building indexes on a standalone.
+   For a replica set or a sharded cluster, use a rolling index build.
+   See :doc:`/tutorial/build-indexes-on-replica-sets` for details.
+
+For potentially long running index building operations on standalone
+deployments, consider the ``background`` option so that the MongoDB
+database remains available during the index building operation. 
+
+For example, to create an index in the background of the ``zipcode``
+field of the ``people`` collection, issue the following:
 
 .. code-block:: javascript
 
@@ -49,13 +57,6 @@ following:
 Behavior
 ~~~~~~~~
 
-As of MongoDB version 2.4, a :program:`mongod` instance can build more
-than one index in the background concurrently.
-
-.. versionchanged:: 2.4
-   Before 2.4, a :program:`mongod` instance could only build one
-   background index per database at a time.
-
 Background indexing operations run in the background so that other database
 operations can run while creating the index. However, the :program:`mongo`
 shell session or connection where you are creating
@@ -75,7 +76,6 @@ usable once the index build is complete.
    :dbcommand:`compact`. These operations will return an error during
    background index builds.
 
-
 Performance
 ~~~~~~~~~~~
 
@@ -84,18 +84,9 @@ slower than the normal "foreground" index builds. If the index is
 larger than the available RAM, then the incremental process can take
 *much* longer than the foreground build.
 
-If your application
-includes :method:`~db.collection.createIndex()`
-operations, and an index *doesn't* exist for other operational
-concerns, building the index can have a severe impact on the
-performance of the database.
-
-To avoid performance issues, make sure that your application checks
-for the indexes at start up using the
-:method:`~db.collection.getIndexes()` method or the :api:`equivalent
-method for your driver <>` and terminates if the proper indexes do not
-exist. Always build indexes in production instances using separate
-application code, during designated maintenance windows.
+Building an index can have a severe impact on the performance of the
+database. If possible, build indexes during designated maintenance
+windows.
 
 .. versionchanged:: 3.4
 
@@ -116,43 +107,35 @@ To start the :program:`mongod` after a failed index build, use the
 
 .. _index-creation-building-indexes-on-secondaries:
 
-Building Indexes on Secondaries
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Build Indexes on Replica Sets and Sharded Clusters
+--------------------------------------------------
 
-.. versionchanged:: 2.6
-   Secondary members can now build indexes in the
-   background. Previously all index builds on secondaries were in the
-   foreground.
+To minimize the impact of building an index on replica sets and sharded
+clusters with replica set shards, use a rolling index build procedure
+as described on :doc:`/tutorial/build-indexes-on-replica-sets`.
 
-A foreground index build on a :term:`primary` requires a global DB lock. It
-replicates as a foreground index build on :term:`replica set`
-:term:`secondaries <secondary>`, and the replication worker takes a global DB
-lock that queues reads and writes to all databases on the indexing server.
+If not using the rolling index build procedure:
 
-A background index build on a primary replicates as background index builds on
-secondaries. The replication worker does not take a global DB lock, and
-secondary reads are not affected.
+- A foreground index build on a :term:`primary` requires a DB
+  lock. It replicates as a foreground index build on :term:`replica
+  set` :term:`secondaries <secondary>`, and the replication worker
+  takes a global DB lock that queues reads and writes to all databases
+  on the indexing server.
 
-In both cases, index operations on replica set secondaries begin after the
-primary finishes building the index.
+- A background index build on a primary replicates as background index
+  builds on secondaries. The replication worker does not take a global
+  DB lock, and secondary reads are not affected.
 
-To build large indexes on secondaries the best approach is to
-restart one secondary at a time in :term:`standalone` mode and build
-the index. After building the index, restart as a member of the
-replica set, allow it to catch up with the other members of the set,
-and then build the index on the next secondary. When all the
-secondaries have the new index, step down the primary, restart it as a
-standalone, and build the index on the former primary.
+- For both foreground and background index builds on the primary, the
+  index operations on replica set secondaries begin after the primary
+  finishes building the index.
 
 The amount of time required to build the index on a secondary must be
 within the window of the :term:`oplog`, so that the secondary can
 catch up with the primary.
 
-Indexes on secondary members in "recovering" mode are always built in
-the foreground to allow them to catch up as soon as possible.
-
 See :ref:`index-building-replica-sets` for a complete procedure for
-building indexes on secondaries.
+building indexes on replica sets and sharded clusters.
 
 .. index:: index; name
 .. _index-names:
@@ -206,15 +189,11 @@ method in the :program:`mongo` shell. For index builds, the effects of
 :method:`db.killOp()` may not be immediate and may occur well after
 much of the index build operation has completed.
 
-You cannot terminate a *replicated* index build on secondary members
-of a replica set. To minimize the impact of building an index on
-replica sets, see :doc:`/tutorial/build-indexes-on-replica-sets`.
-
-.. versionchanged:: 2.4
+You cannot terminate a *replicated* index build on secondary members of
+a replica set. To minimize the impact of building an index on replica
+sets and sharded clusters with replica set shards, see
+:doc:`/tutorial/build-indexes-on-replica-sets`.
 
-   Before MongoDB 2.4, you could *only* terminate *background* index
-   builds. After 2.4, you can terminate both *background* index builds
-   and foreground index builds.
 
 .. seealso::
    :method:`db.currentOp()`, :method:`db.killOp()`

source/includes/fact-index-build-memory-limit.rst

@@ -10,4 +10,11 @@ only one collection at a time and has no risk of exceeding the memory
 limit. However, it is possible for a user to start foreground index
 builds on multiple collections in multiple databases simultaneously
 and potentially consume an amount of memory greater than the limit
-set in :parameter:`maxIndexBuildMemoryUsageMegabytes`.
+set in :parameter:`maxIndexBuildMemoryUsageMegabytes`.
+
+.. tip::
+
+   To minimize the impact of building an index on replica sets and
+   sharded clusters with replica set shards, use a rolling index build
+   procedure as described on
+   :doc:`/tutorial/build-indexes-on-replica-sets`.

source/reference/command/createIndexes.txt

@@ -63,17 +63,27 @@ Definition
 Considerations
 --------------
 
+Index Names
+~~~~~~~~~~~
+
 An index name, including the :term:`namespace`, cannot be longer than
 the :ref:`Index Name Length <limit-index-name-length>` limit.
 
+Replica Sets and Sharded Clusters
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To minimize the impact of building an index on replica sets and sharded
+clusters, use a rolling index build procedure
+as described on :doc:`/tutorial/build-indexes-on-replica-sets`.
+
 Behavior
 --------
 
 Concurrency
 ~~~~~~~~~~~
 
-Non-background indexing operations block all other operations on a
-database.
+Foreground indexing operations on a populated collection block all
+other operations on a database.
 
 Multiple Index Builds
 ~~~~~~~~~~~~~~~~~~~~~

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

@@ -19,12 +19,16 @@ Definition
 
    .. versionchanged:: 3.2
 
-      Starting in MongoDB 3.2, MongoDB disallows the creation of
-      :ref:`version 0 <3.2-version-0-indexes>` indexes. To upgrade
-      existing version 0 indexes, see :ref:`3.2-version-0-indexes`.
+      MongoDB disallows the creation of :ref:`version 0
+      <3.2-version-0-indexes>` indexes. To upgrade existing version 0
+      indexes, see :ref:`3.2-version-0-indexes`.
 
    .. include:: /includes/apiargs/method-db.collection.createIndex-param.rst
 
+   To minimize the impact of building an index on replica sets and
+   sharded clusters, use a rolling index build procedure as described
+   on :doc:`/tutorial/build-indexes-on-replica-sets`.
+
 .. _ensureIndex-options:
 .. _createIndex-options:
 
@@ -119,6 +123,7 @@ described here.
 
    Foreground index builds block all other operations on the database.
 
+
 .. include:: /includes/extracts/createIndex-behavior.rst
 
 - .. include:: /includes/fact-index-key-length-operation-behaviors.rst

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

@@ -21,6 +21,10 @@ Definition
 
    .. include:: /includes/apiargs/method-db.collection.createIndexes-param.rst
 
+   To minimize the impact of building an index on replica sets and sharded
+   clusters, use a rolling index build procedure
+   as described on :doc:`/tutorial/build-indexes-on-replica-sets`.
+
 .. _createIndexes-options:
 
 Options

source/tutorial/build-indexes-on-replica-sets.txt

@@ -15,45 +15,43 @@ Build Indexes on Replica Sets
    :depth: 1
    :class: singlecol
 
-For replica sets, secondaries will begin building indexes *after* the
-:term:`primary` finishes building the index. In :term:`sharded clusters
-<sharded cluster>`, the :program:`mongos` will send :method:`createIndex()
-<db.collection.createIndex()>` to the primary members of the replica
-set for each shard, which then replicate to the secondaries after the
-primary finishes building the index.
-
-To minimize the impact of building an index on your replica set, you
-can use the following procedure to build indexes.
+To minimize the impact of building an index on replica sets and sharded
+clusters with replica set shards, use the following procedure to build
+indexes in a rolling fashion.
 
+This procedure *does* take one member out of the replica set at a time.
+However, this procedure will only affect one member of the set at a
+time rather than *all* secondaries at the same time.
 
 Considerations
 --------------
 
-.. important::
+Unique Indexes
+~~~~~~~~~~~~~~
 
-   To create :ref:`unique indexes <index-type-unique>` using the
-   following procedure, you must stop all writes to the collection
-   during this procedure.
+To create :ref:`unique indexes <index-type-unique>` using the following
+procedure, you must stop all writes to the collection during this
+procedure.
 
-   If you cannot stop all writes to the collection during this
-   procedure, do not use the procedure on this page. Instead, build
-   your unique index on the collection by:
+If you cannot stop all writes to the collection during this procedure,
+do not use the procedure on this page. Instead, build your unique index
+on the collection by:
 
-   - issuing :method:`db.collection.createIndex()` on the primary for a
-     replica set, or
+- issuing :method:`db.collection.createIndex()` on the primary for a
+  replica set, or
 
-   - issuing :method:`db.collection.createIndex()` on the
-     :program:`mongos` for a sharded cluster.
+- issuing :method:`db.collection.createIndex()` on the
+  :program:`mongos` for a sharded cluster.
 
-- Ensure that your :term:`oplog` is large enough to permit the
-  indexing or re-indexing operation to complete without falling
-  too far behind to catch up. See the :ref:`oplog sizing
-  <replica-set-oplog-sizing>` documentation for additional
-  information.
 
-- This procedure *does* take one member out of the replica set at a
-  time. However, this procedure will only affect one member of the
-  set at a time rather than *all* secondaries at the same time.
+Oplog Size
+~~~~~~~~~~
+
+Ensure that your :term:`oplog` is large enough to permit the indexing
+or re-indexing operation to complete without falling too far behind to
+catch up. See the :ref:`oplog sizing <replica-set-oplog-sizing>`
+documentation for additional information.
+
 
 Procedure
 ---------
@@ -129,41 +127,31 @@ Modify the port number (e.g. ``27017``) or the replica set name
 
 Allow replication to catch up on this member.
 
-Build Indexes on all Secondaries
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Repeat the Procedure for the Remaining Secondaries
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-For each secondary in the set, build an index according to the
-following steps:
+Once the member catches up with the other members of the set, repeat
+the procedure one member at a time for the remaining secondary members:
 
 #. :ref:`tutorial-index-on-replica-sets-stop-one-member`
+
 #. :ref:`tutorial-index-on-replica-sets-build-index`
+
 #. :ref:`tutorial-index-on-replica-sets-restart-mongod`
 
 Build the Index on the Primary
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-To build an index on the primary you can either:
-
-#. :ref:`Build the index in the background
-   <index-creation-background>` on the primary.
-
-#. Step down the primary using the :method:`rs.stepDown()` method in
-   the :program:`mongo` shell to cause the current primary to become a
-   secondary graceful and allow the set to elect another member as
-   primary.
+When all the secondaries have the new index, step down the primary,
+restart it as a standalone, and build the index on the former primary:
 
-   Then repeat the index building procedure, listed below, to build the
-   index on the primary:
+#. Use the :method:`rs.stepDown()` method in the :program:`mongo` shell
+   to step down the primary. Upon successful stepdown, the current primary
+   becomes a secondary and the replica set members elect a new primary.
 
-   #. :ref:`tutorial-index-on-replica-sets-stop-one-member`
+#. :ref:`tutorial-index-on-replica-sets-stop-one-member`
 
-   #. :ref:`tutorial-index-on-replica-sets-build-index`
+#. :ref:`tutorial-index-on-replica-sets-build-index`
 
-   #. :ref:`tutorial-index-on-replica-sets-restart-mongod`
+#. :ref:`tutorial-index-on-replica-sets-restart-mongod`
 
-Building the index on the background, takes longer than the foreground
-index build and results in a less compact index structure. Additionally,
-the background index build may impact write performance on the
-primary. However, building the index in the background allows the set to
-be continuously up for write operations while MongoDB builds the
-index.