moveCollection

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.

Compatibility

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

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

• MongoDB Enterprise: The subscription-based, self-managed version of MongoDB

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

Syntax

The command has the following syntax:

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

Command Fields

The command takes the following fields:

Considerations

• 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:

  • collMod

  • convertToCapped

  • createIndexes

  • db.collection.createIndexes()

  • drop

  • db.collection.drop()

  • dropIndexes

  • db.collection.dropIndex()

  • renameCollection

  • db.collection.renameCollection()

• You cannot run the following operations against the cluster while moveCollection is in progress:

  • addShard

  • removeShard

  • db.createCollection()

  • dropDatabase

  • transitionToDedicatedConfigServer

  • transitionFromDedicatedConfigServer

Requirements

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 size + Index Size ) * 1.2 bytes available. This extra space helps accomodate incoming writes during the moveCollection operation.

  • Ensure that your I/O capacity is below 50%.

  • Ensure that your CPU load is below 80%.

Example

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.

Learn More

• sh.moveCollection()