updateZoneKeyRange (database command数据库命令)

Definition定义

updateZoneKeyRange

The updateZoneKeyRange administrative command can either create or remove the association between a range of shard key values and a zone.updateZoneKeyRange管理命令可以创建或删除分片键值范围与区域之间的关联。

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

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

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.如果不需要便利性或需要额外的返回字段，请使用数据库命令。

To run updateZoneKeyRange, use the db.runCommand( { <command> } ) method.要运行updateZoneKeyRange，请使用db.runCommand( { <command> } )方法。

You must run addShardToZone on the admin database.您必须在管理数据库上运行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(
   {
     updateZoneKeyRange: <string>,
     min: <document>,
     max: <document>,
     zone: <string> | <null>
   }
)

Command Fields命令字段

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

Behavior行为

If no zone range matches the minimum and maximum bounds passed to updateZoneKeyRange, nothing is removed.如果没有区域范围与传递给updateZoneKeyRange的最小和最大边界匹配，则不会删除任何内容。

Only issue updateZoneKeyRange when connected to a mongos instance.仅在连接到mongos实例时发出updateZoneKeyRange。

mongosh provides two helper methods:提供了两种辅助方法：

• sh.updateZoneKeyRange() for adding a range of shard key values to a zone.用于向区域添加一系列分片键值。
• sh.removeRangeFromZone() for removing a range of shard key values from a zone.用于从区域中删除一系列分片键值。

You cannot create a range of shard key values whose lower and upper boundaries overlap with an existing range for the sharded collection. 您不能创建其下限和上限与分片集合的现有范围重叠的分片键值范围。For example, given an existing range of 1 to 10, you cannot create a new range of 5 to 20, as the new range would overlap with the existing range.例如，给定1到10的现有范围，您无法创建5到20的新范围，因为新范围将与现有范围重叠。

A zone can have multiple ranges of data associated with it, but a range can at most be associated with a single zone.一个区域可以有多个与之关联的数据范围，但一个范围最多只能与一个区域关联。

When removing the association between a range and a zone, updateZoneKeyRange does not remove the zone. 删除区域和区域之间的关联时，updateZoneKeyRange不会删除区域。Use the removeShardFromZone command to remove the association between a zone and a shard.使用removeShardFromZone命令删除区域和分片之间的关联。

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

Security安全

For sharded clusters running with authentication, you must authenticate as either:对于使用身份验证运行的分片集群，您必须以以下方式之一进行身份验证：

• a user whose privileges include the specified actions on various collections in the config database:权限包括对config数据库中的各种集合执行指定操作的用户：

  • find on the config.shards collection在config.shards集合中find
  • find, update, and remove on the config.tags collection;在config.tags集合上find、update和remove；

  or, alternatively,或者，

• a user whose privileges include enableSharding on the cluster resource.其权限包括在集群资源上enableSharding（启用分片）的用户。

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

Example示例

Given a sharded collection exampledb.collection with a shard key of { a : 1 }, the following operation creates a range with a lower bound of 1 and an upper bound of 10 on the alpha zone:给定一个分片集合exampledb.collection，其分片键为{ a : 1 }，以下操作在alpha区域创建一个下限为1、上限为10的范围：

admin = db.getSiblingDB("admin")
admin.runCommand(
   {
      updateZoneKeyRange : "exampledb.collection",
      min : { a : 1 },
      max : { a : 10 },
      zone : "alpha"
   }
)

The following operation removes the previously created range by passing null to the zone field.以下操作通过向zone字段传递null来删除之前创建的范围。

admin = db.getSiblingDB("admin")
admin.runCommand(
   {
      updateZoneKeyRange : "exampledb.collection",
      min : { a : 1 },
      max : { a : 10 },
      zone : null
   }
)

The min and max must match exactly the bounds of the target range. The following operation attempts to remove the previously created range, but specifies { a : 0 } as the min bound:min和max必须与目标范围的边界完全匹配。以下操作尝试删除以前创建的范围，但将{ a : 0 }指定为min界限：

admin = db.getSiblingDB("admin")
admin.runCommand(
   {
      updateZoneKeyRange : "exampledb.collection",
      min : { a : 0 },
      max : { a : 10 },
      zone : null
   }
)

While the range of { a : 0 } and { a : 10 } encompasses the existing range, it is not an exact match and therefore updateZoneKeyRange does not remove anything.虽然{ a : 0 }和{ a : 10 }的范围包含现有范围，但它不是完全匹配的，因此updateZoneKeyRange不会删除任何内容。

admin = db.getSiblingDB("admin")
admin.runCommand(
   {
      updateZoneKeyRange : "exampledb.collection",
      min : { a : 1, b : 1 },
      max : { a : 10, b : 10 },
      zone : "alpha"

   }
)