Docs Home → Develop Applications → MongoDB Manual
moveChunk![](/docs/v5.2/assets/link.svg)
On this page
Definition![](/docs/v5.2/assets/link.svg)
moveChunk
Internal administrative command. Moves chunks between shards. Issue the
moveChunk
command via amongos
instance while using the admin database. Use the following forms: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:FieldTypeDescriptionmoveChunk
stringThe namespace of the collection where the chunk exists. Specify the collection's full namespace, including the database name.find
documentAn equality match on the shard key that specifies the shard-key value of the chunk to move. Specify either thebounds
field or thefind
field but not both. Do not use thefind
field to select chunks in collections that use a hashed shard key.bounds
arrayThe 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 thebounds
field or thefind
field but not both. Usebounds
to select chunks in collections that use a hashed shard key.to
stringThe name of the destination shard for the chunk.booleanOptional. 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
booleanOptional. Starting in MongoDB 3.4, for WiredTiger, defaults to
false
.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
documentOptional. 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
booleanOptional. Internal option for testing purposes. The default isfalse
. If set totrue
, the delete phase of amoveChunk
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.
Tip
Considerations![](/docs/v5.2/assets/link.svg)
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.
Behavior![](/docs/v5.2/assets/link.svg)
Indexes![](/docs/v5.2/assets/link.svg)
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![](/docs/v5.2/assets/link.svg)
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.
maxCatchUpPercentageBeforeBlockingWrites
Server Parameter![](/docs/v5.2/assets/link.svg)
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.