unshardCollection

On this page

Definition

Compatibility
Restrictions
Syntax
Command Fields
Considerations
Requirements
Behavior
Examples
Learn More

Definition

unshardCollection

Unshards an existing sharded collection and moves the collection data onto a single shard. When you unshard a collection, the collection cannot be partitioned across multiple shards and the shard key is removed.

New in version 8.0.

Tip

In mongosh, this command can also be run through the sh.unshardCollection().

Helper methods are convenient for mongosh users, but they may not return the same level of information as database commands. In cases where the convenience is not needed or the additional return fields are required, use the database command.

This command must run on the admin database.

If the collection has a zone configuration applied, you must first remove the range associations and shards from the zone before you unshard the collection. For more information, see Unshard Zones.

Note

Unsharding a collection is a write-intensive operation that can result in an increased oplog growth rate. To help mitigate this, consider the following configuration changes:

To prevent unbounded oplog growth, set a fixed oplog size.
To reduce the chance of secondaries becoming stale, increase the oplog size.

For more details, see the Replica Set Oplog.

Compatibility

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

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

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

Important

This command cannot be run on shared or serverless instances. For more information, see Unsupported Commands.

Restrictions

You cannot use unshardCollection for:

Time series collections.
Queryable Encryption collections.

Syntax

db.adminCommand( {
   unshardCollection: "<database>.<collection>",
   toShard: "<shard-id>"
} )

Command Fields

Field	Type	Necessity	Description
`unshardCollection`	string	Required	Specifies the database and collection to unshard.
`toShard`	string	Optional	Specifies the recipient shard ID. As MongoDB unshards the collection, it moves collection data from their current shards to this specific shard. If unspecified, the cluster selects the shard with the least amount of data.

Considerations

unshardCollection can only be run on sharded clusters.
unshardCollection can only operate on sharded collections.
unshardCollection can only operate on a single collection at a time.
unshardCollection has a 5 minute minimum duration.
You must rebuild Atlas Search indexes after unshardCollection runs.
You cannot make topology changes, such as adding or removing shards or transitioning between embedded and dedicated config servers, until unshardCollection completes.
You cannot run the following operations on the collection that is being unsharded while unshardCollection is in progress:
You cannot run the following operations on the cluster while unshardCollection is in progress:
Index builds that occur while unshardCollection is in progress might silently fail.
- Do not create indexes while unshardCollection is in progress.
- Do not call unshardCollection if there are ongoing index builds.

Requirements

Before you unshard 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%.

Behavior

Unshard Zones

To unshard a collection that uses zone sharding, you must first stop the balancer, then remove the range and shard from the zone.

For an example, see Unshard a Zone Sharded Collection.

Examples

Unshard a Collection

The following example unshards the sales.eu_accounts collection:

db.adminCommand( {
    unshardCollection: "sales.eu_accounts"
} )

Unshard to a Specific Shard

The following example unshards the sales.us_accounts collections and places the collection data on shard1:

db.adminCommand( {
    unshardCollection: "sales.eu_accounts",
    toShard: "shard1"
} )

Unshard a Zone Sharded Collection

The following example unshards a collection that uses zones:

Stop the balancer

To stop the balancer, run the balancerStop command:

db.adminCommand( { balancerStop: 1 } )

Identify range associations.

To identify ranges associated with the zones, run the sh.status() method and note the ranges in the chunks field for each sharded collection:

sh.status()

Remove range from the zone

To remove a range from a zone, run the updateZoneKeyRange command:

db.adminCommand( {
   updateZoneKeyRange: "app.inventory",
   min: 100,
   max: 500,
   zone: null
} )

Repeat this step until you have removed all ranges from zones used by the collection.

Remove the shards from zone

To remove shards from the zone, run the removeShardFromZone command

db.adminCommand( {
   removeShardFromZone: "shard01",
   zone: "us"
} )

Repeat until you have removed all collection shards from the zones.

Restart the balancer

To restart the balancer, run the balancerStart command:

db.adminCommand( { balancerStart: 1 } )

Unshard the collection

To unshard the collection, run the unshardCollection command:

db.adminCommand( { unshardCollection: "app.inventory" } )

Learn More

Back

unsetSharding

updateZoneKeyRange