Zones

In sharded clusters, you can create zones of sharded data basedon the shard key. You can associate each zone with one or more shardsin the cluster. A shard can associate with any number of zones. In a balancedcluster, MongoDB migrates chunks covered by a zone only tothose shards associated with the zone.

Some common deployment patterns where zones can be applied are as follows:

  • Isolate a specific subset of data on a specific set of shards.
  • Ensure that the most relevant data reside on shards that aregeographically closest to the application servers.
  • Route data to shards based on the hardware / performance of theshard hardware.

The following image illustrates a sharded cluster with three shards and twozones. The A zone represents a range with a lower boundary of 1 and anupper bound of 10. The B zone represents a range with a lower boundaryof 10 and an upper boundary of 20. Shards Alpha and Beta havethe A zone. Shard Beta also has the B zone. Shard Charlie hasno zones associated with it. The cluster is in a steady state and no chunksviolate any of the zones.

Diagram of data distribution based on zones in a sharded cluster

Behavior and Operations

Ranges

Each zone covers one or more ranges of shard key values for acollection. Each range a zone covers is always inclusive of its lowerboundary and exclusive of its upper boundary.

Zones cannot share ranges, nor can they have overlapping ranges.

To define ranges, MongoDB provides the updateZoneKeyRangecommand and the associated helper methodssh.updateZoneKeyRange() and sh.addShardTag().

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.

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

Initial Chunk Distribution

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.

Balancer

The balancer attempts to evenly distribute a sharded collection’schunks across all shards in the cluster.

For each chunk marked for migration, the balancer checks eachpossible destination shard for any configured zones. If the chunk range fallsinto a zone, the balancer migrates the chunk into a shard inside thatzone. Chunks that do not fall into a zone can exist on any shard in thecluster and are migrated normally.

During balancing rounds, if the balancer detects that any chunks violate theconfigured zones for a given shard, the balancer migrates those chunks toa shard where no conflict exists.

After associating a zone with a shard or shards and configuring thezone with a shard key range for a sharded collection, the cluster maytake some time to migrate the affected data for the sharded collection.This depends on the division of chunks and the current distribution ofdata in the cluster. When balancing is complete, reads and writes fordocuments in a given zone are routed only to the shard or shards insidethat zone.

Once configured, the balancer respects zones during futurebalancing rounds.

Shard Key

You must use fields contained in the shard key when defining a newrange for a zone to cover. If using a compound shardkey, the range must include the prefix of the shard key.

For example, given a shard key { a : 1, b : 2, c : 3 }, creating orupdating a zone to cover values of b requires including a as theprefix. Creating or updating a zone to covers values of c requiresincluding a and b as the prefix.

You cannot create zones using fields not included in the shard key. Forexample, if you wanted to use zones to partition data based ongeographic location, the shard key would need at least one field thatcontained geographic data.

When choosing a shard key for a collection, consider what fields you mightwant to use for configuring zones. After sharding, you cannot change theshard key. See Choosing a Shard Key for considerationsin choosing a shard key.

Hashed Shard Keys and Zones

When using zones on a hashed shard key, each zone covers the hashed shardkey values. Given a shard key { a : 1 } and a zone alpha with a lowerbound of 1 and an upper bound of 5, the bounds represent the hashed_value of a, and not the actual value. Therefore, there is no guaranteethat MongoDB routes documents where a has a value of 1 to 5 tozone alpha. MongoDB routes any document where the _hashed shard key valuefalls within the range of 1 or 5 to a shard inside zone alpha.

In general, a zone covering a sequential range of hashed shard key values mayexhibit unexpected behavior.

It is possible create a zone which covers the entire range of shard keyvalues using minKey and maxkey to guarantee that MongoDB restricts all thedata for a specific collection to the shard or shards in that zone.

Shard Zone Boundaries

Zone ranges are always inclusive of the lower boundary and exclusiveof the upper boundary.

See also

Manage Shard Zones