Docs Menu

Docs HomeDevelop ApplicationsMongoDB Manual

sh.addTagRange()

On this page

  • Definition
  • Behavior
  • Example
sh.addTagRange(namespace, minimum, maximum, tag)

Changed in version 3.4: This method aliases to sh.updateZoneKeyRange() in MongoDB 3.4. The functionality specified below still applies to MongoDB 3.2. MongoDB 3.4 provides Zone sharding as the successor to tag-aware sharding.

Attaches a range of shard key values to a shard tag created using the sh.addShardTag() method.

Starting in MongoDB 4.0.2, you can run updateZoneKeyRange database command and its helpers sh.updateZoneKeyRange() and sh.addTagRange() on an unsharded collection or a non-existing collection.

sh.addTagRange() takes the following arguments:

Parameter
Type
Description
namespace
string
The namespace of the sharded collection to tag.
minimum
document
The minimum value of the shard key range to include in the tag. The minimum is an inclusive match. Specify the minimum value in the form of <fieldname>:<value>. This value must be of the same BSON type or types as the shard key.
maximum
document
The maximum value of the shard key range to include in the tag. The maximum is an exclusive match. Specify the maximum value in the form of <fieldname>:<value>. This value must be of the same BSON type or types as the shard key.
tag
string
The name of the tag to attach the range specified by the minimum and maximum arguments to.

Use sh.addShardTag() to ensure that the balancer migrates documents that exist within the specified range to a specific shard or set of shards.

Only issue sh.addTagRange() when connected to a mongos instance.

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

If you are considering performing zone sharding on an empty or non-existent collection, use sh.addTagRange() to create the zones and zone ranges before sharding the collection. Starting in version 4.0.3, creating zones and zone ranges on empty or non-existing collections allows MongoDB to optimize the initial chunk creation and distribution process when sharding the collection. This optimized process supports faster setup of zoned sharding with less balancer overhead than creating zones after sharding. The balancer performs all chunk management after the optimized initial chunk creation and distribution.

For an example of defining zones and zone ranges for initial chunk distribution, see Pre-Define Zones and Zone Ranges for an Empty or Non-Existing Collection.

MongoDB supports sharding collections on compound hashed indexes. MongoDB can perform optimized initial chunk creation and distribution when sharding the empty or non-existing collection on a compound hashed shard key.

For a more complete example of defining zones and zone ranges for initial chunk distribution on a compound hashed shard key, see Pre-Define Zones and Zone Ranges for an Empty or Non-Existing Collection.

Dropping a collection deletes its associated zone/tag ranges.

In earlier versions, MongoDB does not remove the tag associations for a dropped collection, and if you later create a new collection with the same name, the old tag associations will apply to the new collection.

Given a shard key of {state: 1, zip: 1}, the following operation creates a tag range covering zip codes in New York State:

sh.addTagRange( "exampledb.collection",
{ state: "NY", zip: MinKey },
{ state: "NY", zip: MaxKey },
"NY"
)
←  sh.addShardToZone()sh.balancerCollectionStatus() →