shardCollection
Definition
shardCollection
- Shards a collection to distribute its documentsacross shards. You must run
enableSharding
on adatabase before running theshardCollection
command.TheshardCollection
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:
FieldTypeDescriptionshardCollection
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
booleanWhen true
, the unique
option ensures that the underlying indexenforces a unique constraint. Hashed shard keys do not support uniqueconstraints. Defaults to false
.numInitialChunks
integerSpecifies 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
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
Zone Sharding and Initial Chunk Distribution
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.
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
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 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 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