updateZoneKeyRange

Definition定义

updateZoneKeyRange

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

Starting in MongoDB 4.0.2, you can run updateZoneKeyRange database command and its helpers sh.updateZoneKeyRange() and sh.addTagRange() on an unsharded collection or a non-existing collection.从MongoDB 4.0.2开始，您可以在未分级集合或不存在的集合上运行updateZoneKeyRange数据库命令及其助手sh.updateZoneKeyRange()和sh.addTagRange()。

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

You must run addShardToZone on the admin database.您必须在管理数据库上运行addShardToZone。

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

{
  updateZoneKeyRange: <string>,
  min: <document>,
  max: <document>,
  zone: <string> | <null>
}

The command takes the following fields:该命令接受以下字段：

Parameter参数	Type类型	Description描述
updateZoneKeyRange	string	The namespace of the collection to associate with the range.要与范围关联的集合的命名空间。 The collection must be sharded for the command to succeed.必须对集合进行分片化，命令才能成功。
min	document	The inclusive lower bound of the range of shard key values.分片键值范围的包含下限。 Specify each field of the shard key in the form of <fieldname> : <value>. 以<fieldname> : <value>的形式指定分片键的每个字段。The value must be of the same BSON type or types as the shard key.该值必须与分片键具有相同的BSON类型。 Note注意 To use hashed sharding, the field value needs to be of type NumberLong.要使用哈希分片，字段值需要为NumberLong类型。
max	document	The exclusive upper bound of the range of shard key values.分片键值范围的独占上限。 Specify each field of the shard key in the form of <fieldname> : <value>. 以<fieldname> : <value>的形式指定分片键的每个字段。The value must be of the same BSON type or types as the shard key.该值必须与分片键具有相同的BSON类型。 Note注意 To use hashed sharding, the field value needs to be of type NumberLong.要使用哈希分片，字段值需要为NumberLong类型。
zone	string	The name of the zone to associate with the range bounded by the min and max.要与由min和max限定的范围关联的分区的名称。 If the value does not match an existing zone, the command fails.如果该值与现有分区不匹配，则命令将失败。 Specify null to remove the association between the range with lower bounds of min and upper bound of max and the updateZoneKeyRange collection. 指定null以删除下限为min、上限为max的范围与updateZoneKeyRange集合之间的关联。The values of min and max must match exactly the target range.min和max必须与目标范围完全匹配。

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.用于从区域中删除一系列分片键值。

Behavior行为

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 (available starting in version 4.2.2, 4.0.14, 3.6.16).其权限包括在群集资源上enableSharding的用户（从版本4.2.2、4.0.14、3.6.16开始提供）。

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

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:给定一个分片键为{ a : 1 }的分片集合exampledb.collection，以下操作在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.以下操作通过向区域字段传递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. min和max必须与目标范围的边界完全匹配。The following operation attempts to remove the previously created range, but specifies { a : 0 } as the min bound:以下操作尝试删除以前创建的范围，但将{ 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"
   }
)