Fix This Page
Navigation

sh.addTagRange()

On this page

Definition

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. 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.

Behavior

Bounds

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

Dropped Collections

If you add a tag range to a collection using sh.addTagRange() and then later drop the collection or its database, MongoDB does not remove the tag association. If you later create a new collection with the same name, the old tag association will apply to the new collection.

Example

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"
              )