sh.shardCollection()

Definition

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

Shards a collection using the key as a the shard key. The shard key determines how MongoDB distributes the collection's documents among the shards.

The mongo shell method sh.shardCollection() wraps the shardCollection command.

Important

mongo Shell Method

This 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 the shardCollection 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 document that specifies the field or fields to use as the shard key. { <field1>: <1|"hashed">, ... } Set the field value to either: 1 for ranged based sharding "hashed" to specify a hashed shard key. shard key must be supported by an index. 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. Specify true to ensure that the underlying index enforces a unique constraint. Defaults to false. You cannot specify true when using hashed shard keys. If specifying the options document, you must explicitly specify the value for unique.
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 minimum number of chunks to create initially when sharding an empty collection with a hashed shard key. MongoDB then creates and balances chunks across the cluster. The numInitialChunks parameter must be less than 8192 chunks per shard. Defaults to 2 chunks per shard. If the collection is not empty or the shard key does not contain a hashed field, the operation returns an error. If sharding with presplitHashedZones: true, MongoDB attempts to evenly distribute the specified number of chunks across the zones in the cluster. If sharding with presplitHashedZones: false or omitted and no zones and zone ranges are defined for the empty collection, MongoDB attempts to evenly distributed the specified number of chunks across the shards in the cluster. If sharding with presplitHashedZones: false or omitted and zones and zone ranges have been defined for the empty collection, numInitChunks has no effect. Changed in version 4.4.
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.
presplitHashedZones	boolean	Optional. Specify true to perform initial chunk creation and distribution for an empty or non-existing collection based on the defined zones and zone ranges for the collection. For hashed sharding only. shardCollection() with presplitHashedZones: true returns an error if any of the following are true: The shard key does not contain a hashed field (i.e. is not a single field hashed index or compound hashed index). The collection has no defined zones or zone ranges. The defined zone ranges do not meet the requirements. New in version 4.4.

Considerations

Once a collection has been sharded, MongoDB provides no method to unshard a sharded collection.

Examples

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

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