sh.shardCollection()

On this page本页内容

Definition定义

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

Shards a collection using the key as a the shard key. 使用key作为分片键来分割集合。The shard key determines how MongoDB distributes the collection's documents among the shards.分片键决定MongoDB如何在分片之间分发集合的文档。

The mongosh method sh.shardCollection() wraps the shardCollection command.mongosh方法sh.shardCollection()包装了shardCollection命令。

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

Parameter参数Type类型Description描述
namespacestringThe namespace of the collection to shard in the form "<database>.<collection>". 要分片的集合的名称空间，格式为"<database>.<collection>"。
keydocument

The 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另请参见分析键索引

uniqueboolean

Optional. 可选。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描述
numInitialChunksinteger

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. 然后，MongoDB在集群中创建和平衡块。The numInitialChunks must be less than 8192 per shard. 每个分片的numInitialChunks必须小于8192。Defaults to 2.默认为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. 字段支持分片键模式的索引中必须至少有一个索引具有简单排序规则。
presplitHashedZonesboolean

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. 指定true以根据为集合定义的区域和区域范围为空集合或不存在的集合执行初始区块创建和分发。For hashed sharding only.仅用于散列分片。

shardCollection() with presplitHashedZones: true returns an error if any of the following are true:带有presplitHashedZones:true的shardCollection()：如果以下任一项为true，则返回错误：

New in version 4.4.在版本4.4中新增。

timeseriesdocument

Optional. 可选。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描述
timeFieldstring

Required. 必需。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的值。

metaFieldstring

Optional. 可选。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.字段可以是任何类型。

granularitystring

Optional. 可选。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，请考虑具有相同metaFields字段唯一值的连续传入测量之间的时间跨度。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.如果未指定timeseries.metaField，请考虑插入集合的所有度量之间的时间跨度。

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 metaFieldmetaField
  • Sub-fields of metaFieldmetaField的子字段
  • 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.分片键模式中不允许包含_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提示

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"指定一个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: 参阅：

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命令和shshardCollection()助手）可以为空集合或不存在的集合执行初始区块创建和分发。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 andpresplitHashedZones 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: 参阅：

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排序规则

Changed in version 3.4.在版本3.4中更改。

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" }的排序规则参数。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. 不需要为没有排序规则的集合指定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:在名为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分片为：

sh.shardCollection(
  "phonebook.contacts",
  { last_name: "hashed" },
  false,
  {
    numInitialChunks: 5,
    collation: { locale: "simple" }
  }
)
Tip提示
←  sh.setBalancerState()sh.splitAt() →