shardCollection

Definition

• shardCollection
• Shards a collection to distribute its documentsacross shards. You must run enableSharding on adatabase before running the shardCollection command.The shardCollection command must be run against theadmin database.

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

shardCollection has the following form:

{
   shardCollection: "<database>.<collection>",
   key: <shardkey>,
   unique: <boolean>,
   numInitialChunks: <integer>,
   collation: { locale: "simple" }
}

shardCollection has the following fields:

FieldTypeDescriptionshardCollectionstringThe namespace of the collection to shard in the form<database>.<collection>.keydocumentThe index specification document to use as theshard key. The shard keydetermines how MongoDB distributes the documents among the shards.

The key of the index specification document is the field to use asthe shard key. The value of the document must be one of thefollowing:

• 1 for ranged based sharding
• "hashed" to specify ahashed shard key.Unless the collection is empty, the index must exist prior to theshardCollection command. If the collection is empty,MongoDB creates the index prior to sharding the collection if theindex that can support the shard key does not already exist.

See also Shard Key IndexesuniquebooleanWhen true, the unique option ensures that the underlying indexenforces a unique constraint. Hashed shard keys do not support uniqueconstraints. Defaults to false.numInitialChunksintegerSpecifies the number of chunks to createinitially when sharding an empty collection with a hashedshard key. MongoDB will then create andbalance chunks across the cluster. The numInitialChunks must beless than 8192 per shard.

Changed in version 4.0.3: The option has no effect if zones and zone ranges have beendefined for the empty collection. See Zone Sharding and Initial Chunk Distribution.

Changed in version 3.4: If the collection is not empty or the shard key is not a hashedkey, the operation returns an error.

collationdocumentOptional. If the collection specified to shardCollectionhas a default collation,you must include a collation document with{ locale : "simple" }, orthe shardCollection command fails. At least one of the indexeswhose fields support the shard key pattern must have the simplecollation.

Considerations

Use

You can only shard a collection once.

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

MongoDB provides no method to deactivate sharding for a collectionafter calling shardCollection. Additionally, aftershardCollection, you cannot change shard keys or modifythe value of any field used in your shard key index.

Shard Keys

Choosing the best shard key to effectively distribute load among yourshards requires some planning. Review Shard Keysregarding choosing a shard key and restrictions.

Hashed Shard Keys

Hashed shard keys use ahashed index of asingle field as the shard key.

Use the form {field: "hashed"} to specify a hashed shard key.Hashed shard keys may not be compound indexes.

Note

If chunk migrations are in progress while creating a hashedshard key collection, the initial chunk distribution may beuneven until the balancer automatically balances thecollection.

See also

Hashed Sharding

Zone Sharding and Initial Chunk Distribution

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

If the numInitialChunks option has no effect if zones and zoneranges have been defined for the empty collection.

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

See also

Initial Chunks

Uniqueness

If specifying unique: true:

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

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

See also Sharded Collection and Unique Indexes

Collation

Changed in version 3.4.

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

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

Write Concern

mongos uses "majority" for thewrite concern of theshardCollection command and its helpersh.shardCollection().

Example

The following operation enables sharding for the people collectionin the records database and uses the zipcode field as theshard key:

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

See also

Sharding