Manage the ApsaraDB for MongoDB balancer - ApsaraDB for MongoDB

If you want to add or delete shards to or from an ApsaraDB for MongoDB sharded cluster instance or migrate data, you may need to change the active time window of the balancer or specify whether to enable or disable the balancer. This topic describes how to manage the balancer.

Feature description

The balancer can balance data among shard nodes in a sharded cluster instance. The working principle of the balancer varies based on the version of the ApsaraDB for MongoDB instance.

MongoDB 5.0 and earlier versions

The balancer monitors the number of chunks on each shard node in a sharded cluster instance. When the number of chunks on a shard node reaches a specified data migration threshold, the balancer migrates the chunks on the shard node (moveChunk) to other shard nodes to balance the distribution of chunks across all shard nodes. The data migration threshold varies based on the instance version. The following table describes the data migration thresholds for different instance versions.

Database engine version	Data migration threshold
MongoDB 3.2 (discontinued)	If the total number of chunks is less than 20, the data migration threshold is 2. If the total number of chunks ranges from 20 to 80, the data migration threshold is 4. If the total number of chunks is greater than or equal to 80, the data migration threshold is 8.
MongoDB 3.4 (discontinued) MongoDB 4.0	The default data migration threshold is 2. If the total number of chunks is less than 20, or if the total number of chunks that were previously migrated is less than 20, the data migration threshold is 1.
MongoDB 4.2 MongoDB 4.4 MongoDB 5.0	The data migration threshold is 1.

MongoDB 6.0
The existence of jumbo chunks may result in the following issue: The number of chunks on each shard node is the same, but the space usage on each shard node is different. To resolve this issue, the balancer monitors the data size in the same collection on each shard node in a sharded cluster instance of ApsaraDB for MongoDB 6.0 or later. If the difference in data size between two shard nodes in the same collection exceeds 384 MB (three times the chunk size), the balancer splits the data by shard tag and migrates the data to another shard node (moveRange).
To determine whether data is balanced, you can run the getShardDistribution() command to view the distribution of data in a collection. Instead of focusing on the logical concept of chunks, you need to only focus on the data size of the collection.

Usage notes

The balancer is supported only for sharded cluster instances.
By default, the balancer is enabled. For more information about how to enable the balancer, see Enable the balancer.
By default, the active time window of the balancer is 24 hours. When the balancer migrates chunks, the database performance may be degraded. To avoid the impact of chunk migration on your business, we recommend that you change the active time window of the balancer to off-peak hours. For more information about how to set an active time window, see Set an active window for the balancer.
In examples given in this topic, the mongo shell is used to manage the balancer. The methods that other client tools use to manage the balancer and returned information may differ from those in these examples.

Set an active time window for the balancer

Connect to an ApsaraDB for MongoDB sharded cluster instance by using the mongo shell
After you connect to a mongos node, run the following command in the mongo shell to switch to the config database:
```
use config
```
Run the following command to set an active time window for the balancer:
```
db.settings.update(
   { _id: "balancer" },
   { $set: { activeWindow : { start : "<start-time>", stop : "<stop-time>" } } },
   { upsert: true }
)
```
Note
- <start-time>: the start time of the active time window. Specify the time in the HH:MM format. The HH value ranges from 00 to 23, and the MM value ranges from 00 to 59. This format indicates the local time of the region in which the instance is deployed.
- <stop-time>: the end time of the active time window. Specify the time in the HH:MM format. The HH value ranges from 00 to 23, and the MM value ranges from 00 to 59. This format indicates the local time of the region in which the instance is deployed.
For example, you must change the active time window of the balancer to 1 am to 3 am every day. Sample command:
```
db.settings.update(
   { _id: "balancer" },
   { $set: { activeWindow : { start : "01:00", stop : "03:00" } } },
   { upsert: true }
)
```
After you complete the configurations, you can run the sh.status() command to view the active time window of the balancer. Sample results:

Related operation: If you want the balancer to be always in the Running state, run the following command to delete the settings of the active time window:

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

Enable the balancer

If you have configured sharding, the balancer can immediately start a balancing procedure among shard nodes after the balancer is enabled. Balancing occupies the resources of an instance. Therefore, we recommend that you perform this operation during off-peak hours.

Connect to an ApsaraDB for MongoDB sharded cluster instance by using the mongo shell
After you connect to a mongos node, run the following command in the mongo shell to switch to the config database:
```
use config
```
Run the following command to enable the balancer:
```
sh.setBalancerState(true)
```

Disable the balancer

By default, the balancer is enabled. To temporarily disable the balancer, perform the following steps.

Note

After the balancer is disabled, the balancer no longer balances data across shard nodes. This may cause data skew.

Connect to an ApsaraDB for MongoDB sharded cluster instance by using the mongo shell
After you connect to a mongos node, run the following command in the mongo shell to switch to the config database:
```
use config
```
Run the sh.isBalancerRunning() command to view the running status of the balancer.
The sh.isBalancerRunning() command returns a Boolean or Map value based on the version of the mongo shell client.
- Boolean
  - If the value false is returned, the balancer does not perform tasks. In this case, you can disable the balancer.
  - If the value true is returned, the balancer performs a chunk migration task. In this case, you cannot disable the balancer. Otherwise, data inconsistency may occur.
- Map
```
{
  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 })
}
```
  - If the inBalancerRound parameter is set to false, the balancer does not perform tasks. In this case, you can disable the balancer.
  - If the inBalancerRound parameter is set to true, the balancer performs a chunk migration task. In this case, you cannot disable the balancer. Otherwise, data inconsistency may occur.
For more information about the sh.isBalancerRunning() command, see sh.isBalancerRunning().
After you confirm that no output is returned for this command in the preceding step, run the following command to disable the balancer:
```
sh.stopBalancer()
```