Database Manual / Reference / Database Commands / Sharding

addShardToZone (database command数据库命令)

Definition定义

addShardToZone

Associates a shard with a zone. MongoDB associates this shard with the given zone. Chunks that are covered by the zone are assigned to shards associated with the zone.将分片与区域关联。MongoDB将此分片与给定区域相关联。被该区域覆盖的块被分配给与该区域关联的分片。

Tip

In mongosh, this command can also be run through the sh.addShardToZone() helper method.在mongosh中，此命令也可以通过sh.addShardToZone()辅助方法运行。

Helper methods are convenient for mongosh users, but they may not return the same level of information as database commands. 助手方法对mongosh用户来说很方便，但它们可能不会返回与数据库命令相同级别的信息。In cases where the convenience is not needed or the additional return fields are required, use the database command.如果不需要便利性或需要额外的返回字段，请使用database命令。

You can only run addShardToZone on the admin database from a mongos instance.您只能从mongos实例在admin数据库上运行addShardToZone。

Compatibility兼容性

This command is available in deployments hosted in the following environments:此命令在以下环境中托管的部署中可用：

  • MongoDB Atlas: The fully managed service for MongoDB deployments in the cloud：云中MongoDB部署的完全托管服务
  • MongoDB Enterprise: The subscription-based, self-managed version of MongoDB：MongoDB的基于订阅的自我管理版本
  • MongoDB Community: The source-available, free-to-use, and self-managed version of MongoDB：MongoDB的源代码可用、免费使用和自我管理版本

Syntax语法

The command has the following syntax:该命令具有以下语法：

db.adminCommand(
   {
     addShardToZone: <string>,
     zone: <string>
   }
)

Command Fields命令字段

The command takes the following fields:该命令包含以下字段：

Field字段Type类型Description描述
addShardtoZonestring字符串

The name of the shard to associate with the zone.与区域关联的分片的名称。

zonestring字符串

The name of the zone to associate with the shard.与分片关联的区域的名称。

mongosh provides the helper method sh.addShardToZone().提供了辅助方法sh.addShardToZone()。

Behavior行为

You can associate a zone with multiple shards, and a shard can associate with multiple zones.您可以将一个区域与多个分片相关联，一个分片也可以与多个区域相关联。

See the zone manual page for more information on zones in a sharded cluster.有关分片集群中区域的更多信息，请参阅区域手册页面。

Ranges范围

MongoDB effectively ignores zones that do not have at least one range of shard key values associated with it.MongoDB有效地忽略了没有至少一个与之关联的分片键值范围的区域。

To associate a range of shard key values with a zone, use the updateZoneKeyRange database command, or the sh.updateZoneKeyRange() shell helper.要将一系列分片键值与区域相关联，请使用updateZoneKeyRange数据库命令或sh.updateZoneKeyRange()shell帮助程序。

You can run updateZoneKeyRange database command and its helpers sh.updateZoneKeyRange() and sh.addTagRange() on an unsharded collection or a non-existing collection.您可以在未记录的集合或不存在的集合上运行updateZoneKeyRange数据库命令及其助手sh.updateZoneKeyRange()和sh.addTagRange()。

Tip

By defining the zones and the zone ranges before sharding an empty or a non-existing collection, the shard collection operation creates chunks for the defined zone ranges as well as any additional chunks to cover the entire range of the shard key values and performs an initial chunk distribution based on the zone ranges. 通过在对空的或不存在的集合进行分片之前定义区域和区域范围，分片集合操作为定义的区域范围创建块以及任何其他块，以覆盖分片键值的整个范围，并根据区域范围执行初始块分布。This initial creation and distribution of chunks allows for faster setup of zoned sharding. After the initial distribution, the balancer manages the chunk distribution going forward.这种块的初始创建和分发允许更快地设置分区分片。在初始分发之后，平衡器管理接下来的块分发。

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

Security安全

For sharded clusters that enforce access control, you must authenticate as a user whose privileges include either:对于实施访问控制的分片集群，您必须以用户身份进行身份验证，其权限包括：

The clusterAdmin or clusterManager built-in roles have the appropriate permissions for issuing addShardToZone. See the documentation page for Role-Based Access Control for more information.clusterAdmin或clusterManager内置角色具有发布addShardToZone的适当权限。有关更多信息，请参阅基于角色的访问控制的文档页面。

Example示例

The following example associates shard0000 with zone JFK:以下示例将shard0000与JFK区域相关联：

db.adminCommand( { addShardToZone : "shard0000" , zone : "JFK" } )

A shard can associate with multiple zones. The following example associates LGA to shard0000:一个分片可以与多个区域关联。以下示例将LGA与shard0000关联：

db.adminCommand( { addShardToZone : "shard0000" , zone : "LGA" } )

shard0000 associates with both the LGA zone and the JFK zone. In a balanced cluster, MongoDB routes reads and writes covered by either zone to shard0000.shard0000与LGA区和JFK区都有关联。在平衡集群中，MongoDB将任一区域覆盖的读写路由到shard0000。