shardCollection

在此页面上

定义

兼容性
语法
命令字段
Considerations
例子

定义

shardCollection: 对集合进行分片以跨分片分发其文档。 shardCollection命令必须针对admin数据库运行。
注意
在 6.0 版本中进行了更改。
从 MongoDB 6.0 开始，对集合进行分片无需首先运行 enableSharding 命令来配置数据库。
提示
在 mongosh 中，该命令也可通过 sh.shardCollection() 辅助方法运行。
辅助方法对 mongosh 用户来说很方便，但它们返回的信息级别可能与数据库命令不同。如果不追求方便或需要额外的返回字段，请使用数据库命令。

兼容性

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

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

重要

无服务器实例不支持此命令。有关更多信息，请参阅不支持的命令。

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

语法

要运行 shardCollection，请使用 db.runCommand( { <command> } ) 方法。

该命令采用以下形式：

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

命令字段

该命令接受以下字段：

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

时间序列选项

5.1 版本中的新功能。

要创建已分片的新时间序列集合，请将 timeseries 选项指定为 shardCollection。

timeseries 选项包含以下字段：

字段	类型	说明
`timeField`	字符串	必需。包含每个时间序列文档中日期的字段的名称。时间序列集合中的文档必须具有有效 BSON 日期，以作为 `timeField` 的值。从MongoDB 8.0开始，不推荐使用`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 是单调增加的，因此，可能导致所有写入都出现在集群中的单个数据段上。理想情况下，数据均匀分布在数据段之间。

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

从MongoDB 8.0开始，不推荐使用timeField作为时间序列集合中的分分片键。

哈希分片键

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

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

注意

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

提示

另请参阅：

哈希分片

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

分片集合操作（即shardCollection 命令和 sh.shardCollection() 辅助程序）可以对空集合或不存在的集合执行初始数据块创建和分发，前提是已为该集合定义区域和区域范围）。初始数据块分布允许更快地设置区域分片。在初始分布之后，负载均衡器将照例管理未来的数据块分布。

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

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

区域分片和复合哈希索引

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

如果已为空集合定义区域和区域范围且 presplitHashedZones 为 false，则 numInitialChunks 选项无效。

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

提示

另请参阅：

唯一性

如果指定 unique: true：

如果集合为空，shardCollection 将在分片键上创建唯一索引（如果这样的索引尚不存在）。
如果集合不为空，则必须先创建索引，然后才能使用 shardCollection。

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

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

排序规则

如果集合有默认排序规则，则 shardCollection 命令必须包含值为 { locale: "simple" } 的 collation 参数。对于具有默认排序规则的非空集合，您必须至少拥有一个具有简单排序规则且其字段支持分片键模式的索引。

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

写关注

mongos使用"majority" 作为命令、其助手shardCollectionsh.shardCollection() 和方法的写关注（write sh.shardAndDistributeCollection() concern）。

例子

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

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

提示

另请参阅：

后退

setAllowMigrations

来年

shardingState