sh.shardCollection()

Definition

• sh.shardCollection(namespace, key, unique, options)
• Shards a collection using the key as a the shardkey. sh.shardCollection() takes the following arguments:

ParameterTypeDescriptionnamespacestringThe 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 IndexesuniquebooleanOptional. When true, the unique option ensures that the underlying indexenforces a unique constraint. Hashed shard keys do not support uniqueconstraints. Defaults to false. If specifying theoptions document, unique is required.Omitting a value for unique while specifying a value forthe options document may result in an incorrectly shardedcollection.optionsdocumentOptional. A document containing optional fields, includingnumInitialChunks and collation.

The options argument supports the following options:

ParameterTypeDescriptionnumInitialChunksintegerOptional. Specifies 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

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 a single 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

Changed in version 4.0.3.

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.

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, sh.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 sh.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 sh.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().

Examples

Simple Usage

Given a collection named people in a database named records,the following command shards the collection by thezipcode field:

sh.shardCollection("records.people", { zipcode: 1 } )

Usage with Options

The phonebook database has a collection contacts with nodefault collation. Thefollowing example usessh.shardCollection() to shard the phonebook.contacts with:

• a hashed shard key on thelast_name field,
• 5 initial chunks, and
• a collation of simple.

sh.shardCollection(
  "phonebook.contacts",
  { last_name: "hashed" },
  false,
  {
    numInitialChunks: 5,
    collation: { locale: "simple" }
  }
)

See also

shardCollection, Sharding