Sharding >
Sharding Commands

Sharding Commands¶

On this page

JavaScript Methods
Database Commands

JavaScript Methods¶

sh.addShard(host)¶

Parameters:	host (string) – Specify the hostname of a database instance or a replica set configuration.

Use this method to add a database instance or replica set to a sharded cluster. This method must be run on a mongos instance. The host parameter can be in any of the following forms:

copy

[hostname]
[hostname]:[port]
[set]/[hostname]
[set]/[hostname],[hostname]:port

You can specify shards using the hostname, or a hostname and port combination if the shard is running on a non-standard port.

Warning

Do not use localhost for the hostname unless your configuration server is also running on localhost.

The optimal configuration is to deploy shards across replica sets. To add a shard on a replica set you must specify the name of the replica set and the hostname of at least one member of the replica set. You must specify at least one member of the set, but can specify all members in the set or another subset if desired. sh.addShard() takes the following form:

If you specify additional hostnames, all must be members of the same replica set.

copy

sh.addShard("set-name/seed-hostname")

Example

copy

sh.addShard("repl0/mongodb3.example.net:27327")

The sh.addShard() method is a helper for the addShard command. The addShard command has additional options which are not available with this helper.

See also

sh.enableSharding(database)¶

Parameters:	database (string) – Specify a database name to shard.

Enables sharding on the specified database. This does not automatically shard any collections, but makes it possible to begin sharding collections using sh.shardCollection().

See also

sh.shardCollection()

sh.shardCollection(namespace, key, unique)¶

Parameters:	namespace (string) – The namespace of the collection to shard. key (document) – A document containing a shard key that the sharding system uses to partition and distribute objects among the shards. unique (boolean) – When true, the `unique` option ensures that the underlying index enforces uniqueness so long as the unique index is a prefix of the shard key.

Shards the named collection, according to the specified shard key. Specify shard keys in the form of a document. Shard keys may refer to a single document field, or more typically several document fields to form a “compound shard key.”

See

Size of Sharded Collection

sh.splitFind(namespace, query)¶

Parameters:	namespace (string) – Specify the namespace (i.e. “`<database>.<collection>`”) of the sharded collection that contains the chunk to split. query – Specify a query to identify a document in a specific chunk. Typically specify the shard key for a document as the query.

Splits the chunk containing the document specified by the query at its median point, creating two roughly equal chunks. Use sh.splitAt() to split a collection in a specific point.

In most circumstances, you should leave chunk splitting to the automated processes. However, when initially deploying a sharded cluster it is necessary to perform some measure of pre-splitting using manual methods including sh.splitFind().

sh.splitAt(namespace, query)¶

Parameters:	namespace (string) – Specify the namespace (i.e. “`<database>.<collection>`”) of the sharded collection that contains the chunk to split. query (document) – Specify a query to identify a document in a specific chunk. Typically specify the shard key for a document as the query.

Splits the chunk containing the document specified by the query as if that document were at the “middle” of the collection, even if the specified document is not the actual median of the collection. Use this command to manually split chunks unevenly. Use the “sh.splitFind()” function to split a chunk at the actual median.

In most circumstances, you should leave chunk splitting to the automated processes within MongoDB. However, when initially deploying a sharded cluster it is necessary to perform some measure of pre-splitting using manual methods including sh.splitAt().

sh.moveChunk(collection, query, destination)¶

Parameters:	collection (string) – Specify the sharded collection containing the chunk to migrate. query – Specify a query to identify documents in a specific chunk. Typically specify the shard key for a document as the query. destination (string) – Specify the name of the shard that you wish to move the designated chunk to.

Moves the chunk containing the documents specified by the query to the shard described by destination.

This function provides a wrapper around the moveChunk. In most circumstances, allow the balancer to automatically migrate chunks, and avoid calling sh.moveChunk() directly.

See also

“moveChunk” and “Sharding” for more information.

sh.setBalancerState(state)¶

