Manage Shard Zones¶
In sharded clusters, you can create zones that represent a group of shards and associate one or more ranges of shard key values to that zone. MongoDB routes reads and writes that fall into a zone range only to those shards inside of the zone.
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.
Add Shards to a Zone¶
Associate a Zone with a particular shard using the
sh.addShardToZone() method when connected to a mongos
instance. A single shard may have multiple zones, and multiple shards
may also have the same zone.
Example
The following example adds the zone NYC to two shards, and the zones
SFO and NRT to a third shard:
You may remove zone from a particular shard using the
sh.removeShardFromZone() method when connected to a
mongos instance, as in the following example, which removes
the NRT zone from a shard:
Create a Zone Range¶
To define the zone’s range of shard keys, use the sh.updateZoneKeyRange()
method when connected to a mongos instance. Any given shard key
range may only have one assigned zone. You cannot overlap defined ranges.
Example
Given a collection named users in the records database,
sharded by the zipcode field. The following operations assign:
- two ranges of zip codes in Manhattan and Brooklyn the
NYCzone - one range of zip codes in San Francisco the
SFOzone
Note
- Zone ranges are always inclusive of the lower boundary and exclusive of the upper boundary.
- Starting in MongoDB 4.0.2, dropping a collection deletes its associated zone/tag ranges.
Remove a Zone Range¶
New in version 3.4: Use the shell helper method sh.removeRangeFromZone() to
remove a range from a zone.
Example
The following example removes the NYC zone assignment for the
range of zip codes within Manhattan:
Note
Starting in MongoDB 4.0.2, dropping a collection deletes its associated zone/tag ranges.
View Existing Zones¶
Use sh.status() to list the zones associated to each shard in the
cluster. You can also view a shards zones by querying the
shards collection in the config database.
The following example uses the find() method to
return all shards with the NYC zone.
You can find zone ranges for all namespaces in the
tags collection of the config database. The output
of sh.status() also displays all zone ranges.
The following example uses the find() method to
return any range associated to the NYC zone.