shardCollection（数据库命令）

定义

shardCollection: Shards a collection to distribute its documents across shards. The shardCollection command must be run against the admin database.
提示
In mongosh, this command can also be run through the sh.shardCollection() helper method.
Helper methods are convenient for mongosh users, but they may not return the same level of information as database commands. In cases where the convenience is not needed or the additional return fields are required, use the database command.

兼容性

此命令可用于以下环境中托管的部署：

MongoDB Atlas：用于云中 MongoDB 部署的完全托管服务

MongoDB Enterprise：基于订阅、自我管理的 MongoDB 版本
MongoDB Community：源代码可用、免费使用且可自行管理的 MongoDB 版本

语法

To run shardCollection, use the db.runCommand( { <command> } ) method.

该命令采用以下形式：

db.adminCommand(
   {
     shardCollection: "<database>.<collection>",
     key: { <field1>: <1|"hashed">, ... },
     unique: <boolean>,
     numInitialChunks: <integer>,
     presplitHashedZones: <boolean>,
     collation: { locale: "simple" },
     timeseries: <object>
   }
 )

注意

在版本6.0中进行了更改。

从 MongoDB 6.0 开始，对集合进行分片无需首先运行 enableSharding 命令来配置数据库。

命令字段

该命令接受以下字段：

字段	类型	说明
`shardCollection`	字符串	要分片的集合的命名空间，格式为 `<database>.<collection>`。
`key`	文档	指定一个或多个字段用作分片键的文档。 `{ <field1>: <1\|"hashed">, ... }` 将字段值设置为以下任一项： `1` 用于基于范围的分片 `"hashed"` 指定哈希分片键。 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. 另请参阅分片键索引
`unique`	布尔	指定 `true` 以确保基础索引执行唯一约束。默认值为 `false`。使用哈希分片键时，不能指定 `true`。
`numInitialChunks`	整型	指定在使用哈希分片键对空集合进行分片时，要在集群中所有分片上创建的数据块初始数量。然后，MongoDB 在集群中创建并均衡数据块。`numInitialChunks` 的结果必须少于每个分片的 `8192`。如果集合不为空或分片键不包含哈希字段，则操作将返回错误。如果使用 presplitHashedZones: true 进行分片，MongoDB 会尝试将指定数量的数据块平均分配到集群中的各区域。如果使用 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.
`collation`	文档	可选。如果指定给 `shardCollection` 的集合具有默认排序规则，则必须包含附带 `{ locale : "simple" }` 的排序规则文档，否则 `shardCollection` 命令将失败。对于其字段支持分片键模式的索引，必须至少有一个索引采用简易排序规则。
presplitHashedZones	布尔	可选。指定 `true` 以基于为集合定义的区域和区域范围来执行空集合或不存在集合的初始数据段创建和分发。仅用于哈希分片。 `shardCollection` 和 `presplitHashedZones: true` 返回错误，如果满足以下任一条件：分片键不包含哈希字段（即不是单个字段的哈希索引或复合哈希索引）。集合没有定义的区域或区域范围。定义的区域范围不符合要求。
时间序列	对象	可选。指定此选项可创建新的分片时间序列集合。要对现有的时间序列集合进行分片，请省略此参数。当指定给 `shardCollection` 的集合是时间序列集合并且未指定 `timeseries` 选项时，MongoDB 将使用定义现有时间序列集合的值来填充 `timeseries` 字段。有关详细语法，请参阅时间序列选项。 5.1版本新增。

时间序列选项

5.1版本新增。

To create a new time series collection that is sharded, specify the timeseries option to shardCollection.

timeseries 选项包含以下字段：

