sh.removeRangeFromZone()

Definition

  • sh.removeRangeFromZone(namespace, minimum, maximum)

New in version 3.4.

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

sh.removeRangeFromZone() takes the following arguments:

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

The collection must be sharded for the operation to succeed.minimumdocumentThe 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.maximumdocumentThe 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 betweenunused, out of date, or conflicting ranges and a zone.

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

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

Behavior

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

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

Balancer

Removing the association between a range and a zone removes the constraintskeeping chunks covered by the range on the shards inside that zone. During thenext balancer round, the balancer may migrate chunks that were previouslycovered by the zone.

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

Security

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

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

The clusterAdmin or clusterManager built-in roles havethe 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 1and an upper bound of 10:

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

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

  1. admin = db.getSiblingDB("admin")
  2. admin.runCommand(
  3.    {
  4.       updateZoneKeyRange : "exampledb.collection",
  5.       min : { a : 0 },
  6.       max : { a : 10 },
  7.       zone : null
  8.    }
  9. )

While the range of { a : 0 } and { a : 10 } encompasses the existingrange, it is not an exact match and thereforesh.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 lowerbound of { a : 1, b : 1} and an upper bound of { a : 10, b : 10 }:

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

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