Navigation
This version of the documentation is archived and no longer supported.

sh.updateZoneKeyRange()

On this page

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 run updateZoneKeyRange database command and its helpers sh.updateZoneKeyRange() and sh.addTagRange() on an unsharded collection or a non-existing collection.

Important

mongo Shell Method

This page documents a mongo method. This is not the documentation for database commands or language-specific drivers, such as Node.js. To use the database command, see the updateZoneKeyRange command.

For MongoDB API drivers, refer to the language-specific MongoDB driver documentation.

sh.updateZoneKeyRange() takes the following arguments:

Parameter Type Description
namespace string

The namespace of the sharded collection associate with the zone.

The collection must be sharded for the operation to succeed.

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

maximum 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 of shard key values bounded by minimum and maximum.

Only issue sh.updateZoneKeyRange() when connected to a mongos instance.

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.

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

Initial Chunk Distribution

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

Changed in version 4.0.3: By defining the zones and the zone ranges before sharding an empty or a non-existing collection, the shard collection operation creates chunks for the defined zone ranges as well as any additional chunks to cover the entire range of the shard key values and performs an initial chunk distribution based on the zone ranges. This initial creation and distribution of chunks allows for faster setup of zoned sharding. After the initial distribution, the balancer manages the chunk 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 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. See Balancer for more information.

See the sharded cluster balancer manual page 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:

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

    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 sh.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:

sh.updateZoneKeyRange(
   "exampledb.collection",
   { a : 1 },
   { a : 10 },
   "alpha"
)

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

sh.updateZoneKeyRange(
   "exampledb.collection",
   { a : 1 },
   { a : 10 },
   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:

sh.updateZoneKeyRange(
   "exampledb.collection",
   { a : 0 },
   { a : 10 },
   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:

sh.updateZoneKeyRange(
   "exampledb.collection",
   { a : 1, b : 1 },
   { a : 10, b : 10 },
   "alpha"
)

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

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.

By defining the zones and the zone ranges before sharding an empty or a non-existing collection, the shard collection operation creates chunks for the defined zone ranges as well as any additional chunks to cover the entire range of the shard key values and performs an initial chunk distribution based on the zone ranges. This initial creation and distribution of chunks allows for faster setup of zoned sharding. After the initial distribution, the balancer manages the chunk distribution going forward.

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

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

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

sh.updateZoneKeyRange(
   "exampledb.contacts",
   { zip: 10001 },
   { zip: 10090 },
   "DC1"
);

sh.updateZoneKeyRange(
   "exampledb.contacts",
   { zip: 90001 },
   { zip: 96054 },
   "DC2"
);

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

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.

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

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

sh.status()

The method returns:

--- Sharding Status ---
  sharding version: {
     "_id" : 1,
     "minCompatibleVersion" : 5,
     "currentVersion" : 6,
     "clusterId" : ObjectId("5b80c06d35a961fd0ae1986d")
  }
  shards:
        {  "_id" : "shardA",  "host" : "shardA/mongodb0.example.net:27018,mongodb1.example.net:27018,mongodb2.example.net:27018",  "state" : 1,  "tags" : [ "DC1" ] }
        {  "_id" : "shardB",  "host" : "shardB/mongodb3.example.net:27018,mongodb4.example.net:27018,mongodb5.example.net:27018",  "state" : 1,  "tags" : [ "DC2" ] }
  active mongoses:
        "4.2.0" : 2
  autosplit:
        Currently enabled: yes
  balancer:
        Currently enabled:  yes
        Currently running:  no
        Failed balancer rounds in last 5 attempts:  0
        Migration Results for the last 24 hours:
                No recent migrations
  databases:
        {  "_id" : "config",  "primary" : "config",  "partitioned" : true }
        {  "_id" : "exampledb",  "primary" : "shardA",  "partitioned" : true,  "version" : {  "uuid" : UUID("6c351bcf-acd2-4fd9-82d8-9f6bd7321558"),  "lastMod" : 1 } }
                exampledb.contacts
                        shard key: { "zip" : 1 }
                        unique: false
                        balancing: true
                        chunks:
                                shardA   3
                                shardB   2
                        { "zip" : { "$minKey" : 1 } } -->> { "zip" : 10001 } on : shardA Timestamp(1, 0)
                        { "zip" : 10001 } -->> { "zip" : 10090 } on : shardA Timestamp(1, 1)
                        { "zip" : 10090 } -->> { "zip" : 90001 } on : shardB Timestamp(1, 2)
                        { "zip" : 90001 } -->> { "zip" : 96054 } on : shardB Timestamp(1, 3)
                        { "zip" : 96054 } -->> { "zip" : { "$maxKey" : 1 } } on : shardA Timestamp(1, 4)
                         tag: DC1  { "zip" : 10001 } -->> { "zip" : 10090 }
                         tag: DC2  { "zip" : 90001 } -->> { "zip" : 96054 }

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