Changing the definition for a shard cluster

The db.runCommand command with changeShardCollection command syntax changes the definition for a shard cluster.

Before you begin

If the shard cluster uses an expression for distributing data across multiple database servers, you must add database servers to a shard cluster and remove database servers from a shard cluster by running the changeShardCollection command. If the shard-cluster definition uses a hash algorithm, database servers are automatically added to the shard cluster when you run the sh.addShard MongoDB shell command.

If you change a shard-cluster definition to include a new shard server, that server must first be added to a shard cluster by running the db.runCommand command with addShard command syntax.

When a shard-cluster definition changes, existing data on shard servers is redistributed to match the new definition.

About this task

The following steps apply to changing the definition for shard cluster that uses an expression for distributing documents in a collection across multiple database servers.

Procedure

To change the definition for a shard cluster:
  1. Run the mongo command.
    The command starts the MongoDB shell.
  2. Change the shard-cluster definition by running the changeShardCollection command. You must redefine all expressions for all shard servers, not just newly added or changed shard servers.
    
1 db.runCommand ({"changeShardCollection":"database.
2.1 collection
2.1 table
1", expressions:{+ , " ER_group_name ":" expression " ,"ER_group_name":"remainder" })
    Element Description Restrictions
    collection The name of the collection that is distributed across database servers. The collection must exist.
    database The name of the database that contains the collection that is distributed across database servers. The database must exist.
    ER_group_name The Enterprise Replication group name of a database server that receives copied data.

    The default Enterprise Replication group name for a database server is the database server's name prepended with g_. For example, the default Enterprise Replication group name for a database server that is named myserver is g_myserver.

    		 None.
    expression The expression that is used to select documents by shard key value. None.
    remainder The database server that receives documents with shard key values that are not selected by expressions.
    table The name of the table that is distributed across database servers. The table must exist.
  3. For optimal query performance, connect to the wire listener and run the MongoDB ensureIndex command on the shard key each of a cluster's shard servers. The ensureIndex command ensures that an index for the collection or table is created on the shard server.

Example

You have a shard cluster that is composed of three database servers, and the shard cluster is defined by the following command:
> db.runCommand({"shardCollection":"database1.collection1",
   expressions:{"g_shard_server_1":"in ('KS','MO')",
   "g_shard_server_2":"in ('CA','WA')","g_shard_server_3":"remainder"})
To add g_shard_server_4 and g_shard_server_5 to the shard cluster and change where data is sent to, run the following command:
> db.runCommand({"changeShardCollection":"database1.collection1",
   expressions:{"g_shard_server_1":"in ('KS','MO')",
   "g_shard_server_2":"in ('TX','OK')","g_shard_server_3":"in ('CA','WA')",
   "g_shard_server_4":"in ('OR','ID')","g_shard_server_5":"remainder"})
The new shard cluster contains five database servers:
  • Inserted documents with a state field value of KS or MO are sent to g_shard_server_1.
  • Inserted documents with a state field value of TX or OK are sent to g_shard_server_2.
  • Inserted documents with a state field value of CA or WA are sent to g_shard_server_3.
  • Inserted documents with a state field value of OR or ID are sent to g_shard_server_4.
  • Inserted documents with a state field value that is not in the expression are sent to g_shard_server_5.
To then remove g_shard_server_2 and change where the data that was on g_shard_server_2 is sent to, run the following command:
> db.runCommand({"changeShardCollection":"database1.collection1", 
   expressions:{"g_shard_server_1":"in ('KS','MO')",
   "g_shard_server_3":"in ('TX','CA','WA')",
   "g_shard_server_4":"in ('OK','OR','ID')",
   "g_shard_server_5":"remainder"})
The new shard cluster contains four database servers.
  • Inserted documents with a state field value of TX are now sent to g_shard_server_3.
  • Inserted documents with a state field value of OK are now sent to g_shard_server_4.
Existing data on shard servers is redistributed to match the new definition.