sh.shardCollection()（mongosh方法）

定义

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

使用 key 作为分片键以对集合进行分片。分片键决定了 MongoDB 如何在各分片之间分发集合的文档。

注意

在版本6.0中进行了更改。

从 MongoDB 6.0 开始，对集合分片无需首先运行 sh.enableSharding() 方法来配置数据库。

重要

mongosh 方法

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

有关数据库命令，请参阅 shardCollection 命令。

如需了解 MongoDB API 驱动程序，请参阅特定语言的 MongoDB 驱动程序文档。

sh.shardCollection() 采用以下参数：

Parameter	类型	说明
`namespace`	字符串	要分片的集合的命名空间，格式为 `"<database>.<collection>"`。
`key`	文档	指定一个或多个字段用作分片键的文档。 `{ <field1>: <1\|"hashed">, ... }` 将字段值设置为以下任一项： `1` 用于基于范围的分片 `"hashed"` 以指定哈希分片键。分片键必须有索引支持。除非集合为空，否则索引必须在 `shardCollection` 命令之前存在。如果集合为空，并且尚不存在可以支持分片键的索引，MongoDB 会在对集合进行分片之前创建索引。另请参阅分片键索引
`unique`	布尔	可选。指定 `true` 以确保基础索引执行唯一约束。默认为 `false`。使用哈希分片键时，不能指定 `true`。如果指定了 `options` 文件，则必须显式指定 `unique` 的值。
`options`	文档	可选。包含可选字段的文档，包括 `numInitialChunks` 和 `collation`。

options 参数支持以下选项：

Parameter	类型	说明
`numInitialChunks`	整型	可选。指定使用哈希分片键对空集合进行分片时最初创建的最小数据段数。然后，MongoDB 在集群中创建并均衡数据段。`numInitialChunks` 参数必须小于每个分片 `8192` 个数据段。默认为每个分片 `2` 个数据段。如果集合不为空或分片键不包含哈希字段，则操作将返回错误。如果使用 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版本新增。

To create a new time series collection that is sharded, specify the timeseries option to sh.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` 参数。

兼容性

此方法可用于以下环境中托管的部署：

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

重要

M0 和 Flex 集群不支持此命令。有关更多信息，请参阅不支持的命令。

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

Considerations

集合被分片后，MongoDB 就不再提供对分片集合进行取消分片的方法。

分片键

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

时间序列集合上的分片键

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

使用 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, 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().

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

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

排序规则

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.

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

写关注

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

示例

简易用法

假设名为 records 的数据库中有一名为 people 的集合，以下命令将按 zipcode 字段对该集合进行分片：

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

用法以及选项

The phonebook database has a collection contacts with no default collation. The following example uses sh.shardCollection() to shard the phonebook.contacts with:

针对 last_name 字段的哈希分片键、
5 初始数据段以及
simple 的排序规则。

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

提示

后退

sh.shardAndDistributeCollection

来年

sh.splitAt