sh.moveCollection()

On this page

Definition

sh.moveCollection(namespace, destination): Moves a single unsharded collection to a different shard. Run sh.moveCollection() with a mongos instance while using the admin database.
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 moveCollection command.
For MongoDB API drivers, refer to the language-specific MongoDB driver documentation.

sh.moveCollection() has the following syntax:

sh.moveCollection( "<database>.<collection>" )

sh.moveCollection() takes the following parameters:

Parameter	Type	Description
`namespace`	string	Database and name of the collection to move.
`toShard`	string	Optional. ID of the recipient shard. If you do not specify a shard to move to, the balancer moves the collection to the least loaded shard.

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

This command is not available on the Atlas Shared Tier.

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

sh.moveCollection() can only be run on sharded clusters.
sh.moveCollection() can only move unsharded collections.
sh.moveCollection() can only move a single collection at a time.
sh.moveCollection() has a 5 minute minimum duration.
Atlas Search indexes need to be rebuilt after moveCollection runs.
You cannot make topology changes, such as add or remove shard or transition between embedded and dedicated config servers, until moveCollection completes.
You cannot run the following operations against the collection that is being moved while sh.moveCollection() is in progress:
You cannot run the following operations against the cluster while moveCollection is in progress:
- addShard
- removeShard
- db.createCollection()
- dropDatabase
- transitionToDedicatedConfigServer
- transitionFromDedicatedConfigServer
Index builds that occur while sh.moveCollection() is in progress might silently fail.
- Do not create indexes while sh.moveCollection() is in progress.
- Do not call sh.moveCollection() if there are ongoing index builds.

Before you move your collection, ensure that you meet the following requirements:

Your application can tolerate a period of two seconds where the affected collection blocks writes. During the time period where writes are blocked, your application experiences an increase in latency.
Your database meets these resource requirements:
- Ensure the shard you are moving the collection to has enough storage space for the collection and its indexes. The destination shard requires at least ( Collection storage size + Index Size ) * 2 bytes available.
- Ensure that your I/O capacity is below 50%.
- Ensure that your CPU load is below 80%.

These requirements are not enforced by the database. A failure to allocate enough resources can result in:

If your application has time periods with less traffic, perform this operation on the collection during that time if possible.

This example moves an unsharded collection named inventory on the app database to the shard02 shard.

sh.moveCollection( "app.inventory", "shard02" )

To get a list of the available shard IDs, run sh.status(). For details, see sh.status() Output.

Back

sh.moveChunk

sh.removeRangeFromZone