Manage the ApsaraDB for MongoDB balancer-ApsaraDB for MongoDB(MongoDB)-阿里云帮助中心

How it works

The balancer monitors data distribution across shard nodes and migrates data automatically. Behavior varies by database engine version.

MongoDB 5.0 and earlier

The balancer tracks chunk counts per shard node. When the difference reaches the migration threshold, it migrates chunks (moveChunk) to rebalance the cluster.

Database engine version	Migration threshold
MongoDB 4.2, 4.4, 5.0	1
MongoDB 3.4 (discontinued), MongoDB 4.0	Default: 2. Reduced to 1 if total chunks < 20 or previously migrated chunks < 20
MongoDB 3.2 (discontinued)	Total chunks < 20: threshold is 2. Total chunks 20--80: threshold is 4. Total chunks >= 80: threshold is 8

MongoDB 6.0

The balancer monitors data size per collection per shard instead of chunk counts. If the size difference between two shards in a collection exceeds 384 MB (three times the default chunk size), it splits data by shard tag and migrates it using moveRange.

To verify data balance, run getShardDistribution() and focus on data size rather than chunk count.

Note

After you upgrade to V6.0 (minor 7.0.1) or later, sh.status() may show that chunk counts across shards are no longer balanced or that each shard holds a single chunk. This is the expected behavior of the new balancer. For details, see Imbalanced chunk count across shards after a MongoDB upgrade.

Usage notes

Supported only for sharded cluster instances.
By default, the balancer runs continuously (24-hour active window).
Chunk migration consumes resources and may degrade performance. Schedule the active window during off-peak hours.

Check the balancer status

Before disabling the balancer, verify that no migration is in progress.

Connect to the sharded cluster instance by using the mongo shell.
Run the following command:
```
   sh.isBalancerRunning()
```

Interpret the result based on the return type: Map return value Some mongo shell versions return a Map object. Check the inBalancerRound field as documented in sh.isBalancerRunning().

Boolean return value

Value	Meaning
`false`	The balancer is idle. Safe to disable.
`true`	The balancer is migrating chunks. Do not disable it to avoid data inconsistency.

`inBalancerRound` value	Meaning
`false`	The balancer is idle. Safe to disable.
`true`	The balancer is migrating chunks. Do not disable it to avoid data inconsistency.

   {
     mode: 'full',
     inBalancerRound: false,
     numBalancerRounds: Long("1143"),
     ok: 1,
     '$clusterTime': {
       clusterTime: Timestamp({ t: 1639753724, i: 3 }),
       signature: {
         hash: Binary(Buffer.from("0000000000000000000000000000000000000000", "hex"), 0),
         keyId: Long("0")
       }
     },
     operationTime: Timestamp({ t: 1639753724, i: 3 })
   }

Set an active time window

Restrict the balancer to specific hours to reduce performance impact during peak usage.

Connect to the sharded cluster instance by using the mongo shell.
Switch to the config database:
```
   use config
```

Set the active time window. Replace the placeholders with your values. Example: Run the balancer from 01:00 to 03:00 daily:

Note

Times are in the local time zone of the instance region.

Placeholder	Description	Format
`<start-time>`	Start time of the active time window	HH:MM (HH: 00--23, MM: 00--59)
`<stop-time>`	End time of the active time window	HH:MM (HH: 00--23, MM: 00--59)

   db.settings.update(
      { _id: "balancer" },
      { $set: { activeWindow : { start : "<start-time>", stop : "<stop-time>" } } },
      { upsert: true }
   )

   db.settings.update(
      { _id: "balancer" },
      { $set: { activeWindow : { start : "01:00", stop : "03:00" } } },
      { upsert: true }
   )

Run sh.status() to verify. The output shows the active time window:

Remove the active time window

To restore continuous balancing, remove the active time window:

db.settings.update({ _id : "balancer" }, { $unset : { activeWindow : true } })

Enable the balancer

Enabling the balancer immediately starts data migration if sharding is configured, which consumes instance resources. Perform this during off-peak hours.

Connect to the sharded cluster instance by using the mongo shell.
Switch to the config database:
```
   use config
```
Enable the balancer:
```
   sh.setBalancerState(true)
```

Disable the balancer

Note

A disabled balancer stops migrating data across shard nodes, which may cause data skew.

Connect to the sharded cluster instance by using the mongo shell.
Switch to the config database:
```
   use config
```
Check whether the balancer is migrating data. Interpret the return value as described in Check the balancer status.
- If the result is false (or inBalancerRound: false for Map return values), proceed to the next step.
- If the result is true (or inBalancerRound: true), wait for the migration to complete. Disabling the balancer mid-migration may cause data inconsistency.
```
   sh.isBalancerRunning()
```
After the balancer is idle, disable it:
```
   sh.stopBalancer()
```

References

FAQ

Is it normal that orphaned documents are generated after the balancer is enabled, and how do I handle them?

Orphaned documents can be created when a chunk migration is interrupted or rolled back, or when an unsuitable shard key distributes data unevenly. In these cases, a moveChunk operation can leave data on the source shard.

The orphaned document count can fluctuate while the balancer frequently migrates chunks. This is normal if the count eventually falls to 0 and does not remain elevated for a long time.

Balancing can also be triggered automatically when the data volume difference between collections exceeds the default threshold, such as 200 MB. This process can temporarily create orphaned documents.

If orphaned documents persist, check the balancer logs for migration errors and verify that the shard key distributes data evenly. After all chunk migrations complete, run cleanupOrphaned to remove the remaining orphaned documents.