sh.addShardToZone()
Definition
New in version 3.4: Associates a shard with a zone. MongoDB associates this shardwith the given zone. Chunks that are covered by the zone are assigned toshards associated with the zone.
ParameterTypeDescriptionshard
stringThe name of the shard to which to associate the zone
.zone
stringThe name of the zone to associate with the shard
Only issue sh.addShardToZone()
when connected to amongos
instance.
Behavior
You can associate a zone with multiple shards, and a shard can associate withmultiple zones.
See the zone manual page for more information on zonesin sharded clusters.
Ranges
MongoDB effectively ignores zones that do not have at least one range ofshard key values associated with it.
To associate a range of shard key values with a zone, use thesh.updateZoneKeyRange()
method.
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.
Security
For sharded clusters running with authentication, youmust authenticate as a user whose privileges include update
onthe config.shards
collection or the config
database.
The clusterAdmin
or clusterManager
built-in roles havethe appropriate permissions for issuing sh.addShardToZone()
. See theRole-Based Access Control manual page for moreinformation.
Example
The following example adds three zones, NYC
, LAX
, and NRT
,associating each to a shard:
- sh.addShardToZone("shard0000", "JFK")
- sh.addShardToZone("shard0001", "LAX")
- sh.addShardToZone("shard0002", "NRT")
A shard can associate with multiple zones. The following example associatesLGA
to shard0000
:
- sh.addShardToZone("shard0000", "LGA")
shard0000
associates with both the LGA
zone and the JFK
zone. In abalanced cluster, MongoDB routes reads and writes covered by either zone toshard0000
.
See also