Parameters:	state (boolean) – `true` enables the balancer if disabled, and `false` disables the balancer.

Enables or disables the balancer. Use sh.getBalancerState() to determine if the balancer is currently enabled or disabled and sh.isBalancerRunning() to check its current state.

See also

sh.isBalancerRunning()¶

Returns:	boolean

Returns true if the balancer process is currently running and migrating chunks and false if the balancer process is not running. Use sh.getBalancerState() to determine if the balancer is enabled or disabled.

See also

sh.status()¶

Returns:	A formatted report of the status of the sharded cluster, including data regarding the distribution of chunks.

sh.addShardTag(shard, tag)¶

New in version 2.2.

Parameters:	shard (string) – Specifies the name of the shard that you want to give a specific tag. tag (string) – Specifies the name of the tag that you want to add to the shard.

sh.addShardTag() associates a shard with a tag or identifier. MongoDB uses these identifiers to direct chunks that fall within a tagged range to specific shards.

sh.addTagRange() associates chunk ranges with tag ranges.

Always issue sh.addShardTag() when connected to a mongos instance.

Example

The following example adds three tags, NYC, LAX, and NRT, to three shards:

copy

sh.addShardTag("shard0000", "NYC")
sh.addShardTag("shard0001", "LAX")
sh.addShardTag("shard0002", "NRT")

See also

sh.addTagRange() and
sh.removeShardTag()

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

New in version 2.2.

Parameters:

namespace (string) – Specifies the namespace, in the form of <database>.<collection> of the sharded collection that you would like to tag.
minimum (document) – Specifies the minimum value of the shard key range to include in the tag. 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) – Specifies the maximum value of the shard key range to include in the tag. 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) – Specifies the name of the tag to attach the range specified by the minimum and maximum arguments to.

sh.addTagRange() attaches a range of values of the shard key to a shard tag created using the sh.addShardTag() method. Use this operation to ensure that the documents that exist within the specified range exist on shards that have a matching tag.

Always issue sh.addTagRange() when connected to a mongos instance.

Note

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 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}, create a tag range covering ZIP codes in New York State:

copy

sh.addTagRange( "exampledb.collection",
        { STATE: "NY", ZIP: MinKey },
        { STATE:"NY", ZIP: MaxKey },
        "NY"
        )

sh.removeShardTag(shard, tag)¶

New in version 2.2.

Parameters:	shard (string) – Specifies the name of the shard that you want to remove a tag from. tag (string) – Specifies the name of the tag that you want to remove from the shard.

Removes the association between a tag and a shard.

Always issue sh.removeShardTag() when connected to a mongos instance.

See also

sh.addShardTag(), sh.addTagRange()

sh.help()¶

Returns:	a basic help text for all sharding related shell functions.

Database Commands¶

The following database commands support sharded clusters.

addShard¶

Parameters:	hostname (string) – a hostname or replica-set/hostname string. name (string) – Optional. Unless specified, a name will be automatically provided to uniquely identify the shard. maxSize (integer) – Optional, megabytes. Limits the maximum size of a shard. If `maxSize` is `0` then MongoDB will not limit the size of the shard.

Use the addShard command to add a database instance or replica set to a sharded cluster. You must run this command when connected a mongos instance.

The command takes the following form:

copy

{ addShard: "<hostname><:port>" }

Example

copy

db.runCommand({addShard: "mongodb0.example.net:27027"})

Replace <hostname><:port> with the hostname and port of the database instance you want to add as a shard.

Warning

Do not use localhost for the hostname unless your configuration server is also running on localhost.

The optimal configuration is to deploy shards across replica sets. To add a shard on a replica set you must specify the name of the replica set and the hostname of at least one member of the replica set. You must specify at least one member of the set, but can specify all members in the set or another subset if desired. addShard takes the following form:

copy

{ addShard: "replica-set/hostname:port" }

Example

copy

db.runCommand( { addShard: "repl0/mongodb3.example.net:27327"} )

