moveCollection

On this page

Definition

moveCollection: New in version 8.0.
Moves a single unsharded collection to a different shard. Run moveCollection with a mongos instance while using the admin database.

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

This command is not available on the Atlas Shared Tier or on Atlas Serverless.

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

The command has the following syntax:

db.adminCommand(
  {
    moveCollection: "<database>.<collection>",
    toShard: "<ID of the recipient shard>",
  }
)

The command takes the following fields:

Field	Type	Description
`moveCollection`	string	Database and name of the collection to move.
`toShard`	string	ID of the recipient shard.

moveCollection can only be run on sharded clusters.
moveCollection can only move unsharded collections.
moveCollection can only move a single collection at a time.
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 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 moveCollection is in progress might silently fail.
- Do not create indexes while moveCollection is in progress.
- Do not call 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.

db.adminCommand(
  {
    moveCollection: "app.inventory",
    toShard: "shard02"
  }
)

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

Back

moveChunk

movePrimary