Skip to content

DOCS-1708: Documentation isn't clear on what a 'blocking index build' is #1185

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 13 additions & 8 deletions source/core/indexes.txt
Original file line number Diff line number Diff line change
Expand Up @@ -633,20 +633,25 @@ affect how MongoDB builds the indexes.
Background Construction
~~~~~~~~~~~~~~~~~~~~~~~

By default, creating an index is a blocking operation. Building an
index on a large collection of data can take a long
time to complete. To resolve this issue, the background option can
allow you to continue to use your :program:`mongod` instance during
the index build.

For example, to create an index in the background of the ``zipcode``
field of the ``people`` collection you would issue the following:
By default, creating an index is a blocking operation. When building
an index, the databases that hold those collections are not available
for any read or write operations until the index is totally built.
Any operation requiring a read or write lock on all databases (e.g.
:command:`listDatabases`) will wait for the index to complete building.

For potentially long running index building operations you can use the
``background`` operation so that your MongoDB instance remains available
during the index building operation. For example, to create an index in
the background of the ``zipcode`` field of the ``people`` collection you
would issue the following:

.. code-block:: javascript

db.people.ensureIndex( { zipcode: 1}, {background: true} )

By default, ``background`` is ``false`` for building MongoDB indexes.
Setting ``background`` to ``true`` makes the index creation a
non-blocking operation.

You can combine the background option with other options, as in the
following:
Expand Down
17 changes: 12 additions & 5 deletions source/tutorial/build-indexes-in-the-background.txt
Original file line number Diff line number Diff line change
Expand Up @@ -8,11 +8,18 @@ Build Indexes in the Background
.. default-domain:: mongodb

By default, MongoDB builds indexes in the foreground, which means that
these indexes block all other read and write operations to the
database while the index builds. :ref:`Background index construction
<index-creation-background>` allows read and write operations to
continue while building the index; however, these index builds take
longer to complete and result in a larger index.
these no read and write operations to the database can occur while the
index builds. Also, no operations that need a read or write lock on all
databases (e.g. :command:`listDatabases`) can occur during this time as
well.

:ref:`Background index construction <index-creation-background>` allows
read and write operations to continue while building the index.

.. note::

These index builds take longer to complete and result in a larger
index.

After the index finishes building, MongoDB treats indexes built in the
background the same as any other index.
Expand Down