- Reference >
- Database Commands >
- Sharding Commands >
- updateZoneKeyRange
updateZoneKeyRange¶
On this page
Definition¶
-
updateZoneKeyRange
¶ New in version 3.4.
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 helperssh.updateZoneKeyRange()
andsh.addTagRange()
on an unsharded collection or a non-existing collection.To run
updateZoneKeyRange
, use thedb.runCommand( { <command> } )
method.You must run
addShardToZone
on the admin database.The
updateZoneKeyRange
command has the following syntax: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.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.zone
string The name of the zone to associate with the range bounded by the
min
andmax
.If the value does not match an existing zone, the command fails.
Specify
null
to remove the association between the range with lower bounds ofmin
and upper bound ofmax
and theupdateZoneKeyRange
collection. The values ofmin
andmax
must match exactly the target range.If no zone range matches the minimum and maximum bounds passed to
updateZoneKeyRange
, nothing is removed.Only issue
updateZoneKeyRange
when connected to amongos
instance.The
mongo
shell 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.
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.
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¶
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 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¶
Starting in MongoDB 4.0.2, 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.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:
The following operation removes the previously created range by passing
null
to the zone
field.
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:
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: