sh.addTagRange()

Definition

• sh.addTagRange(namespace, minimum, maximum, tag)

Changed in version 3.4: This method aliases to sh.updateZoneKeyRange() in MongoDB 3.4. The functionality specifiedbelow 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 thesh.addShardTag() method.

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.

sh.addTagRange() takesthe following arguments:

ParameterTypeDescriptionnamespacestringThe namespace of the sharded collection to tag.minimumdocumentThe minimum value of the shard key range to include in thetag. The minimum is an inclusive match. Specify the minimum value inthe form of <fieldname>:<value>. This value must be of the sameBSON type or types as the shard key.maximumdocumentThe maximum value of the shard key range to include in the tag.The maximum is an exclusive match. Specify the maximum value in theform of <fieldname>:<value>. This value must be of the same BSONtype or types as the shard key.tagstringThe name of the tag to attach the range specified by the minimumand maximum arguments to.

Use sh.addShardTag() to ensure that the balancer migratesdocuments that exist within the specified range to a specific shardor set of shards.

Only issue sh.addTagRange() when connected to amongos instance.

Behavior

Bounds

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

Initial Chunk Distribution

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.

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.

Dropped Collections

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

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

Example

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

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