Navigation

sh.shardCollection()

Definition

sh.shardCollection(namespace, key, unique, options)

Shards a collection using the key as a the shard key. sh.shardCollection() takes the following arguments:

Parameter Type Description
namespace string The namespace of the collection to shard in the form <database>.<collection>.
key document

The index specification document to use as the shard key. The shard key determines how MongoDB distributes the documents among the shards.

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

  • 1 to indicate forward traversal for the field.
  • -1 to indicate reverse traversal for the field.
  • "hashed" to specify a hashed shard key.

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 Optional. When true, the unique option ensures that the underlying index enforces a unique constraint. Hashed shard keys do not support unique constraints. Defaults to false.
options document Optional. A document containing optional fields, including numInitialChunks and collation.

The options argument supports the following options:

Parameter Type Description
numInitialChunks integer

Optional. 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.

Changed in version 4.0.3: The option has no effect if zones and zone ranges have been defined 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 hashed key, the operation returns an error.

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.

Considerations

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

Shard Keys

Choosing the best shard key to effectively distribute load among your shards requires some planning. Review Shard Keys regarding choosing a shard key and restrictions.

Hashed Shard Keys

Hashed shard keys use a hashed 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 hashed shard key collection, the initial chunk distribution may be uneven until the balancer automatically balances the collection.

See also

Hashed Sharding

Zone Sharding and Initial Chunk Distribution

Changed in version 4.0.3.

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.

If the numInitialChunks option has no effect if zones and zone ranges 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 the shard key if such an index does not already exists.
  • If the collection is not empty, you must create the index first before using sh.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.

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

Examples

Simple Usage

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

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

Usage with Options

Given a collection named contacts in a database named phonebook, the following command:

  • Shards the collection by the last_name field.
  • Indicates that there is no unique constraint on the underlying index.
  • Specifies 5 initial chunks.
  • Specifies a collation.
sh.shardCollection("phonebook.contacts", { last_name: 1 }, false,
                    { numInitialChunks: 5, collation: { locale: "simple" } } )