字段	类型	说明
`timeField`	字符串	必需。包含每个时间序列文档中日期的字段的名称。时间序列集合中的文档必须具有有效 BSON 日期，以作为 `timeField` 的值。
`metaField`	字符串	可选。包含每个时间序列文档中元数据的字段的名称。指定字段中的元数据应是用于标记一系列独一无二的文档的数据。元数据应该很少改变（如有）。指定字段的名称可能不是 `timeseries.timeField` 或与 `_id` 相同。该字段可以是任何数据类型。虽然`metaField`字段是可选的，但使用元数据可以改进查询优化。例如，MongoDB 会自动为新集合的`metaField`和`timeField`字段创建复合索引。如果您没有为此字段提供值，则仅根据时间对数据进行分桶。
`granularity`	字符串	可选。可能的值为： `"seconds"` `"minutes"` `"hours"` 默认情况下，MongoDB 将 `granularity` 设置为 `"seconds"` 以进行高频提取。手动设置 `granularity` 参数，通过优化时间序列集合中数据的内部存储方式来提高性能。要选择 `granularity` 的值，请选择与连续传入测量之间的时间跨度最接近的匹配项。如果您指定 `timeseries.metaField`，请考虑 `metaField` 字段具有相同唯一值的连续传入测量值之间的时间跨度。如果测量值来自同一来源，则 `metaField` 字段通常具有相同的唯一值。如果未指定 `timeseries.metaField`，请考虑插入到集合中的所有测量值之间的时间跨度。如果设置了 `granularity` 参数，就无法设置 `bucketMaxSpanSeconds` 和 `bucketRoundingSeconds` 参数。

Considerations

分片键

虽然您可在后续更改分片键，但请务必仔细考虑分片键的选择，以免出现可扩展性与性能问题。

提示

时间序列集合上的分片键

对时间序列集合进行分片时，您只能为分片键指定以下字段：

使用 metaField
子字段 metaField
使用 timeField

您可以在分片键中指定这些字段的组合。不允许在分片键模式中使用任何其他字段，包括 _id。

在您指定分片键时：

metaField 可以是:
- 哈希片键
- 基于范围的分片键
timeField 必须是：
- 基于范围的分片键
- 在分片键模式的末尾

提示

避免仅指定 timeField 作为分片键。由于 timeField 是单调增加的，因此，可能导致所有写入都出现在集群中的单个数据段上。理想情况下，数据均匀分布在数据段之间。

要了解如何最好地选择分片键，请参阅：

哈希分片键

哈希分片键使用哈希索引或复合哈希索引作为分片键。

使用表单 field: "hashed" 指定哈希分片键字段。

注意

如果在创建哈希分片键集合时正在进行块迁移，则初始块分布可能会不均匀，直到负载均衡器自动平衡集合。

提示

哈希分片

区域分片和初始数据块分布

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.

有关示例，请参阅为空集合或不存在的集合预先定义区域和区域范围。如果使用范围或单字段哈希分片键对集合进行分片，并且已为空集合定义了区域和区域范围，则 numInitialChunks 选项将不起作用。

要使用复合哈希索引对集合进行分片，请参阅区域分片和复合哈希索引。

区域分片和复合哈希索引

MongoDB 支持使用组合哈希索引对集合进行分片。在使用组合哈希分片键对空集合或不存在的集合进行分片时，需要满足额外的要求，MongoDB 才能执行初始数据块创建和分配。

The numInitialChunks option has no effect if zones and zone ranges have been defined for the empty collection and presplitHashedZones is false.

有关示例，请参阅为空集合或不存在的集合预先定义区域和区域范围。

提示

唯一性

如果指定 unique: true：

If the collection is empty, 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 shardCollection.

尽管可以有以分片键为前缀的唯一复合索引，但如果使用unique参数，则集合必须在分片键上有唯一索引。

另请参阅分片集合和唯一索引

排序规则

If the collection has a default collation, the 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.

无需为没有排序规则的集合指定 collation 选项。如果确实为没有排序规则的集合指定了排序规则选项，则它将不起作用。

写关注

mongos uses "majority" for the write concern of the shardCollection command and its helper sh.shardCollection().

例子

以下操作为 records 数据库中的 people 集合启用分片并使用 zipcode 字段作为分片键：

db.adminCommand( { shardCollection: "records.people", key: { zipcode: 1 } } )

提示