Navigation

sh.removeRangeFromZone()

On this page

Definition

sh.removeRangeFromZone(namespace, minimum, maximum)

New in version 3.4.

Removes the association between a range of shard key values and a zone.

sh.removeRangeFromZone() takes the following arguments:

Parameter Type Description
namespace string

The namespace of the sharded collection to associate with the zone.

The collection must be sharded for the operation to succeed.

minimum document

The inclusive lower bound of the range of shard key values.

Specify each field of the shard key in the form of <fieldname> : <value>. The value must be of the same BSON type or types as the shard key.

maximum document

The exclusive upper bound of the range of shard key values.

Specify each field of the shard key in the form of <fieldname> : <value>. The value must be of the same BSON type or types as the shard key.

Use sh.removeRangeFromZone() to remove the association between unused, out of date, or conflicting ranges and a zone.

If no range matches the minimum and maximum bounds passed to removeShardFromZone(), nothing is removed.

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

Behavior

sh.removeShardFromZone() does not remove the zone associated to the specified range.

See the zone manual page for more information on zones in sharded clusters.

Balancer

Removing the association between a range and a zone removes the constraints keeping chunks covered by the range on the shards inside that zone. During the next balancer round, the balancer may migrate chunks that were previously covered by the zone.

See the documentation for the sharded cluster balancer for more information on how migrations work in a sharded cluster.

Security

For sharded clusters running with authentication, you must authenticate as a user whose privileges include:

  • find on the config.shards collection or the config database
  • find on the config.tags collection or the config database
  • update on the config.tags collection or the config database
  • remove on the config.tags collection or the config database

The clusterAdmin or clusterManager built-in roles have the appropriate permissions for issuing sh.removeRangeFromZone(). See the documentation page for Role-Based Access Control for more information.

Example

Given a sharded collection exampledb.collection with a shard key of { a : 1 }, the following operation removes the range with a lower bound of 1 and an upper bound of 10:

sh.removeRangeFromZone( "exampledb.collection",
                { a : 1 },
                { a : 10 }
              )

The min and max must match exactly the bounds of the target range. The following operation attempts to remove the previously created range, but specifies { a : 0 } as the min bound:

admin = db.getSiblingDB("admin")
admin.runCommand(
   {
      updateZoneKeyRange : "exampledb.collection",
      min : { a : 0 },
      max : { a : 10 },
      zone : null
   }
)

While the range of { a : 0 } and { a : 10 } encompasses the existing range, it is not an exact match and therefore sh.removeRangeFromZone() does not remove anything.

Compound Shard Key

Given a sharded collection exampledb.collection with a shard key of { a : 1, b : 1 }, the following operation removes the range with a lower bound of { a : 1, b : 1} and an upper bound of { a : 10, b : 10 }:

sh.removeRangeFromZone( "exampledb.collection",
                { a : 1, b : 1 },
                { a : 10, b : 10 }
              )

Given the previous example, if there was an existing range with a lower bound of { a : 1, b : 5 } and an upper bound of { a : 10, b : 1 }, the operation would not remove that range, as it is not an exact match of the minimum and maximum passed to sh.removeRangeFromZone().