/ /

/ /

sh.unshardCollection (mongosh method)

Definition

sh.unshardCollection( namespace, shardID )

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.

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 unshardCollection command.

For MongoDB API drivers, refer to the language-specific MongoDB driver documentation.

The sh.unshardCollection method requires you to specify the shard to receive the collection data. With the unshardCollection command, if you don't specify the destination shard, the cluster automatically selects the shard with the least data.

If the collection uses zone sharding, you must first remove the range associations and shard 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.

Syntax

sh.unshardCollection has the following syntax:

sh.unshardCollection( namespace, shardID )

Parameters

Parameter	Type	Description
`namespace`	string	Specifies the database and collection to unshard.
`shardID`	string	Specifies the recipient shard ID. As MongoDB unshards the collection, it moves the collection data from their current shards to this specific shard.

Compatibility

This method 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

Considerations

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

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.

Examples

Unshard a Collection

This example unshards a collection named inventory on the app database to the shard02 shard.

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

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

Learn More

Back

sh.stopBalancer

sh.updateZoneKeyRange