moveRange

On this page

Definition

Compatibility
Syntax
Command Fields
Considerations
Examples

Definition

moveRange: New in version 6.0.
Moves ranges between shards. Run the moveRange command with a mongos instance while using the admin database.

Compatibility

This command is available in deployments hosted in the following environments:

MongoDB Atlas: The fully managed service for MongoDB deployments in the cloud

Note

This command is supported in all MongoDB Atlas clusters. For information on Atlas support for all commands, see Unsupported Commands.

MongoDB Enterprise: The subscription-based, self-managed version of MongoDB
MongoDB Community: The source-available, free-to-use, and self-managed version of MongoDB

Syntax

The command has the following syntax:

db.adminCommand(
  {
    moveRange: <namespace>,
    toShard: <ID of the recipient shard>,
    min: <min key of the range to move>, // conditional
    max: <max key of the range to move>, // conditional
    forceJumbo: <bool>, // optional
    waitForDelete: <bool>, // optional
    writeConcern: <write concern>, // optional
    secondaryThrottle: <bool> // optional
  }
)

Command Fields

The command takes the following fields:

Field	Type	Description
`toShard`	string	ID of the recipient shard.
`min`	key	Minimum key of the range to move. Required if you don't specify `max`. If you do not specify `min`, given a chunk `C` where `max` is either the exclusive upper bound of `C` or `C` includes the shard key `max`, `min` is determined in the following way: If the data size of the range between `min(C)` and `max` is less than the per-collection chunk size or the default chunk size, the chunk's `min` value is selected as `min` = `min(C)`. Otherwise, key `min` > `min(C)` where `min` depends on the configured chunk size.
`max`	key	Maximum key of the range to move. Required if you don't specify `min`. If you do not specify `max`, given a chunk `C` including the shard key `min`, `max` is determined in the following way: If the data size of the range between `min` and `max(C)` is less than the per-collection chunk size or the default chunk size, the chunk's max is selected as `max` = `max(C)`. Otherwise, key `max` < `max(C)` where `max` depends on the configured chunk size.
forceJumbo	boolean	Optional. Flag that determines if the command can move a range that is too large to migrate. The range may or may not be labeled as jumbo. If `true`, the command can move the range. If `false`, the command cannot move the range. The default is `false`. WARNING: The `moveRange` command with `forceJumbo=true` blocks read and write operations on the collection. This option causes the shard to migrate chunks even when they are larger than the configured chunk size. The collection remains unavailable for the duration of the migration. To migrate these large chunks without this long blocking period, see Balance Ranges that Exceed Size Limit instead.
`writeConcern`	document	Optional. Document with the write concern. The default is `w: majority`.
`secondaryThrottle`	boolean	Optional. If `true`, each document move during chunk migration propagates to at least one secondary before the balancer proceeds with the next document. This is equivalent to a write concern of `{ w: 2 }`. Use the `writeConcern` option to specify a different write concern. If `false`, the balancer does not wait for replication to a secondary and instead continues with the next document. For more information, see Secondary Throttle.

The range migration section describes how ranges move between shards on MongoDB.

Considerations

Only use the moveRange in scenarios like:

an initial ingestion of data
a large bulk import operation

Allow the balancer to create and balance ranges in sharded clusters in most cases.

Tip

Examples

The following examples use a collection with:

Shard key x
Configured chunk size of 128MB
A chunk with boundaries: [x: 0, x: 100)

Specify both `min` and `max`

The following table lists the results of setting min and max to various values:

`min`	`max`	Result
`0`	`100`	Moves all the documents in the range to the recipient shard.
`10`	`30`	Creates three sub-ranges: `[x: 0, x: 10)` `[x: 10, x: 30)` `[x: 30, x: 100)` Moves all the documents in `[x: 10, x: 30)` to the recipient shard.
`0`	`20`	Creates two sub-ranges: `[x: 0, x: 20)` `[x: 20, x: 100)` Moves all the documents in `[x: 0, x: 20)` to the recipient shard.
`40`	`100`	Creates two sub-ranges: `[x: 0, x: 40)` `[x: 40, x: 100)` Moves all the documents in `[x: 40, x: 100)` to the recipient shard.

Specify `min` but not `max`

The following table lists the results of setting min to various values:

`min`	Amount of Data in Key Range	Result
`0`	Less than 128 MB contained between keys `x: 0` and `x: 100`.	Moves all the documents in the range to the recipient shard.
`10`	Less than 128 MB contained between keys `x: 0` and `x: 100`.	Creates two sub-ranges: `[x: 0, x: 10)` `[x : 10, x: 100)` Moves all documents in `[x: 10, x: 100)` to the recipient shard.
`10`	128 MB contained between keys `x: 10` and `x: 30`.	Creates three sub-ranges: `[x: 0, x: 10)` `[x: 10, x: 30)` `[x: 30, x: 100)` Moves all documents in `[x: 10, x: 30)` to the recipient shard.

Specify `max` but not `min`

The following table lists the results of setting max to various values:

`max`	Amount of Data in Key Range	Result
`100`	Less than 128 MB contained between keys `x: 0` and `x: 100`.	Moves all the documents in the range to the recipient shard.
`10`	Less than 128 MB contained between keys `x: 0` and `x: 100`.	Creates two sub-ranges: `[x: 0, x: 10)` `[x : 10, x: 100)` Moves all documents in `[x: 0, x: 10)` to the recipient shard.
`30`	128 MB contained between keys `x: 10` and `x: 30`.	Creates three sub-ranges: `[x: 0, x: 10)` `[x: 10, x: 30)` `[x: 30, x: 100)` Moves all documents in `[x: 10, x: 30)` to the recipient shard.

Back

movePrimary

mergeChunks