Docs Menu
Docs Home
/
MongoDB Manual
/ / /

reshardCollection

On this page

  • Definition
  • Compatibility
  • Syntax
  • Command Fields
  • Resharding Process
  • Examples
reshardCollection

New in version 5.0.

The reshardCollection command changes the shard key for a collection and changes the distribution of your data.

Tip

In mongosh, this command can also be run through the sh.reshardCollection() 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.

This command is available in deployments hosted in the following environments:

  • MongoDB Atlas: The fully managed service for MongoDB deployments in the cloud

Note

This command is supported in all MongoDB Atlas clusters. For information on all commands, see Unsupported Commands.

The command has the following syntax:

db.adminCommand(
{
reshardCollection: "<database>.<collection>",
key: <shardkey>,
unique: <boolean>,
numInitialChunks: <integer>,
collation: { locale: "simple" },
zones: [
{
min: <document with same shape as shardkey>,
max: <document with same shape as shardkey>,
zone: <string> | null
},
...
],
forceRedistribution: <bool>
}
)

The command takes the following fields:

Field
Type
Description
reshardCollection
string
The namespace of the collection to be resharded. Takes the form <database>.<collection>.
key
document

The document that specifies the new field or fields to use as the shard key.

{ <field1>: <1|"hashed">, ... }

Set the field values to either:

unique
boolean
Optional. Specify whether there is a uniqueness constraint on the shard key. Only false is supported. Defaults to false.
numInitialChunks
integer
Optional. Specifies the initial number of chunks to create across all shards in the cluster when resharding a collection. The default is the number of chunks that exist for the collection under the current shard key pattern. MongoDB will then create and balance chunks across the cluster. The numInitialChunks must result in less than 8192 per shard.
collation
document
Optional. If the collection specified in reshardCollection has a default collation, you must include a collation document with { locale : "simple" }, or the reshardCollection command fails.
zones
array
Optional. To maintain or add zones, specify the zones for your collection in an array.
forceRedistribution
boolean

Optional. If set to true, the operation runs even if the new shard key is the same as the old shard key. Use with the zones option to move data to specific zones.

New in version 7.2.

In a collection resharding operation, a shard can be a:

  • donor, which currently stores chunks for the sharded collection.

  • recipient, which stores new chunks for the sharded collection based on the shard keys and zones.

A shard can be donor and a recipient at the same time. The set of donor shards is identical to the recipient shards, unless you use zones.

The config server primary is always the resharding coordinator and starts each phase of the resharding operation.

During the initialization phase, the resharding coordinator determines the new data distribution for the sharded collection.

During the index phase:

  • Each shard recipient creates a new, empty sharded collection with the same collection options as the existing sharded collection. This new sharded collection is the target for where recipient shards write the new data.

  • Each shard recipient builds the necessary new indexes. These include all existing indexes on the sharded collection and an index compatible with the new shard key pattern if such an index doesn’t already exist on the sharded collection.

During the clone, apply, and catch-up phase:

  • Each shard recipient clones an initial copy of the documents it would own under the new shard key.

  • Each shard recipient begins applying oplog entries from operations that happened after the recipient cloned the data.

  • When the estimate for the time remaining to complete the resharding operation is under two seconds, the resharding coordinator blocks writes for the collection.

    Note

    If desired, you can manually force the resharding operation to complete by issuing the commitReshardCollection command. This is useful if the current time estimate to complete the resharding operation is an acceptable duration for your collection to block writes. The commitReshardCollection command blocks writes early and forces the resharding operation to complete. During the time period where writes are blocked your application experiences an increase in latency.

  • Once the resharding process reaches the commit phase, it may no longer be aborted with abortReshardCollection.

  • When all shards have reached strict consistency, the resharding coordinator commits the resharding operation and installs the new routing table.

  • The resharding coordinator instructs each donor and recipient shard primary, independently, to rename the temporary sharded collection. The temporary collection becomes the new resharded collection.

  • Each donor shard drops the old sharded collection.

    Tip

    See also:

The following example reshards the sales.orders collection with the new shard key { order_id: 1 }:

db.adminCommand({
reshardCollection: "sales.orders",
key: { order_id: 1 }
})

Output:

{
ok: 1,
'$clusterTime': {
clusterTime: Timestamp(1, 1624887954),
signature: {
hash: Binary(Buffer.from("0000000000000000000000000000000000000000", "hex"), 0),
keyId: 0
}
},
operationTime: Timestamp(1, 1624887947)
}

Starting in MongoDB 7.2, you can reshard a collection on the same key, which can be used to redistribute data onto new shards.

After adding a shard to the cluster, you use the reshardCollection command with the forceRedistribution option to redistribute data across the cluster:

db.adminCommand({
reshardCollection: "accounts.invoices",
key: { store_id: "hashed" },
forceRedistribution: true
})

Starting in MongoDB 7.2, you can use the reshardCollection command to move data into new zones without changing the shard key.

The following command redistributes data for the accounts.sales collection using the same shard key, moving data from zones zone01 and zone02 to zone03 and zone04:

db.adminCommand({
reshardCollection: "accounts.sales",
key: { region_id: "hashed" },
forceRedistribution: true,
zones: [
{
zone: "zone04",
min: { region_id: MinKey() },
max: { region_id: 10 }
},
{
zone: "zone05",
min: { region_id: 10 },
max: { region_id: MaxKey() }
}
]
})

Back

removeShardFromZone

Next

setAllowMigrations