- Reference >
mongo
Shell Methods >- Sharding Methods >
- sh.shardCollection()
sh.shardCollection()¶
On this page
Definition¶
-
sh.
shardCollection
(namespace, key, unique, options)¶ Shards a collection using the
key
as a the shard key.sh.shardCollection()
takes the following arguments:Important
mongo
Shell MethodThis page documents a
mongo
method. This is not the documentation for database commands or language-specific drivers, such as Node.js. To use the database command, see theshardCollection
command.For MongoDB API drivers, refer to the language-specific MongoDB driver documentation.
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
for ranged based sharding"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
, theunique
option ensures that the underlying index enforces a unique constraint. Hashed shard keys do not support unique constraints. Defaults tofalse
. If specifying theoptions
document,unique
is required. Omitting a value forunique
while specifying a value for theoptions
document may result in an incorrectly sharded collection.options
document Optional. A document containing optional fields, including numInitialChunks
andcollation
.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 than8192
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 theshardCollection
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 the selection of the
shard key. However, starting in MongoDB 4.2, you can update a
document’s shard key value (unless the shard key field is the immutable
_id
field). For details, see Change a Document’s Shard Key Value.
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
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.
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
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 exist. - 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.
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:
Usage with Options¶
The phonebook
database has a collection contacts
with no
default collation. The
following example uses
sh.shardCollection()
to shard the phonebook.contacts
with:
- a hashed shard key on the
last_name
field, 5
initial chunks, and- a collation of
simple
.
See also