Docs Home → MongoDB Manual

sh.shardCollection()

On this page本页内容

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.使用该key作为分片键对集合进行分片。分片键决定MongoDB如何在分片之间分发集合的文档。

Note

Changed in version 6.0.6.0版更改。

Starting in MongoDB 6.0, sharding a collection does not require you to first run the sh.enableSharding() method to configure the database.从MongoDB 6.0开始，对集合进行分片不需要首先运行sh.enableSharding()方法来配置数据库。

Important

mongosh Method

This page documents a mongosh method. This is not the documentation for database commands or language-specific drivers, such as Node.js.

For the database command, see the shardCollection command.

For MongoDB API drivers, refer to the language-specific MongoDB driver documentation.

For the legacy mongo shell documentation, refer to the documentation for the corresponding MongoDB Server release:

mongo shell v4.4

sh.shardCollection() takes the following arguments:采用以下参数：

Parameter参数Type类型Description描述
namespacestringThe namespace of the collection to shard in the form "<database>.<collection>".集合的命名空间以"<database>.<collection>"的形式分片。
keydocumentThe document that specifies the field or fields to use as the shard key.指定要用作分片键的一个或多个字段的文档。
{ <field1>: <1|"hashed">, ... }
Set the field value to either: 将字段值设置为： shard key must be supported by an index. 分片键必须由索引支持。Unless the collection is empty, the index must exist prior to the shardCollection command. 除非集合为空，否则索引必须存在于shardCollection命令之前。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.如果集合为空，如果可以支持分片键的索引不存在，MongoDB会在对集合进行分片之前创建索引。
See also Shard Key Indexes 另请参阅分片键索引
uniquebooleanOptional.可选的。Specify true to ensure that the underlying index enforces a unique constraint. 指定true以确保基础索引强制执行唯一约束。Defaults to false.默认为false。
You cannot specify true when using hashed shard keys.使用哈希分片键时不能指定true。
If specifying the options document, you must explicitly specify the value for unique. 如果指定options档，则必须显式指定unique的值。
optionsdocumentOptional.可选的。A document containing optional fields, including numInitialChunks and collation.包含可选字段的文档，包括numInitialChunks和collation。

The options argument supports the following options:options参数支持以下选项：

Parameter参数Type类型Description描述
numInitialChunksintegerOptional.可选的。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. 然后MongoDB在集群中创建并平衡区块。The numInitialChunks parameter must be less than 8192 chunks per shard. Defaults to 2 chunks per shard.numInitialChucks参数每个分片必须少于8192个块。默认为每个分片2个块。
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.如果使用presplitHashedZones: true进行分片，MongoDB将尝试在集群中的区域中均匀分布指定数量的块。
  • 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.如果使用presplitHashedZones: false或省略进行分片，并且没有为空集合定义区域和区域范围，MongoDB会尝试在集群中的分片中均匀分布指定数量的块。
  • If sharding with presplitHashedZones: false or omitted and zones and zone ranges have been defined for the empty collection, numInitChunks has no effect.如果使用presplitHashedZones: false或省略进行分片，并且已经为空集合定义了区域和区域范围，则numInitChunks无效。

Changed in version 4.4.4.4版更改。
collationdocumentOptional.可选的。If the collection specified to shardCollection has a default collation, you must include a collation document with{ locale : "simple" }, or the shardCollection command fails. 如果指定给shardCollection的集合具有默认排序规则，则必须包含带有{ locale : "simple" }的排序规则文档，否则shardCollection命令将失败。At least one of the indexes whose fields support the shard key pattern must have the simple collation.字段支持分片-key模式的索引中至少有一个必须具有简单排序规则。
presplitHashedZonesbooleanOptional.可选的。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. 指定true可根据为集合定义的区域和区域范围，为空集合或不存在的集合执行初始区块创建和分发。For hashed sharding only.仅用于哈希分片。
shardCollection() with presplitHashedZones: true returns an error if any of the following are true: 如果以下任何一项为真，则shardCollection()配合presplitHashedZones: true返回错误：
New in version 4.4. 4.4版新增。
timeseriesdocumentOptional.可选的。Specify this option to create a new sharded time series collection.指定此选项可创建新的分片时间序列集合。
To shard an existing time series collection, omit this parameter.若要分割现有的时间序列集合，请省略此参数。
When the collection specified to shardCollection is a time series collection and the timeseries option is not specified, MongoDB uses the values that define the existing time series collection to populate the timeseries field.当指定给shardCollection的集合是时间序列集合并且没有指定timeseries选项时，MongoDB会使用定义现有时间序列集合的值来填充timeseries字段。
For detailed syntax, see Time Series Options. 有关详细语法，请参阅时间序列选项。

