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

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¶

If you add a zone range to a collection using sh.updateZoneKeyRange() and then later drop the collection or its database, MongoDB does not remove the zone association. If you later create a new collection with the same name, the old zone association applies to the new collection.

Security¶

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

find on the config.shards collection or the config database
find on the config.tags collection or the config database
update on the config.tags collection or the config database

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

If you wanted to create a range on values of b only, you must specify the entire range of a when creating ranges. For example, the following operations create two ranges on b and associates them to the beta zone.

Note

The previously defined range conflicts with the ranges defined in this example. Issue the sh.removeRangeFromZone() operation to remove an existing conflicting range.

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

sh.updateZoneKeyRange(
   "exampledb.collection",
   { a : MinKey, b : 10 },
   { a : MaxKey, b: 20 },
   "beta"
);

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