Docs Menu

Docs HomeDevelop ApplicationsMongoDB Manual

sh.moveChunk()

On this page

  • Definition
  • Compatibility
  • Example
sh.moveChunk(namespace, query, destination)

Moves the chunk that contains the document specified by the query to the destination shard. sh.moveChunk() provides a wrapper around the moveChunk database command.

Important

In most circumstances, allow the balancer to automatically migrate chunks, and avoid calling sh.moveChunk() directly.

Warning

This command cannot be used for hashed shard keys, as it uses the find option from the moveChunk command. To move a chunk with a hashed shard key, use the moveChunk command specifying the bounds field.

Important

mongosh Method

This page documents a mongosh method. This is not the documentation for database commands or language-specific drivers, such as Node.js.

For the database command, see the moveChunk command.

For MongoDB API drivers, refer to the language-specific MongoDB driver documentation.

For the legacy mongo shell documentation, refer to the documentation for the corresponding MongoDB Server release:

mongo shell v4.4

sh.moveChunk() takes the following arguments:

Parameter
Type
Description
namespace
string
The namespace of the sharded collection that contains the chunk to migrate.
query
document
An equality match on the shard key that selects the chunk to move.
destination
string
The name of the shard to move.

By default, MongoDB cannot move a chunk if the number of documents in the chunk is greater than 1.3 times the result of dividing the configured chunk size by the average document size. The moveChunk command can specify the forceJumbo option to allow for the manual migration of chunks too large to move, with or without the jumbo label. See moveChunk command for details.

Tip

See also:

This method 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 not supported in serverless instances. For more information, see Unsupported Commands.

Given the people collection in the records database, the following operation finds the chunk that contains the documents with the zipcode field set to 53187 and then moves that chunk to the shard named shard0019:

sh.moveChunk("records.people", { zipcode: "53187" }, "shard0019")
←  sh.isBalancerRunning()sh.removeRangeFromZone() →