Time Series Options时间序列选项

New in version 5.1. 5.1版新增。

To create a new time series collection that is sharded, specify the timeseries option to sh.shardCollection().要创建新的分片时间序列集合，请将timeseries选项指定为sh.shardCollection()。

The timeseries option takes the following fields:timeseries选项采用以下字段：

Field字段Type类型Description描述
timeFieldstringRequired.必要的。The name of the field which contains the date in each time series document. 包含每个时间序列文档中的日期的字段的名称。Documents in a time series collection must have a valid BSON date as the value for the timeField. 时间序列集合中的文档必须具有有效的BSON日期作为timeField的值。
metaFieldstringOptional.可选的。The name of the field which contains metadata in each time series document. 包含每个时间序列文档中的元数据的字段的名称。The metadata in the specified field should be data that is used to label a unique series of documents. 指定字段中的元数据应该是用于标记一系列唯一文档的数据。The metadata should rarely, if ever, change.元数据应该很少更改（如果有的话）。
The name of the specified field may not be _id or the same as the timeseries.timeField. 指定字段的名称不能为_id，也不能与timeseries.timeField相同。The field can be of any type. 字段可以是任何类型。
granularitystringOptional.可选的。Possible values are:可能的值为：
  • "seconds"
  • "minutes"
  • "hours"
By default, MongoDB sets the granularity to "seconds" for high-frequency ingestion.默认情况下，MongoDB将高频摄取的granularity设置为"seconds"。
Manually set the granularity parameter to improve performance by optimizing how data in the time series collection is stored internally. 手动设置granularity参数，通过优化时间序列集合中数据的内部存储方式来提高性能。To select a value for granularity, choose the closest match to the time span between consecutive incoming measurements.要选择granularity值，请选择与连续传入测量之间的时间跨度最匹配的值。
If you specify the timeseries.metaField, consider the time span between consecutive incoming measurements that have the same unique value for the metaField field. 如果指定timeseries.metaField，请考虑具有相同metaField字段唯一值的连续传入测量之间的时间跨度。Measurements often have the same unique value for the metaField field if they come from the same source.如果测量值来自同一来源，则metaField字段通常具有相同的唯一值。
If you do not specify timeseries.metaField, consider the time span between all measurements that are inserted in the collection.如果未指定timeseriesMetField，请考虑插入集合中的所有测量值之间的时间跨度。
If you set the granularity parameter, you can't set the bucketMaxSpanSeconds and bucketRoundingSeconds parameters. 如果设置了granularity参数，则无法设置bucketMaxSpanSeconds和bucketRoundingSeconds参数。

Considerations注意事项

Once a collection has been sharded, MongoDB provides no method to unshard a sharded collection.一旦对集合进行了分片，MongoDB就不提供任何方法来取消对分片集合的分片。

Shard Keys分片键

While you can change your shard key later, it is important to carefully consider your shard key choice to avoid scalability and perfomance issues.虽然稍后可以更改分片键，但重要的是要仔细考虑分片键的选择，以避免可扩展性和性能问题。

Shard Keys on Time Series Collections时间序列集合上的分片键

When sharding time series collections, you can only specify the following fields in the shard key:对时间序列集合进行分片时，只能在分片键中指定以下字段：

  • The metaField
  • Sub-fields of metaField
  • The timeField

You may specify combinations of these fields in the shard key. No other fields, including _id, are allowed in the shard key pattern.您可以在分片键中指定这些字段的组合。在分片-key模式中不允许使用其他字段，包括_id。

When you specify the shard key:指定分片关键帧时：

Tip

Avoid specifying only the timeField as the shard key. 避免只将timeField指定为分片键。Since the timeField increases monotonically, it may result in all writes appearing on a single chunk within the cluster. 由于timeField单调增加，它可能导致所有写入都出现在集群内的单个块上。Ideally, data is evenly distributed across chunks.理想情况下，数据在块之间均匀分布。

To learn how to best choose a shard key, see:要了解如何最好地选择分片键，请参阅：

Tip

See also: 另请参阅：

Hashed Shard Keys哈希分片键

