Docs Menu
Docs Home
/
MongoDB Manual
/ / /

moveCollection

On this page

  • Definition
  • Compatibility
  • Syntax
  • Command Fields
  • Considerations
  • Requirements
  • Example
  • Learn More
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:

  • MongoDB Atlas: The fully managed service for MongoDB deployments in the cloud

Note

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

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.

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%.

Important

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

  • the database running out of space and shutting down

  • decreased performance

  • the operation taking longer than expected

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",
}
)

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

Back

moveChunk

Next

movePrimary