rewriteCollection (database command)

Definition

rewriteCollection

Rewrites a sharded collection to disk using the same shard key.

Use this command to redistribute data when adding or removing shards, or to reclaim disk space.

New in version 8.3.

Compatibility

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

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

• MongoDB Enterprise: The subscription-based, self-managed version of MongoDB

• MongoDB Community: The source-available, free-to-use, and self-managed version of MongoDB

Syntax

The command has the following syntax:

db.adminCommand( {
   rewriteCollection: "<database>.<collection>",
   numInitialChunks: <int>,
   zones: <zones>
} )

Command Fields

The command takes the following fields:

Considerations

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

• Your application can tolerate a period of two seconds where the affected collection 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:

  • Ensure that the available storage space on each recipient shard is at least twice the storage size of the collection that you want to rewrite plus its total index size, divided by the number of shards:

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

    For example, consider a collection with a storage size of 2 TB data and a 400 GB index. To distribute it across four shards you'd need:

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

    To rewrite this collection, each shard requires 1.2 TB of available storage.

    On MongoDB Atlas, you may need to upgrade to the next tier of storage for the rewrite operation. You can downgrade once the operation completes.

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

  • 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 operation taking longer than expected

  If your application has time periods with less traffic, perform this operation on the collection during that time if possible.

• No index builds are in progress. To check for running index builds, use $currentOp:

  db.getSiblingDB("admin").aggregate( [
     { $currentOp : { idleConnections: true } },
     { $match: {
           $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>
  }

Examples

To rewrite a collection, run the following command:

db.adminCommand( {
  rewriteCollection: "sales.orders"
} )

Learn More

• Reshard to the Same Shard Key

• Reshard a Collection back to the Same Shard Key

• Resharding for Adding and Removing Shards

• reshardCollection

• moveCollection