shardCollection¶

On this page

Definition
Considerations
Example

Definition¶

shardCollection¶

Shards a collection to distribute its documents across shards. You must run enableSharding on a database before running the shardCollection command. The shardCollection command must be run against the admin database.

To run shardCollection, use the db.runCommand( { <command> } ) method.

shardCollection has the following form:

copy

{
   shardCollection: "<database>.<collection>",
   key: { <field1>: <1|"hashed">, ... },
   unique: <boolean>,
   numInitialChunks: <integer>,
   presplitHashedZones: <boolean>,
   collation: { locale: "simple" }
}

shardCollection has the following fields:

Field	Type	Description
`shardCollection`	string	The namespace of the collection to shard in the form `<database>.<collection>`.
`key`	document	The document that specifies the field or fields to use as the shard key. `{ <field1>: <1\|"hashed">, ... }` Set the field values to either: `1` for ranged based sharding `"hashed"` to specify a hashed shard key. shard key must be supported by an index. Unless the collection is empty, the index must exist prior to the `shardCollection` command. If the collection is empty, MongoDB creates the index prior to sharding the collection if the index that can support the shard key does not already exist. See also Shard Key Indexes
`unique`	boolean	Specify `true` to ensure that the underlying index enforces a unique constraint. Defaults to `false`. You cannot specify `true` when using hashed shard keys.
`numInitialChunks`	integer	Specifies the number of chunks to create initially when sharding an empty collection with a hashed shard key. MongoDB will then create and balance chunks across the cluster. The `numInitialChunks` must be less than `8192` per shard. If the collection is not empty or the shard key does not contain a hashed field, the operation returns an error. If sharding with presplitHashedZones: true, MongoDB attempts to evenly distribute the specified number of chunks across the zones in the cluster. If sharding with presplitHashedZones: false or omitted and no zones and zone ranges are defined for the empty collection, MongoDB attempts to evenly distributed the specified number of chunks across the shards in the cluster. If sharding with presplitHashedZones: false or omitted and zones and zone ranges have been defined for the empty collection, `numInitChunks` has no effect. Changed in version 4.4.
`collation`	document	Optional. If the collection specified to `shardCollection` has a default collation, you must include a collation document with `{ locale : "simple" }`, or the `shardCollection` command fails. At least one of the indexes whose fields support the shard key pattern must have the simple collation.
presplitHashedZones	boolean	Optional. Specify `true` to perform initial chunk creation and distribution for an empty or non-existing collection based on the defined zones and zone ranges for the collection. For hashed sharding only. `shardCollection` with `presplitHashedZones: true` returns an error if any of the following are true: The shard key does not contain a hashed field (i.e. is not a single field hashed index or compound hashed index). The collection has no defined zones or zone ranges. The defined zone range or ranges do not meet the requirements. New in version 4.4.

Considerations¶

Use¶

You can only shard a collection once.

Do not run more than one shardCollection command on the same collection at the same time.

Once a collection has been sharded, MongoDB provides no method to unshard a sharded collection.

Shard Keys¶

Choosing the best shard key to effectively distribute load among your shards requires some planning.

Starting in MongoDB 4.4, you can refine a collection’s shard key by adding a suffix field or fields to the existing key.
Starting in MongoDB 4.2, you can update a document’s shard key value (unless the shard key field is the immutable _id field).

For more information, see Shard Keys.

Hashed Shard Keys¶

Hashed shard keys use a hashed index or a compound hashed index as the shard key.

Use the form field: "hashed" to specify a hashed shard key field.

Note

If chunk migrations are in progress while creating a hashed shard key collection, the initial chunk distribution may be uneven until the balancer automatically balances the collection.

Zone Sharding and Initial Chunk Distribution¶

The shard collection operation (i.e. shardCollection command and the sh.shardCollection() helper) can perform initial chunk creation and distribution for an empty or a non-existing collection if zones and zone ranges have been defined for the collection. Initial chunk distribution allows for a faster setup of zoned sharding. After the initial distribution, the balancer manages the chunk distribution going forward per usual.

See Pre-Define Zones and Zone Ranges for an Empty or Non-Existing Collection for an example. If sharding a collection using a ranged or single-field hashed shard key, the numInitialChunks option has no effect if zones and zone ranges have been defined for the empty collection.

To shard a collection using a compound hashed index, see Zone Sharding and Compound Hashed Indexes.

Zone Sharding and Compound Hashed Indexes¶

Starting in version 4.4, MongoDB supports sharding collections on compound hashed indexes. When sharding an empty or non-existing collection using a compound hashed shard key, additional requirements apply in order for MongoDB to perform initial chunk creation and distribution.

The numInitialChunks option has no effect if zones and zone ranges have been defined for the empty collection and presplitHashedZones is false.

See Pre-Define Zones and Zone Ranges for an Empty or Non-Existing Collection for an example.

Uniqueness¶

If specifying unique: true:

If the collection is empty, shardCollection creates the unique index on the shard key if such an index does not already exist.
If the collection is not empty, you must create the index first before using shardCollection.

Although you can have a unique compound index where the shard key is a prefix, if using unique parameter, the collection must have a unique index that is on the shard key.

Collation¶

Changed in version 3.4.

If the collection has a default collation, the shardCollection command must include a collation parameter with the value { locale: "simple" }. For non-empty collections with a default collation, you must have at least one index with the simple collation whose fields support the shard key pattern.

You do not need to specify the collation option for collections without a collation. If you do specify the collation option for a collection with no collation, it will have no effect.

Write Concern¶

mongos uses "majority" for the write concern of the shardCollection command and its helper sh.shardCollection().

Example¶

The following operation enables sharding for the people collection in the records database and uses the zipcode field as the shard key:

copy

db.adminCommand( { shardCollection: "records.people", key: { zipcode: 1 } } )