Sharding > Shard Keys > Change a Shard Key

Reshard a Collection¶

The ideal shard key allows MongoDB to distribute documents evenly throughout the cluster while facilitating common query patterns. A suboptimal shard key can lead to performance or scaling issues due to uneven data distribution. Starting in MongoDB 5.0, you can change the shard key for a collection to change the distribution of your data across a cluster.

Requirements¶

Before you reshard your collection, ensure that you meet the following requirements:

• Your application can tolerate a period of two seconds where the collection that is being resharded blocks writes. During the time period where writes are blocked your application experiences an increase in latency. If your workload cannot tolerate this requirement, consider refining your shard key instead.

• Your database meets these resource requirements:

  • Available storage space: Ensure that your available storage space is at least 1.2x the size of the collection that you want to reshard. For example, if the size of the collection you want to reshard is 1 TB, you should have at least 1.2 TB of free storage when starting the sharding operation.
  • I/O: Ensure that your I/O capacity is below 50%.
  • CPU load: Ensure your CPU load is below 80%.
  Important

  These requirements are not enforced by the database. A failure to allocate enough resources can result in:

  • the database running out of space and shutting down
  • decreased performance
  • the resharding operation taking longer than expected

  If your application has time periods with less traffic, reshard your collection during that time if possible.

• You have rewritten your application code to update your queries to use both the current shard key and the new shard key.

  The following queries return an error if the query filter does not include both the current shard key or a unique field (like _id):

  For optimal performance, we recommend that you also rewrite other queries to include the new shard key.

  Once the resharding operation completes, you can remove the old shard key from the queries.

• No index builds are in progress. Use db.currentOp() to check for any running index builds:

   db.adminCommand(    {      currentOp: true,      $or: [        { op: "command", "command.createIndexes": { $exists: true }  },        { op: "none", "msg" : /^Index Build/ }      ]    })

  In the result document, if the inprog field value is an empty array, there are no index builds in progress:

  {   inprog: [],   ok: 1,   '$clusterTime': { ... },   operationTime: <timestamp>}

Limitations¶

• Only one collection can be resharded at a time.
• writeConcernMajorityJournalDefault must be true.
• Resharding a collection that has a uniqueness constraint is not supported.
• The new shard key cannot have a uniqueness constraint.

• The following commands and corresponding shell methods are not supported on the collection that is being resharded while the resharding operation is in progress:

• The following commands and methods are not supported on the cluster while the resharding operation is in progress:

  Warning

  Using any of the preceding commands during a resharding operation causes the resharding operation to fail.

• If the collection to be resharded uses Atlas Search, the search index will become unavailable when the resharding operation completes. You need to manually rebuild the search index once the resharding operation completes.

Resharding Process¶

db.adminCommand({  reshardCollection: "<database>.<collection>",  key: <shardkey>})

db.getSiblingDB("admin").aggregate([  { $currentOp: { allUsers: true, localOps: false } },  {    $match: {      type: "op",      "originatingCommand.reshardCollection": "<database>.<collection>"    }  }])

[  {    shard: '<shard>',    type: 'op',    desc: 'ReshardingRecipientService | ReshardingDonorService | ReshardingCoordinatorService <reshardingUUID>',    op: 'command',    ns: '<database>.<collection>',    originatingCommand: {      reshardCollection: '<database>.<collection>',      key: <shardkey>,      unique: <boolean>,      collation: { locale: 'simple' }    },    totalOperationTimeElapsedSecs: <number>,    remainingOperationTimeEstimatedSecs: <number>,    ...  },  ...]

{  ok: 1,  '$clusterTime': {    clusterTime: <timestamp>,    signature: {      hash: Binary(Buffer.from("0000000000000000000000000000000000000000", "hex"), 0),      keyId: <number>    }  },  operationTime: <timestamp>}

sh.status()

databases[  {     database: {     _id: '<database>',     primary: '<shard>',     partitioned: true,     version: {       uuid: <uuid>,       timestamp: <timestamp>,       lastMod: <number>     }   },   collections: {     '<database>.<collection>': {       shardKey: <shardkey>,       unique: <boolean>,       balancing: <boolean>,       chunks: [],       tags: []     }   }  }  ...]

db.adminCommand({  commitReshardCollection: "<database>.<collection>"})

db.adminCommand({  abortReshardCollection: "<database>.<collection>"})

Behavior¶

Minimum Duration of a Resharding Operation¶

The minimum duration of a resharding operation is always 5 minutes.

Retryable Writes¶

Retryable writes initiated before or during resharding can be retried during and after the collection has been resharded for up to 5 minutes. After 5 minutes you may be unable to find the definitive result of the write and subsequent attempts to retry the write fail with an IncompleteTransactionHistory error.

Error Cases¶

Primary Failovers¶

If a primary failover on a replica set shard or config server occurs, the resharding operation aborts.

If a resharding operation aborts due to a primary failover, run the cleanupReshardCollection command before starting a new resharding operation:

db.runCommand({  cleanupReshardCollection: "<database>.<collection>"})

Duplicate _id Values¶

The resharding operation fails if _id values are not globally unique to avoid corrupting collection data. Duplicate _id values can also prevent successful chunk migration. If you have documents with duplicate _id values, copy the data from each into a new document, and then delete the duplicate documents.