Docs Menu
Docs Home
/
MongoDB Manual
/
Reference
/
Database Commands
/
Sharding Commands

updateZoneKeyRange

On this page

  • Definition
  • Syntax
  • Command Fields
  • Behavior
  • Security
  • Example

Definition

updateZoneKeyRange

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

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.

Tip

In mongosh, this command can also be run through the sh.updateZoneKeyRange() helper method.

Helper methods are convenient for mongosh users, but they may not return the same level of information as database commands. 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.

You must run addShardToZone on the admin database.

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:

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.

Note

To use hashed sharding, the field value needs to be of type 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>. The value must be of the same BSON type or types as the shard key.

Note

To use hashed sharding, the field value needs to be of type NumberLong.

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.

Behavior

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.

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.

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.

Initial Chunk Distribution for Empty or Non-Existing Collections

If you are considering performing zone sharding on an empty or non-existent collection, use updateZoneKeyRange to create the zones and zone ranges before sharding the collection (since 4.0.2). Starting in version 4.0.3, creating zones and zone ranges on empty or non-existing collections allows MongoDB to optimize the initial chunk creation and distribution process when sharding the collection. This optimized process supports faster setup of zoned sharding with less balancer overhead than creating zones after sharding. The balancer performs all chunk management after the optimized initial chunk creation and distribution.

For an example of defining zones and zone ranges for initial chunk distribution, see Pre-Define Zones and Zone Ranges for an Empty or Non-Existing Collection.

Initial Chunk Distribution with Compound Hashed Shard Keys

Starting in version 4.4, MongoDB supports sharding collections on compound hashed indexes. MongoDB can perform optimized initial chunk creation and distribution when sharding the empty or non-existing collection on a compound hashed shard key.

If the hashed field is the prefix of the shard key (i.e. the first field in the shard key), all of the following must be true for MongoDB to perform initial chunk creation and distribution:

If the hashed field is not the prefix of the shard key (i.e. the shard key has one or more non-hashed leading fields), all of the following must be true for MongoDB to perform initial chunk creation and distribution:

  • The collection has one zone range for each combination of distinct prefix field values (i.e. all fields preceding the hashed field).

  • For the lower-bound of each zone range, specify MinKey for the hashed field and all subsequent fields.

  • For each zone range, at least one upper-bound prefix field must differ from its lower-bound counterpart.

  • sh.shardCollection() specifies the presplitHashedZones: true option.

For a more complete example of defining zones and zone ranges for initial chunk distribution on a compound hashed shard key, see Pre-Define Zones and Zone Ranges for an Empty or Non-Existing Collection.

Balancer

After successfully running updateZoneKeyRange, there may be chunk migrations during the next balancer round.

After adding a range to a zone, the balancer must first run in order to migrate any chunks whose ranges are covered by the zone to shards inside of that zone. Until balancing completes, some chunks may reside on the wrong shard given the configured zones for the sharded cluster.

Removing the association between a range and a zone removes the constraints keeping chunks covered by the range on the shards inside that zone. During the next balancer round, the balancer may migrate chunks that were previously covered by the zone.

See the documentation for the sharded cluster balancer for more information on how migrations work in a sharded cluster.

Bounds

Zone ranges are always inclusive of the lower boundary and exclusive of the upper boundary.

Dropped Collections

Dropping a collection deletes its associated zone/tag ranges.

In earlier versions, MongoDB does not remove the tag associations for a dropped collection, and if you later create a new collection with the same name, the old tag associations will apply to the new collection.

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:

    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).

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.

Compound Shard Key

Given a sharded collection exampledb.collection with a shard key of { a : 1, b : 1 }, the following operation creates a range covering the lower bound of { a: 1, b : 1 } and an upper bound of { a : 10, b : 10} and associates it with the alpha zone:

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

Back

unsetSharding