Navigation
This version of the documentation is archived and no longer supported.

Build Indexes on Replica Sets

On this page

For replica sets, secondaries will begin building indexes after the primary finishes building the index. In sharded clusters, the mongos will send 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.

Considerations

Important

To create unique indexes 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:

  • Ensure that your oplog is large enough to permit the indexing or re-indexing operation to complete without falling too far behind to catch up. See the 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.

Procedure

Note

If you need to build an index in a sharded cluster, repeat the following procedure for each replica set that provides each shard.

To create unique indexes using the following procedure, you must stop all writes to the collection during the index build. Otherwise, you may end up with inconsistent data across the replica set members. If you cannot stop all writes to the collection, do not use the following procedure to create unique indexes.

Stop One Secondary

Stop the mongod process on one secondary. Restart the mongod process, making the following configuration updates:

If you are using a configuration file, make the following configuration updates:

For example, for a shard/config server replica set member, the updated configuration file will include content like the following example:

net:
   port: 27218
#   port: 27018
#replication:
#   replSetName: shardA
#sharding:
#   clusterRole: shardsvr
setParameter:
   skipShardingConfigurationChecks: true

If using command-line options, make the following configuration updates:

For example, if your replica set member that is not part of a sharded cluster normally runs with on the default port of 27017 with the --replSet option you would use the following invocation:

mongod --port 27218
[1](1, 2) By running the mongod on a different port, you ensure that the other members of the replica set and all clients will not contact the member while you are building the index.

Build the Index

Create the new index using the createIndex() in the mongo shell, or comparable method in your driver. This operation will create the index on this mongod instance

For example, to create an ascending index on the username field of the records collection, use the following mongo shell operation:

db.records.createIndex( { username: 1 } )

Restart the Program mongod as a Replica Set Member

When the index build completes, restart the mongod instance as a member of the replica set using its normal configuration file or command-line arguments. That is, undo the configuration changes made when starting as a standalone. For shard or config server replica set members, be sure to remove the skipShardingConfigurationChecks parameter.

When the index build completes, start the mongod instance with the --replSet option on its usual port:

mongod --port 27017 --replSet rs0

Allow replication to catch up on this member.

Build Indexes on all Secondaries

For each secondary in the set, build an index according to the following steps:

  1. Stop One Secondary
  2. Build the Index
  3. Restart the Program mongod as a Replica Set Member

Build the Index on the Primary

When all the secondaries have the new index, step down the primary, restart it as a standalone using the procedure described above, and build the index on the former primary:

  1. Build the index in the background on the primary.

  2. Step down the primary using the rs.stepDown() method in the mongo shell to cause the current primary to become a secondary graceful and allow the set to elect another member as primary.

    Then repeat the index building procedure, listed below, to build the index on the primary:

    1. Stop One Secondary
    2. Build the Index
    3. Restart the Program mongod as a Replica Set Member

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.