Migrate Chunks in a Sharded Cluster

This version of the documentation is archived and no longer supported. View the current documentation to learn how to upgrade your version of MongoDB.

In most circumstances, you should let the automatic balancer migrate chunks between shards. However, you may want to migrate chunks manually in a few cases:

When pre-splitting an empty collection, migrate chunks manually to distribute them evenly across the shards. Use pre-splitting in limited situations to support bulk data ingestion.
If the balancer in an active cluster cannot distribute chunks within the balancing window, then you will have to migrate chunks manually.

To manually migrate chunks, use the moveChunk command. For more information on how the automatic balancer moves chunks between shards, see Cluster Balancer and Chunk Migration.

Example

Migrate a single chunk

The following example assumes that the field username is the shard key for a collection named users in the myapp database, and that the value smith exists within the chunk to migrate. Migrate the chunk using the following command in the mongo shell.

db.adminCommand( { moveChunk : "myapp.users",
                   find : {username : "smith"},
                   to : "mongodb-shard3.example.net" } )

This command moves the chunk that includes the shard key value "smith" to the shard named mongodb-shard3.example.net. The command will block until the migration is complete.

Tip

To return a list of shards, use the listShards command.

Example

Evenly migrate chunks

To evenly migrate chunks for the myapp.users collection, put each prefix chunk on the next shard from the other and run the following commands in the mongo shell:

var shServer = [ "sh0.example.net", "sh1.example.net", "sh2.example.net", "sh3.example.net", "sh4.example.net" ];
for ( var x=97; x<97+26; x++ ){
  for( var y=97; y<97+26; y+=6 ) {
    var prefix = String.fromCharCode(x) + String.fromCharCode(y);
    db.adminCommand({moveChunk : "myapp.users", find : {email : prefix}, to : shServer[(y-97)/6]})
  }
}

See Create Chunks in a Sharded Cluster for an introduction to pre-splitting.

The moveChunk command has the: _secondaryThrottle parameter and the writeConcern parameter that determines when the balancer proceeds with the next document in the migrating chunk. See moveChunk command for details.

Warning

The moveChunk command may produce the following error message:

The collection's metadata lock is already taken.

This occurs when clients have too many open cursors that access the migrating chunk. You may either wait until the cursors complete their operations or close the cursors manually.

Back

Manage Sharded Cluster Balancer

Administration