sh.updateZoneKeyRange()

Definition

  • sh.updateZoneKeyRange(namespace, minimum, maximum, zone)

New in version 3.4.

Associates a range of shard key values with a zone.

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.

sh.updateZoneKeyRange() takes the following arguments:

ParameterTypeDescriptionnamespacestringThe namespace of the sharded collection associate with the zone.

The collection must be sharded for the operation to succeed.minimumdocumentThe 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.maximumdocumentThe 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 of shard key values boundedby minimum and maximum.

Only issue sh.updateZoneKeyRange() when connected to amongos instance.

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.

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 associating a range to a zone, the balancer must first run in order to migrate any chunkswhose ranges are covered by the zone to shards inside of that zone. Untilbalancing completes, some chunks may reside on the wrong shard given theconfigured zones for the sharded cluster. See Balancerfor more information.

See the sharded cluster balancer manual page formore information on how migrations work in a sharded cluster.

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

The clusterAdmin or clusterManager built-in roles havethe appropriate permissions for issuing sh.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. sh.updateZoneKeyRange(
  2.    "exampledb.collection",
  3.    { a : 1 },
  4.    { a : 10 },
  5.    "alpha"
  6. )

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

  1. sh.updateZoneKeyRange(
  2.    "exampledb.collection",
  3.    { a : 1 },
  4.    { a : 10 },
  5.    null
  6. )

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. sh.updateZoneKeyRange(
  2.    "exampledb.collection",
  3.    { a : 0 },
  4.    { a : 10 },
  5.    null
  6. )

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} and associates itwith the alpha zone:

  1. sh.updateZoneKeyRange(
  2.    "exampledb.collection",
  3.    { a : 1, b : 1 },
  4.    { a : 10, b : 10 },
  5.    "alpha"
  6. )

If you wanted to create a range on values of b only, you must specifythe entire range of a when creating ranges. For example, the followingoperations create two ranges on b and associates them to thebeta zone.

Note

The previously defined range conflicts with the ranges defined in thisexample. Issue the sh.removeRangeFromZone() operation to remove anexisting conflicting range.

  1. sh.updateZoneKeyRange(
  2.    "exampledb.collection",
  3.    { a : MinKey, b : 1 },
  4.    { a : MaxKey, b: 10 },
  5.    "alpha"
  6. );
  7.  
  8. sh.updateZoneKeyRange(
  9.    "exampledb.collection",
  10.    { a : MinKey, b : 10 },
  11.    { a : MaxKey, b: 20 },
  12.    "beta"
  13. );

MinKey always compares as lower than every other possible value,while MaxKey always compares as higher than every other possiblevalue. Using these special values for the lower and upper bounds of the rangecaptures the entire possible value space of a.

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

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.

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.

First, use sh.addShardToZone() to create the zones:

  1. sh.addShardToZone("shardA", "DC1")
  2. sh.addShardToZone("shardB", "DC2")

Then, use sh.updateZoneKeyRange() to create the ranges:

  1. sh.updateZoneKeyRange(
  2.    "exampledb.contacts",
  3.    { zip: 10001 },
  4.    { zip: 10090 },
  5.    "DC1"
  6. );
  7.  
  8. sh.updateZoneKeyRange(
  9.    "exampledb.contacts",
  10.    { zip: 90001 },
  11.    { zip: 96054 },
  12.    "DC2"
  13. );

If you haven’t enabled sharding for exampledb, usesh.enableSharding() to enable sharding for the database:

  1. sh.enableSharding("exampledb");

Finally, use sh.shardCollection() to shard the collection contacts:

Note

If the collection does not exist, the sharding operation creates the collection.

  1. sh.shardCollection("exampledb.contacts",  { zip: 1 } );

To see the created chunks and distribution, run thesh.status() operation:

  1. sh.status()

The method returns:

  1. --- Sharding Status ---
  2.   sharding version: {
  3.      "_id" : 1,
  4.      "minCompatibleVersion" : 5,
  5.      "currentVersion" : 6,
  6.      "clusterId" : ObjectId("5b80c06d35a961fd0ae1986d")
  7.   }
  8.   shards:
  9.         {  "_id" : "shardA",  "host" : "shardA/mongodb0.example.net:27018,mongodb1.example.net:27018,mongodb2.example.net:27018",  "state" : 1,  "tags" : [ "DC1" ] }
  10.         {  "_id" : "shardB",  "host" : "shardB/mongodb3.example.net:27018,mongodb4.example.net:27018,mongodb5.example.net:27018",  "state" : 1,  "tags" : [ "DC2" ] }
  11.   active mongoses:
  12.         "4.2.0" : 2
  13.   autosplit:
  14.         Currently enabled: yes
  15.   balancer:
  16.         Currently enabled:  yes
  17.         Currently running:  no
  18.         Failed balancer rounds in last 5 attempts:  0
  19.         Migration Results for the last 24 hours:
  20.                 No recent migrations
  21.   databases:
  22.         {  "_id" : "config",  "primary" : "config",  "partitioned" : true }
  23.         {  "_id" : "exampledb",  "primary" : "shardA",  "partitioned" : true,  "version" : {  "uuid" : UUID("6c351bcf-acd2-4fd9-82d8-9f6bd7321558"),  "lastMod" : 1 } }
  24.                 exampledb.contacts
  25.                         shard key: { "zip" : 1 }
  26.                         unique: false
  27.                         balancing: true
  28.                         chunks:
  29.                                 shardA   3
  30.                                 shardB   2
  31.                         { "zip" : { "$minKey" : 1 } } -->> { "zip" : 10001 } on : shardA Timestamp(1, 0)
  32.                         { "zip" : 10001 } -->> { "zip" : 10090 } on : shardA Timestamp(1, 1)
  33.                         { "zip" : 10090 } -->> { "zip" : 90001 } on : shardB Timestamp(1, 2)
  34.                         { "zip" : 90001 } -->> { "zip" : 96054 } on : shardB Timestamp(1, 3)
  35.                         { "zip" : 96054 } -->> { "zip" : { "$maxKey" : 1 } } on : shardA Timestamp(1, 4)
  36.                          tag: DC1  { "zip" : 10001 } -->> { "zip" : 10090 }
  37.                          tag: DC2  { "zip" : 90001 } -->> { "zip" : 96054 }

For the collection, sharding operation created 5 chunks (two chunksthat correspond to the zone ranges and the other three to cover allother values) across shardA and shardB.

See also

sh.addShardToZone(), sh.removeRangeFromZone()