Docs Menu
Docs Home
MongoDB Manual
/ / /

Monitor Defragmentation of a Sharded Collection

On this page

  • About this Task
  • Before you Begin
  • Procedure
  • Next Steps
  • Learn More

To monitor defragmentation of a sharded collection, use the balancerCollectionStatus command.

You can see the current defragmentation state and the number of remaining chunks to process. This shows you the defragmentation progress.

Defragmentation uses the following phases to reduce the number of chunks in a collection and improve performance:

  1. Merge chunks on the same shard that can be merged.

  2. Migrate smaller chunks to other shards. A small chunk is one that contains data less than 25% of the chunkSize setting.

  3. Merge remaining chunks on the same shard that can be merged.

The procedure in this task uses an example sharded collection named ordersShardedCollection in a database named test.

You can use your own sharded collection and database in the procedure.

In the procedure for this task, you monitor the phases and see the defragmentation progress.



balancerCollectionStatus: "test.ordersShardedCollection"

The previous command returns a document with information about defragmentation status, current phase, and the defragmentation work remaining. For example:

"balancerCompliant": false,
"firstComplianceViolation": "defragmentingChunks",
"details": {
"currentPhase": "moveAndMergeChunks",
"progress": { "remainingChunksToProcess": 1 }

The following table describes the document fields.

false if collection chunks must be moved. Otherwise, true.
Indicates the reason that chunks for the namespace must be moved or merged. Only returned if balancerCompliant is false.
Addtional information about the current defragmentation state. Only returned if firstComplianceViolation is defragmentingChunks.

Current defragmentation phase:

  • For phase one, currentPhase is mergeAndMeasureChunks.

    Phase one merges contiguous chunks located on the same shard and calculates the data size for those chunks.

  • For phase two, currentPhase is moveAndMergeChunks.

    After phase one is complete, there might be some small chunks remaining. Phase two migrates those small chunks to other shards and merges the chunks on those shards.

Number of remaining chunks to process in the current phase.

For additional information about the returned document fields, see the balancer collection status output document.


After defragmentation completes, the command returns either:

  • balancerCompliant: true if your collection is balanced.

  • balancerCompliant: false with firstComplianceViolation set to a string other than defragmentingChunks if your collection is not balanced.

Example output for a balanced collection after defragmentation completes:

chunkSize: 0.2,
balancerCompliant: true,
ok: 1,
'$clusterTime': {
clusterTime: Timestamp({ t: 1677543079, i: 1 }),
signature: {
hash: Binary(Buffer.from("0000000000000000000000000000000000000000", "hex"), 0),
keyId: Long("0")
operationTime: Timestamp({ t: 1677543079, i: 1 })

If defragmentation has not yet completed, you can stop it. For details, see Stop Defragmenting a Sharded Collection.

  • Print shard status, see db.printShardingStatus()

  • Retrieve shard status details, see sh.status()

  • View shard status collection fields, see Sharded Collection

  • See active mongos instances, see Active mongos Instances

  • Monitor shards using MongoDB Atlas, see Review Sharded Clusters


Start Defragmenting a Sharded Collection


Stop Defragmenting a Sharded Collection