Hashed shard keys use a hashed index or a compound hashed index as the shard key.哈希分片键使用哈希索引或复合哈希索引作为分片键。

Use the form field: "hashed" to specify a hashed shard key field.使用形式field: "hashed"指定一个哈希分片键字段。

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.如果在创建哈希分片键集合时正在进行块迁移，则在平衡器自动平衡集合之前，初始块分布可能不均衡。

Tip

See also: 另请参阅：

Hashed Sharding哈希分片

Zone Sharding and Initial Chunk Distribution区域分割和初始块分布

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. 如果已经为集合定义了区域和区域范围，则分片集合操作（即shardCollection命令和sh.shardCollection()助手）可以为空集合或不存在的集合执行初始块创建和分发。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.在初始分发之后，平衡器按照惯例管理块分发。

See Pre-Define Zones and Zone Ranges for an Empty or Non-Existing Collection for an example. 有关示例，请参阅空集合或不存在集合的预定义分区和分区范围。If sharding a collection using a ranged or single-field hashed shard key, the numInitialChunks option has no effect if zones and zone ranges have been defined for the empty collection.如果使用范围或单字段散列的分片键对集合进行分片，则如果已为空集合定义了区域和区域范围，则numInitialChunks选项无效。

To shard a collection using a compound hashed index, see Initial Chunk Distribution with Compound Hashed Indexes.要使用复合哈希索引对集合进行分片，请参阅使用复合哈希指数的初始区块分布。

Initial Chunk Distribution with Compound Hashed Indexes具有复合哈希索引的初始块分布

Starting in version 4.4, MongoDB supports sharding collections on compound hashed indexes. 从4.4版本开始，MongoDB支持在复合散列索引上对集合进行分片。When sharding an empty or non-existing collection using a compound hashed shard key, additional requirements apply in order for MongoDB to perform initial chunk creation and distribution.当使用复合散列的分片键对空的或不存在的集合进行分片时，为了让MongoDB执行初始的区块创建和分发，还需要额外的要求。

The numInitialChunks option has no effect if zones and zone ranges have been defined for the empty collection and presplitHashedZones is false.如果已为空集合定义了区域和区域范围，并且presplitHashedZones为false，则numInitialChunks选项无效。

See Pre-Define Zones and Zone Ranges for an Empty or Non-Existing Collection for an example.有关示例，请参阅空集合或不存在集合的预定义分区和分区范围。

Tip

See also: 另请参阅：

Initial Chunks初始区块

Uniqueness独特性

If specifying unique: true:如果指定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.如果集合为空，则sh.shardCollection()会在分片键上创建唯一索引（如果该索引不存在）。
  • If the collection is not empty, you must create the index first before using sh.shardCollection().如果集合不为空，则必须先创建索引，然后才能使用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.尽管可以有一个以分片键为前缀的唯一复合索引，但如果使用unique参数，则集合必须有一个位于分片键上的唯一索引。

See also Sharded Collection and Unique Indexes另请参阅分片集合和唯一索引

Collation排序规则

If the collection has a default collation, the sh.shardCollection() command must include a collation parameter with the value { locale: "simple" }. 如果集合具有默认排序规则，则sh.shardCollection()命令必须包含值为{ locale: "simple" }的collation参数。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.对于具有默认排序规则的非空集合，必须至少有一个具有简单排序规则的索引，其字段支持分片-key模式。

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.不需要为没有排序规则的集合指定collation选项。如果为没有排序规则的集合指定排序规则选项，则该选项将无效。

Write Concern写入关注

mongos uses "majority" for the write concern of the shardCollection command and its helper sh.shardCollection().mongos使用"majority"作为shardCollection命令及其助手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:给定名为records的数据库中的一个名为people的集合，以下命令将按zipcode字段对该集合进行分片：

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

Usage with Options使用选项

The phonebook database has a collection contacts with no default collation. phonebook数据库有一个没有默认排序规则的contacts集合。The following example uses sh.shardCollection() to shard the phonebook.contacts with:以下示例使用sh.shardCollection()对phonebook.contacts进行分片：

  • a hashed shard key on the last_name field,last_name字段上的哈希分片键，
  • 5 initial chunks, and初始组块，以及
  • a collation of simple.simple排序规则。
sh.shardCollection(
  "phonebook.contacts",
  { last_name: "hashed" },
  false,
  {
    numInitialChunks: 5,
    collation: { locale: "simple" }
  }
)
Tip

See also: 另请参阅：