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:
ParameterTypeDescriptionnamespace
stringThe namespace of the collection to shard in the form<database>.<collection>
.key
documentThe 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 Indexesunique
booleanOptional. 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.options
documentOptional. A document containing optional fields, includingnumInitialChunks
and collation
.
The options
argument supports the following options:
ParameterTypeDescriptionnumInitialChunks
integerOptional. 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.
collation
documentOptional. If the collection specified to shardCollection
has 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
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 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
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 unique
parameter, 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 the
last_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