updateZoneKeyRange

Definition

  • updateZoneKeyRange

New in version 3.4.

The updateZoneKeyRange administrative command can eithercreate or remove the association between a range of shard key values and azone.

Starting in MongoDB 4.0.2, you can runupdateZoneKeyRange database command and its helperssh.updateZoneKeyRange() and sh.addTagRange() onan unsharded collection or a non-existing collection.

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

You must run addShardToZone on the admin database.

The updateZoneKeyRange command has the following syntax:

  1. {
  2.   updateZoneKeyRange: <string>,
  3.   min: <document>,
  4.   max: <document>
  5.   zone: <string> | <null>
  6. }

The command takes the following fields:

ParameterTypeDescriptionupdateZoneKeyRangestringThe namespace of the collection to associate with the range.

The collection must be sharded for the command to succeed.mindocumentThe 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.maxdocumentThe 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.zonestringThe name of the zone to associate with the range bounded by themin and max.

If the value does not match an existing zone, the command fails.

Specify null to remove the association between the range with lowerbounds of min and upper bound of max and the updateZoneKeyRangecollection. The values of min and max must match exactly the targetrange.

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

Only issue updateZoneKeyRange when connected to amongos instance.

The mongo shell provides two helper methods:

Behavior

You cannot create a range of shard key values whose lower and upper boundariesoverlap with an existing range for the sharded collection. For example, givenan existing range of 1 to 10, you cannot create a new range of 5to 20, as the new range would overlap with the existing range.

A zone can have multiple ranges of data associated with it, but a rangecan 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 theremoveShardFromZone command to remove the association between azone and a shard.

See the zone manual page for more information on zonesin sharded clusters.

Initial Chunk Distribution

Starting in MongoDB 4.0.2, you can runupdateZoneKeyRange database command and its helperssh.updateZoneKeyRange() and sh.addTagRange() onan unsharded collection or a non-existing collection.

Tip

Changed in version 4.0.3: By defining the zones and the zone ranges before sharding an emptyor a non-existing collection, the shard collection operation createschunks for the defined zone ranges as well as any additional chunksto cover the entire range of the shard key values and performs aninitial chunk distribution based on the zone ranges. This initialcreation and distribution of chunks allows for faster setup of zonedsharding. After the initial distribution, the balancer manages thechunk distribution going forward.

See Pre-Define Zones and Zone Ranges for an Empty or Non-Existing Collection for an example.

Balancer

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

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

Removing the association between a range and a zone removes the constraintskeeping chunks covered by the range on the shards inside that zone. During thenext balancer round, the balancer may migrate chunks that were previouslycovered by the zone.

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

Bounds

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

Dropped Collections

Starting in MongoDB 4.0.2, dropping a collection deletes itsassociated zone/tag ranges.

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

Security

For sharded clusters running with authentication, youmust authenticate as a user whose privileges include:

  • find on the config.shards collection or the configdatabase
  • find on the config.tags collection or the configdatabase
  • update on the config.tags collection or the configdatabase
  • remove on the config.tags collection or the configdatabase

The clusterAdmin or clusterManager built-in roles havethe appropriate permissions for issuing updateZoneKeyRange. Seethe documentation page for Role-Based Access Controlfor 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 1and an upper bound of 10 on the alpha zone:

  1. admin = db.getSiblingDB("admin")
  2. admin.runCommand(
  3.    {
  4.       updateZoneKeyRange : "exampledb.collection",
  5.       min : { a : 1 },
  6.       max : { a : 10 },
  7.       zone : "alpha"
  8.    }
  9. )

The following operation removes the previously created range by passingnull to the zone field.

  1. admin = db.getSiblingDB("admin")
  2. admin.runCommand(
  3.    {
  4.       updateZoneKeyRange : "exampledb.collection",
  5.       min : { a : 1 },
  6.       max : { a : 10 },
  7.       zone : null
  8.    }
  9. )

The min and max must match exactly the bounds of the target range.The following operation attempts to remove the previously created range, butspecifies { a : 0 } as the min bound:

  1. admin = db.getSiblingDB("admin")
  2. admin.runCommand(
  3.    {
  4.       updateZoneKeyRange : "exampledb.collection",
  5.       min : { a : 0 },
  6.       max : { a : 10 },
  7.       zone : null
  8.    }
  9. )

While the range of { a : 0 } and { a : 10 } encompasses the existingrange, it is not an exact match and therefore updateZoneKeyRangedoes 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 lowerbound of { a: 1, b : 1 } and an upper bound of { a : 10, b : 10} andassociates it with the alpha zone:

  1. admin = db.getSiblingDB("admin")
  2. admin.runCommand(
  3.    {
  4.       updateZoneKeyRange : "exampledb.collection",
  5.       min : { a : 1, b : 1 },
  6.       max : { a : 10, b : 10 },
  7.       zone : "alpha"
  8.  
  9.    }
  10. )