Reshard a Collection

About this Task

• Only one collection can be resharded at a time.

• writeConcernMajorityJournalDefault must be true.

• To reshard a collection that has a uniqueness constraint, the new shard key must satisfy the unique index requirements for any existing unique indexes.

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

  • collMod

  • convertToCapped

  • createIndexes

  • createIndex()

  • drop

  • drop()

  • dropIndexes

  • dropIndex()

  • renameCollection

  • renameCollection()

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

  • addShard

  • removeShard

  • db.createCollection()

  • dropDatabase

  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.

Before you Begin

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 the available storage space on each shard the collection will be distributed across is at least twice the size of the collection that you want to reshard and its total index size, divided by the number of shards.

    storage_req = ( ( collection_size + index_size ) * 2 ) / shard_count

    For example, consider a collection that contains 2 TB of data and has a 400 GB index distributed across four shards. To perform a resharding operation on this collection, each shard would require 1.2 TB of available storage.

    1.2 TB storage = ( ( 2 TB collection + 0.4 TB index ) * 2 ) / 4 shards

    To meet storage requirements, you may need to upgrade to the next tier of storage during the resharding operation. You can scale down once the operation completes.

  • I/O: Ensure that your I/O capacity is below 50%.

  • CPU load: Ensure that 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 must rewrite your application's queries to use both the current shard key and the new shard key.

  Tip

  If your application can tolerate downtime, you can perform these steps to avoid rewriting your application's queries to use both the current and new shard keys:

  1. Stop your application.

  2. Rewrite your application to use the new shard key.

  3. Wait until resharding completes. To monitor the resharding process, use the $currentOp pipeline stage.

  4. Deploy your rewritten application.

  Before resharding completes, the following queries return an error if the query filter does not include either the current shard key or a unique field (like _id):

  • deleteOne()

  • findAndModify()

  • findOneAndDelete()

  • findOneAndReplace()

  • findOneAndUpdate()

  • replaceOne()

  • updateOne()

  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>
  }

Steps

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.

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

Error Cases

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