This version of the documentation is archived and no longer supported.




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

db.adminCommand( { moveChunk : <namespace> ,
                 find : <query> ,
                 to : <string>,
                 _secondaryThrottle : <boolean>,
                 writeConcern: <document>,
                 _waitForDelete : <boolean> } )


db.adminCommand( { moveChunk : <namespace> ,
                 bounds : <array> ,
                 to : <string>,
                 _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.
to string The name of the destination shard for the chunk.
_secondaryThrottle boolean

Optional. Starting in MongoDB 3.4, for WiredTiger, defaults to false. For MMAPv1, the default value remains true.

  • If true, then by default, 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.

writeConcern document

Optional. A document that expresses the write concern that the _secondaryThrottle will use to wait for secondaries during the chunk migration.

writeConcern requires _secondaryThrottle: true.

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

The value of bounds takes the form:

[ { hashedField : <minValue> } ,
  { hashedField : <maxValue> } ]

The chunk migration section describes how chunks move between shards on MongoDB.


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.



Changed in version 3.0.0: In previous versions, moveChunk would build indexes as part of the migrations.

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.

Meta Data Error

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.

←   medianKey movePrimary  →