Docs Menu
Docs Home
/
MongoDB Manual
/
Reference
/
mongosh Methods
/
Sharding

sh.reshardCollection()

On this page

  • Definition
  • Compatibility
  • Considerations
  • Resharding Process
  • Examples
  • Learn More

Definition

sh.reshardCollection(namespace, key, unique, options)

New in version 5.0.

The sh.reshardCollection() method changes the shard key for a collection and changes the distribution of your data.

Before you reshard a collection, read the the reshard requirements and reshard limitations.

Important

mongosh Method

This page documents a mongosh method. This is not the documentation for database commands or language-specific drivers, such as Node.js.

For the database command, see the reshardCollection command.

For MongoDB API drivers, refer to the language-specific MongoDB driver documentation.

sh.reshardCollection() takes the following fields:

Field
Type
Description

namespace

string

The namespace of the collection to shard in 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:

See also Shard Key Indexes

unique

boolean

Optional. Specify whether there is a uniqueness constraint on the shard key. Only false is supported. Defaults to false.

options

document

Optional. A document containing optional fields, including numInitialChunks, collation, zones and forceRedistribution.

The options field supports the following fields:

Field
Type
Description

numInitialChunks

integer

Optional. Specifies the initial number of chunks to create across all shards in the cluster when resharding a collection. The default value is 90. 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 to reshardCollection has a default collation, you must include a collation document with { locale : "simple" }, or the reshardCollection command fails.

zones

array

Optional. Specifies the zones for the collection.

To maintain or add zones, specify the zones for your collection in an array:

[
  {s
      min: <document with same shape as shardkey>,
      max: <document with same shape as shardkey>,
      zone: <string> | null
  },
  ...
]

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 8.0.

Compatibility

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

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

Important

This command is not supported in M0, M2, and M5 clusters. For more information, see Unsupported Commands.

Considerations

Index builds that occur during resharding might silently fail.

  • Do not create indexes during the resharding process.

  • Do not start the resharding process if there are ongoing index builds.

Resharding Process

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 config server primary is always the resharding coordinator and starts each phase of the resharding operation.

Initialization Phase

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

Clone Phase

During the clone phase:

  • Each recipient shard creates a temporary, empty sharded collection with the same collection options as the donor sharded collection. This new collection is the target for where recipient shards write the new data. The recipient shards do not create any index except the _id index until the index phase.

  • Each recipient shard clones collection data from the donor shard, including all documents that the recipient shard owns under the new shard key.

Index Phase

During the index phase, each recipient shard 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.

Apply and Catch-up Phase

During the apply and catch-up phase:

  • Each recipient shard begins applying oplog entries that were written to the the corresponding donor shard after the recipient cloned the data.

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

Note

If required, you can manually force the resharding operation to complete by issuing the sh.commitReshardCollection() method. This is useful if the current time estimate to complete the resharding operation is an acceptable duration for your collection to block writes. The sh.commitReshardCollection() method 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.

Commit Phase

During the commit phase:

  • The resharding coordinator waits for all shards to reach strict consistency, then commits the resharding operation.

  • 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.

Note

Once the resharding process reaches the commit phase, the process cannot be ended with sh.abortReshardCollection().

Examples

Reshard a Collection

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

sh.reshardCollection( "sales.orders", { order_id: 1 } )

Example output:

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

Reshard a Collection to the Same Shard Key

In order to reshard to the same shard key, set forceRedistribution to true. The following example reshards the sales.orders collection to the same shard key { order_id: 1 } and redistributes data.

sh.reshardCollection(
  "sales.orders",
  { order_id: 1 },
  { forceRedistribution: true }
)

Example output:

{
  ok: 1,
  '$clusterTime': {
    clusterTime: Timestamp({ t: 1733502241, i: 20 }),
    signature: {
      hash: Binary.createFromBase64('AAAAAAAAAAAAAAAAAAAAAAAAAAA=', 0),
      keyId: Long('0')
    }
  },
  operationTime: Timestamp({ t: 1733502241, i: 20 })
}

Reshard a Collection with Zones

Reshard a collection with zones when you need to adjust the distribution of data across the shards in your cluster to meet changing requirements or to improve performance.

In the following example, the test.scores collection resides on shard0 and shard1. The current shard key is { _id: 1}.

1

Add shards to a new zone

In this example, this zone is called NewZone.

sh.addShardToZone( "shard2", "NewZone" )
sh.addShardToZone( "shard3", "NewZone" )
2

Run sh.reshardCollection with the new zone information

sh.reshardCollection(
  "test.scores",
  { "studentId": 1, "testId": 1},
  { zones: [ {
    min: { "studentId": MinKey(), "testId": MinKey() },
    max: { "studentId": MaxKey(), "testId": MaxKey() },
    zone: "NewZone" }
    ]
} )

The resharding operation adds the shards in zone NewZone as recipients. The database primary shard is added as a recipient as a backstop for any missing ranges in the zone definition. If there are no missing ranges, the collection is cloned on shards in the "NewZone", such as shard2 and shard3 in this example. sh.reshardCollection returns the following:

{
   ok: 1,
   '$clusterTime': {
   clusterTime: Timestamp( { t: 1699484530, i: 54 } ),
   signature: {
   hash: Binary.createFromBase64( "90ApBDrSSi4XnCpV3OWIH4OGO0Y=", 0 ),
   keyId: Long( "7296989036055363606" )
   } },
   operationTime: Timestamp( { t: 1699484530, i: 54 } )
}

Learn More

Back

sh.removeTagRange

Next

sh.setBalancerState