Docs Menu
Docs Home
/
MongoDB Manual
/
Reference
/
Database Commands
/
Sharding Commands

addShardToZone

On this page

  • Definition
  • Syntax
  • Behavior
  • Security
  • Example

Definition

addShardToZone

Associates a shard with a zone. MongoDB associates this shard with the given zone. Chunks that are covered by the zone are assigned to shards associated with the zone.

Tip

In mongosh, this command can also be run through the sh.addShardToZone() helper method.

Helper methods are convenient for mongosh users, but they may not return the same level of information as database commands. In cases where the convenience is not needed or the additional return fields are required, use the database command.

You can only run addShardToZone on the admin database from a mongos instance.

Syntax

The command has the following syntax:

db.adminCommand(
   {
     addShardToZone: <string>,
     zone: <string>
   }
)

Command Fields

The command takes the following fields:

Field
Type
Description
string

The name of the shard to associate with the zone.

string

The name of the zone to associate with the shard.

mongosh provides the helper method sh.addShardToZone().

Behavior

You can associate a zone with multiple shards, and a shard can associate with multiple zones.

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

Ranges

MongoDB effectively ignores zones that do not have at least one range of shard key values associated with it.

To associate a range of shard key values with a zone, use the updateZoneKeyRange database command, or the sh.updateZoneKeyRange() shell helper.

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.

Tip

Changed in version 4.0.3: By defining the zones and the zone ranges before sharding an empty or a non-existing collection, the shard collection operation creates chunks for the defined zone ranges as well as any additional chunks to cover the entire range of the shard key values and performs an initial chunk distribution based on the zone ranges. This initial creation and distribution of chunks allows for faster setup of zoned sharding. After the initial distribution, the balancer manages the chunk distribution going forward.See Pre-Define Zones and Zone Ranges for an Empty or Non-Existing Collection for an example.

Security

For sharded clusters that enforce access control, you must authenticate as a user whose privileges include either:

  • update on the shards collection in the config database; or, alternatively,

  • enableSharding on the cluster resource (available starting in version 4.2.2, 4.0.14, 3.6.16).

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

Example

The following example associates shard0000 with zone JFK:

db.adminCommand( { addShardToZone : "shard0000" , zone : "JFK" } )

A shard can associate with multiple zones. The following example associates LGA to shard0000:

db.adminCommand( { addShardToZone : "shard0000" , zone : "LGA" } )

shard0000 associates with both the LGA zone and the JFK zone. In a balanced cluster, MongoDB routes reads and writes covered by either zone to shard0000.

Back

addShard