Manage Shard Zones

In sharded clusters, you can create zones that represent a group of shards andassociate one or more ranges of shard key values to that zone. MongoDBroutes reads and writes that fall into a zone range only to those shardsinside of the zone.

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.

Add Shards to a Zone

Associate a Zone with a particular shard using thesh.addShardToZone() method when connected to a mongosinstance. A single shard may have multiple zones, and multiple shardsmay also have the same zone.

Example

The following example adds the zone NYC to two shards, and the zonesSFO and NRT to a third shard:

  1. sh.addShardToZone("shard0000", "NYC")
  2. sh.addShardToZone("shard0001", "NYC")
  3. sh.addShardToZone("shard0002", "SFO")
  4. sh.addShardToZone("shard0002", "NRT")

You may remove zone from a particular shard using thesh.removeShardFromZone() method when connected to amongos instance, as in the following example, which removesthe NRT zone from a shard:

  1. sh.removeShardFromZone("shard0002", "NRT")

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 keyrange 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 NYC zone
  • one range of zip codes in San Francisco the SFO zone
  1. sh.updateZoneKeyRange("records.users", { zipcode: "10001" }, { zipcode: "10281" }, "NYC")
  2. sh.updateZoneKeyRange("records.users", { zipcode: "11201" }, { zipcode: "11240" }, "NYC")
  3. sh.updateZoneKeyRange("records.users", { zipcode: "94102" }, { zipcode: "94135" }, "SFO")

Note

  • Zone ranges are always inclusive of the lower boundary and exclusiveof the upper boundary.
  • Starting in MongoDB 4.0.2, dropping a collection deletes itsassociated zone/tag ranges.

Remove a Zone Range

New in version 3.4: Use the shell helper method sh.removeRangeFromZone() toremove a range from a zone.

Example

The following example removes the NYC zone assignment for therange of zip codes within Manhattan:

  1. sh.removeRangeFromZone("records.user", {zipcode: "10001"}, {zipcode: "10281"})

Note

Starting in MongoDB 4.0.2, dropping a collection deletes itsassociated zone/tag ranges.

View Existing Zones

Use sh.status() to list the zones associated to each shard in thecluster. You can also view a shards zones by querying theshards collection in the config database.

The following example uses the find() method toreturn all shards with the NYC zone.

  1. use config
  2. db.shards.find({ tags: "NYC" })

You can find zone ranges for all namespaces in thetags collection of the config database. The outputof sh.status() also displays all zone ranges.

The following example uses the find() method toreturn any range associated to the NYC zone.

  1. use config
  2. db.tags.find({ tag: "NYC" })