If you specify additional hostnames, all must be members of the same replica set.

Send this command to only one mongos instance, it will store shard configuration information in the config database.

Note

Specify a maxSize when you have machines with different disk capacities, or if you want to limit the amount of data on some shards.

The maxSize constraint prevents the balancer from migrating chunks to the shard when the value of mem.mapped exceeds the value of maxSize.

See also

listShards¶

Use the listShards command to return a list of configured shards. The command takes the following form:

copy

{ listShards: 1 }

enableSharding¶

The enableSharding command enables sharding on a per-database level. Use the following command form:

copy

{ enableSharding: "<database name>" }

Once you’ve enabled sharding in a database, you can use the shardCollection command to begin the process of distributing data among the shards.

shardCollection¶

The shardCollection command marks a collection for sharding and will allow data to begin distributing among shards. You must run enableSharding on a database before running the shardCollection command.

copy

{ shardCollection: "<db>.<collection>", key: <shardkey> }

This enables sharding for the collection specified by <collection> in the database named <db>, using the key <shardkey> to distribute documents among the shard. <shardkey> is a document, and takes the same form as an index specification document.

Choosing the right shard key to effectively distribute load among your shards requires some planning.

See also

Sharding for more information related to sharding. Also consider the section on Shard Key Selection for documentation regarding shard keys.

Warning

There’s no easy way to disable sharding after running shardCollection. In addition, you cannot change shard keys once set. If you must convert a sharded cluster to a standalone node or replica set, you must make a single backup of the entire cluster and then restore the backup to the standalone mongod or the replica set..

shardingState¶

shardingState is an admin command that reports if mongod is a member of a sharded cluster. shardingState has the following prototype form:

copy

{ shardingState: 1 }

For shardingState to detect that a mongod is a member of a sharded cluster, the mongod must satisfy the following conditions:

the mongod is a primary member of a replica set, and
the mongod instance is a member of a sharded cluster.

If shardingState detects that a mongod is a member of a sharded cluster, shardingState returns a document that resembles the following prototype:

copy

{
  "enabled" : true,
  "configServer" : "<configdb-string>",
  "shardName" : "<string>",
  "shardHost" : "string:",
  "versions" : {
       "<database>.<collection>" : Timestamp(<...>),
       "<database>.<collection>" : Timestamp(<...>)
  },
  "ok" : 1
}

Otherwise, shardingState will return the following document:

copy

{ "note" : "from execCommand", "ok" : 0, "errmsg" : "not master" }

The response from shardingState when used with a config server is:

copy

{ "enabled": false, "ok": 1 }

Note

mongos instances do not provide the shardingState.

Warning

This command obtains a write lock on the affected database and will block other operations until it has completed; however, the operation is typically short lived.

removeShard¶

Starts the process of removing a shard from a cluster. This is a multi-stage process. Begin by issuing the following command:

copy

{ removeShard : "[shardName]" }

The balancer will then migrate chunks from the shard specified by [shardName]. This process happens slowly to avoid placing undue load on the overall cluster.

The command returns immediately, with the following message:

copy

{ msg : "draining started successfully" , state: "started" , shard: "shardName" , ok : 1 }

If you run the command again, you’ll see the following progress output:

copy

{ msg: "draining ongoing" , state: "ongoing" , remaining: { chunks: 23 , dbs: 1 }, ok: 1 }

The remaining document specifies how many chunks and databases remain on the shard. Use db.printShardingStatus() to list the databases that you must move from the shard.

Each database in a sharded cluster has a primary shard. If the shard you want to remove is also the primary of one of the cluster’s databases, then you must manually move the database to a new shard. This can be only after the shard is empty. See the movePrimary command for details.

After removing all chunks and databases from the shard, you may issue the command again, to return:

copy

{ msg: "remove shard completed successfully", state: "completed", host: "shardName", ok : 1 }

← Convert a Replica Set to a Replicated Sharded Cluster Application Development →