Tag Aware Sharding

MongoDB supports tagging a range of shard key values to associate that range with a shard or group of shards. Those shards receive all inserts within the tagged range.

The balancer obeys tagged range associations, which enables the following deployment patterns:

  • isolate a specific subset of data on a specific set of shards.
  • ensure that the most relevant data reside on shards that are geographically closest to the application servers.

This document describes the behavior, operation, and use of tag aware sharding in MongoDB deployments.


Behavior and Operations

The balancer migrates chunks of documents in a sharded collections to the shards associated with a tag that has a shard key range with an upper bound greater than the chunk’s lower bound.

During balancing rounds, if the balancer detects that any chunks violate configured tags, the balancer migrates chunks in tagged ranges to shards associated with those tags.

After configuring tags with a shard key range, and associating it with a shard or shards, the cluster may take some time to balance the data among the shards. This depends on the division of chunks and the current distribution of data in the cluster.

Once configured, the balancer respects tag ranges during future balancing rounds.

Chunks that Span Multiple Tag Ranges

A single chunk may contain data with a shard key values that falls into ranges associated with more than one tag. To accommodate these situations, the balancer may migrate chunks to shards that contain shard key values that exceed the upper bound of the selected tag range.


Given a sharded collection with two configured tag ranges:

  • Shard key values between 100 and 200 have tags to direct corresponding chunks to shards tagged NYC.
  • Shard key values between 200 and 300 have tags to direct corresponding chunks to shards tagged SFO.

For this collection cluster, the balancer will migrate a chunk with shard key values ranging between 150 and 220 to a shard tagged NYC, since 150 is closer to 200 than 300.

To ensure that your collection has no potentially ambiguously tagged chunks, create splits on your tag boundaries. You can then manually migrate chunks to the appropriate shards, or wait for the balancer to automatically migrate these chunks.