Docs Menu
Docs Home
/
MongoDB Manual
/ / /

sh.moveCollection()

On this page

  • Definition
  • Syntax
  • Compatibility
  • Considerations
  • Requirements
  • Examples
  • Learn More
sh.moveCollection(coll, 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.

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

mongo shell v4.4

sh.moveCollection() has the following syntax:

sh.moveCollection( "<namespace>.<collection>", "<ID of recipient shard>" )

sh.moveCollection() takes the following parameters:

Parameter
Type
Description
coll
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:

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

Note

This command is not available on the Atlas Shared Tier.

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 examples moves an unsharded collection named inventory on the app database to the shard02 shard.

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

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

Back

sh.moveChunk()

Next

sh.removeRangeFromZone()