On this page

• Definition
• Behavior
• Security
• Example

Definition

updateZoneKeyRange

New in version 3.4.

The updateZoneKeyRange administrative command can either create or remove the association between a range of shard key values and a zone.

To run updateZoneKeyRange, use the db.runCommand( { <command> } ) method.

You must run addShardToZone on the admin database.

The updateZoneKeyRange command has the following syntax:

copy

{
  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>. The value must be of the same BSON type or types as the shard key.
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>. The value must be of the same BSON type or types as the shard key.
zone	string	The name of the zone to associate with the range bounded by the min and 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. The values of min and max must match exactly the target range.

If no zone range matches the minimum and maximum bounds passed to updateZoneKeyRange, nothing is removed.

Only issue updateZoneKeyRange when connected to a mongos instance.

The mongo shell 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.

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. Use the removeShardFromZone command to remove the association between a zone and a shard.

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:

  • find on the config.shards collection
  • find, update, and remove on the config.tags collection;

  or, alternatively,

• a user whose privileges include enableSharding on the cluster resource (available starting in version 3.6.16).

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.

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:

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.

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:

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.

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

   }
)