Docs Menu

Docs HomeMongoDB Manual

Migrate Chunks in a Sharded Cluster

On this page

  • Change Streams and Orphan Documents

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 moveRange or moveChunk command. For more information on how the automatic balancer moves chunks between shards, see Cluster Balancer and Chunk Migration.


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 mongosh.

db.adminCommand( { moveChunk : "myapp.users",
find : {username : "smith"},
to : "" } )

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


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


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 = [ "", "", "", "", "" ];
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.

  • Use the moveChunk command with the _secondaryThrottle and writeConcern fields to determine when the balancer proceeds with the next document in the migrating chunk.

  • Use the moveRange command with the secondaryThrottle and writeConcern fields to determine when the balancer proceeds with the next document in the migrating chunk.

See moveRange and moveChunk for details.

Starting in MongoDB 5.3, during chunk migration, change stream events are not generated for updates to orphaned documents.

←  Manage Sharded Cluster BalancerSharded Cluster Administration →
Share Feedback
© 2022 MongoDB, Inc.


  • Careers
  • Investor Relations
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2022 MongoDB, Inc.