> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

# Migrate Ranges in a Sharded Cluster

In most circumstances, you should let the automatic [balancer](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-balancer) migrate [ranges](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-range) between [shards](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-shard). However, you may want to migrate ranges manually in a few cases:

- When [pre-splitting](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-pre-splitting) an empty collection, migrate ranges 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 ranges within the [balancing window](https://www.mongodb.com/docs/manual/tutorial/manage-sharded-cluster-balancer.md#std-label-sharding-schedule-balancing-window), then you will have to migrate ranges manually.

To manually migrate ranges, use the [`moveChunk`](https://www.mongodb.com/docs/manual/reference/command/moveChunk.md#mongodb-dbcommand-dbcmd.moveChunk) or [`moveRange`](https://www.mongodb.com/docs/manual/reference/command/moveRange.md#mongodb-dbcommand-dbcmd.moveRange) command.

For more information on how the automatic balancer moves ranges between shards, see [Balancer Internals](https://www.mongodb.com/docs/manual/core/sharding-balancer-administration.md#std-label-sharding-balancing-internals) and [Range Migration.](https://www.mongodb.com/docs/manual/core/sharding-data-partitioning.md#std-label-sharding-range-migration)

**Example: Migrate a single range**

The following example assumes that the field `username` is the [shard key](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-shard-key) for a collection named `users` in the `myapp` database, and that the value `smith` exists within the [range](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-range) to migrate. Migrate the range using the following command in [`mongosh`.](https://www.mongodb.com/docs/mongodb-shell.md#mongodb-binary-bin.mongosh)

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

This command moves the range that includes the shard key value "smith" to the [shard](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-shard) named `mongodb-shard3.example.net`. The command will block until the migration is complete.

To return a list of shards, use the [`listShards`](https://www.mongodb.com/docs/manual/reference/command/listShards.md#mongodb-dbcommand-dbcmd.listShards) command.

**Example: Evenly migrate ranges**

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

```javascript
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 Ranges in a Sharded Cluster](https://www.mongodb.com/docs/manual/tutorial/create-chunks-in-sharded-cluster.md#std-label-create-ranges-in-a-sharded-cluster) for an introduction to pre-splitting.

- Use the [`moveChunk`](https://www.mongodb.com/docs/manual/reference/command/moveChunk.md#mongodb-dbcommand-dbcmd.moveChunk) command with the `_secondaryThrottle` and `writeConcern` fields to determine when the balancer proceeds with the next document in the migrating range.

- Use the [`moveRange`](https://www.mongodb.com/docs/manual/reference/command/moveRange.md#mongodb-dbcommand-dbcmd.moveRange) command with the `secondaryThrottle` and `writeConcern` fields to determine when the balancer proceeds with the next document in the migrating range.

See [`moveChunk`](https://www.mongodb.com/docs/manual/reference/command/moveChunk.md#mongodb-dbcommand-dbcmd.moveChunk) and [`moveRange`](https://www.mongodb.com/docs/manual/reference/command/moveRange.md#mongodb-dbcommand-dbcmd.moveRange) for details.

## Change Streams and Orphan Documents

Starting in MongoDB 5.3, during [range migration](https://www.mongodb.com/docs/manual/core/sharding-balancer-administration.md#std-label-range-migration-procedure), [change stream](https://www.mongodb.com/docs/manual/changeStreams.md#std-label-changeStreams) events are not generated for updates to [orphaned documents.](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-orphaned-document)