Docs Menu

Docs HomeDevelop ApplicationsMongoDB Manual

moveChunk

On this page

  • Definition
  • Considerations
  • Behavior
moveChunk

Internal administrative command. Moves chunks between shards. Issue the moveChunk command via a mongos instance while using the admin database. Use the following forms:

Tip

In mongosh, this command can also be run through the sh.moveChunk() helper method.

Helper methods are convenient for mongosh users, but they may not return the same level of information as database commands. In cases where the convenience is not needed or the additional return fields are required, use the database command.

db.adminCommand(
{
moveChunk: <namespace>,
find: <query>,
to: <string>,
forceJumbo: <boolean>, // Starting in MongoDB 4.4
_secondaryThrottle: <boolean>,
writeConcern: <document>,
_waitForDelete: <boolean>
}
)

Alternatively:

db.adminCommand(
{
moveChunk: <namespace>,
bounds: <array>,
to: <string>,
forceJumbo: <boolean>, // Starting in MongoDB 4.4
_secondaryThrottle: <boolean>,
writeConcern: <document>,
_waitForDelete: <boolean>
}
)

The moveChunk command has the following fields:

Field
Type
Description
moveChunk
string
The namespace of the collection where the chunk exists. Specify the collection's full namespace, including the database name.
find
document
An equality match on the shard key that specifies the shard-key value of the chunk to move. Specify either the bounds field or the find field but not both. Do not use the find field to select chunks in collections that use a hashed shard key.
bounds
array

The bounds of a specific chunk to move. The array must consist of two documents that specify the lower and upper shard key values of a chunk to move. Specify either the bounds field or the find field but not both. Use bounds to select chunks in collections that use a hashed shard key.

The value of bounds takes the following form:

[ { hashedField : <minValue> } ,
{ hashedField : <maxValue> } ]
to
string
The name of the destination shard for the chunk.
forceJumbo
boolean

Optional. A flag that determines if the command can move a chunk that is too large to migrate. The chunk may or may not be labeled as jumbo.

  • If true, the command can move the chunk.

  • If false, the command cannot move the chunk.

The default is false.

Warning

When you run moveChunk with forceJumbo: true, write operations to the collection may block for a long period of time during the migration. To migrate these large chunks without this long blocking period, see Balance Chunks that Exceed Size Limit instead.

New in version 4.4.

_secondaryThrottle
boolean

Optional. Default is false.

  • If true, then each document moved during chunk migration propagates to secondary members according to the write concern specified in the writeConcern field before the balancer proceeds with the next document.

    If _secondaryThrottle is true, you must also specify the writeConcern field.

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

writeConcern
document

Required if _secondaryThrottle is true.

A document containing the write concern that the _secondaryThrottle uses to wait for secondaries during the chunk migration.

If _secondaryThrottle is false, the writeConcern field is ignored.

_waitForDelete
boolean
Optional. Internal option for testing purposes. The default is false. If set to true, the delete phase of a moveChunk operation blocks.

To learn how chunks move between shards, see Chunk Migration.

Tip

See also:

Only use the moveChunk in special circumstances such as preparing your sharded cluster for an initial ingestion of data, or a large bulk import operation. In most cases allow the balancer to create and balance chunks in sharded clusters. See Create Chunks in a Sharded Cluster for more information.

moveChunk requires that all indexes exist on the target (i.e. to ) shard before migration and returns an error if a required index does not exist.

moveChunk returns the following error message if another metadata operation is in progress on the chunks collection:

errmsg: "The collection's metadata lock is already taken."

If another process, such as a balancer process, changes meta data while moveChunk is running, you may see this error. You may retry the moveChunk operation without side effects.

Starting in MongoDB 5.0 (and 4.4.7, 4.2.15, 4.0.26), you can set the maxCatchUpPercentageBeforeBlockingWrites to specify the maximum allowed percentage of data not yet migrated during a moveChunk operation when compared to the total size (in MBs) of the chunk being transferred.

←  listShardsmovePrimary →