Indexes >
Index Build Operations

Index Build Operations¶

On this page

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. listDatabases) will wait for the foreground index build to complete.

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:

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

By default, background is false for building MongoDB indexes.

You can combine the background option with other options, as in the following:

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

Behavior¶

As of MongoDB version 2.4, a mongod instance can build more than one index in the background concurrently.

Changed in version 2.4: Before 2.4, a 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 mongo shell session or connection where you are creating the index will block until the index build is complete. To continue issuing commands to the database, open another connection or mongo instance.

Queries will not use partially-built indexes: the index will only be usable once the index build is complete.

Note

If MongoDB is building an index in the background, you cannot perform other administrative operations involving that collection, including running repairDatabase, dropping the collection (i.e. db.collection.drop()), and running compact. These operations will return an error during background index builds.

Performance¶

The background index operation uses an incremental approach that is 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 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 getIndexes() method or the 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.

Changed in version 3.4: You can build one or more indexes on a collection with the database command createIndexes. The default limit on memory usage for a createIndexes operation is 500 megabytes. You can override this limit by setting the maxIndexBuildMemoryUsageMegabytes server parameter.

createIndexes uses a combination of memory and temporary files on disk to complete index builds. Once the memory limit is reached, createIndexes uses temporary disk files in a subdirectory named _tmp within the --dbpath directory for additional scratch space. The higher the memory limit is set, the faster the index build can complete, but be careful not to set this limit too high relative to available RAM or your system can run out of free memory.

Interrupted Index Builds¶

If a background index build is in progress when the mongod process terminates, when the instance restarts the index build will restart as foreground index build. If the index build encounters any errors, such as a duplicate key error, the mongod will exit with an error.

To start the mongod after a failed index build, use the storage.indexBuildRetry or --noIndexBuildRetry to skip the index build on start up.

Building Indexes on Secondaries¶

Changed in version 2.6: Secondary members can now build indexes in the background. Previously all index builds on secondaries were in the foreground.

A foreground index build on a primary replicates as a foreground index build on replica set secondaries. The replication worker acquires a global DB lock that queues reads and writes to all databases on the indexing server.

A background index build on a primary replicates as a background index build on secondaries. Secondary reads are not affected.

In both cases, index operations on replica set secondaries begin after the primary finishes building the index.

To build large indexes on secondaries the best approach is to restart one secondary at a time in 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.

The amount of time required to build the index on a secondary must be within the window of the 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 Build Indexes on Replica Sets for a complete procedure for building indexes on secondaries.

Index Names¶

The default name for an index is the concatenation of the indexed keys and each key’s direction in the index, 1 or -1.

Example

Issue the following command to create an index on item and quantity:

db.products.createIndex( { item: 1, quantity: -1 } )

The resulting index is named: item_1_quantity_-1.

Optionally, you can specify a name for an index instead of using the default name.

Example

Issue the following command to create an index on item and quantity and specify inventory as the index name:

db.products.createIndex( { item: 1, quantity: -1 } , { name: "inventory" } )

The resulting index has the name inventory.

To view the name of an index, use the getIndexes() method.

View Index Build Operations¶

To see the status of an index build operation, you can use the db.currentOp() method in the mongo shell. To filter the current operations for index creation operations, see Active Indexing Operations for an example.

The msg field will include the percent of the build that is complete.

Terminate Index Build Operation¶

To terminate an ongoing index build, use the db.killOp() method in the mongo shell. For index builds, the effects of 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 Build Indexes on Replica Sets.

Changed in version 2.4: 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.