Add proactive RegionGroup allocation and policy hot reload by d-wang-commit · Pull Request #18692 · apache/iotdb

d-wang-commit · 2026-09-22T06:13:09Z

Description

Policy use cases

The configuration template describes the intended scenarios as follows (quoted verbatim).

SchemaRegionGroups/DataRegionGroups:

# 1. CUSTOM: For known workloads that need manual resource allocation; creates the configured target
#    number of SchemaRegionGroups per Database when schema partitions are first allocated.
# 2. AUTO: For most routine workloads (roughly 80% as an approximate planning guideline); gradually
#    meets the configured minimum and expands with slot occupancy up to the resource-based maximum,
#    balancing parallelism and RegionGroup management overhead.
# 3. PROACTIVE: Complements AUTO where it does not expand eagerly enough, such as very few devices with
#    many measurements and a high load; creates groups earlier for more parallelism at the cost of
#    additional RegionGroup management overhead.

Proactive RegionGroup allocation

Sparse databases can keep using only a few RegionGroups under AUTO even when resources are available. Add PROACTIVE for SchemaRegionGroups and DataRegionGroups, and make it the default in ConfigNodeConfig and the configuration template.

PROACTIVE counts distinct persisted and pending series slots separately for schema and data. It grows toward one group per active slot, respects the resource-derived maximum, and follows AUTO's configured minimum. If all groups of the requested type are disabled, one RegionGroup can be allocated within the maximum.

For data allocation and recovery, calculate the retained-slot limit from active assignments, with a minimum of one, instead of the total configured slot count. With 1,000 slots and six active devices, switching from AUTO (with two existing groups) to PROACTIVE can grow to six groups: each old group retains 1 slot and 4 slots (got unassigned first) then use the 4 new groups for new partitions.

Policy hot reload

Transition	Existing < target	Existing = target	Existing > target
AUTO -> PROACTIVE	Expand toward active-slot target	Keep groups	Keep groups; no shrink
PROACTIVE -> AUTO	Grow only when AUTO requires	Keep groups	Keep groups; no shrink
CUSTOM -> PROACTIVE	Refresh cap; expand as needed	Keep groups	Keep groups; no shrink
CUSTOM -> AUTO	Refresh cap; follow AUTO rules	Keep groups	Keep groups; no shrink
AUTO/PROACTIVE -> CUSTOM	Expand to stored maximum	Keep groups	Lower target is rejected

Leaving CUSTOM refreshes resource caps in all cases.
CUSTOM's maximum cannot be lowered, even to the current group count.
Expansion requires subsequent partition allocation; historical partitions stay unchanged.

Tests

Added UTs:

PartitionManagerProactiveExtensionTest: distinct slots, minimum growth, batching, caps, unavailable groups, policy switches, and failed-allocation retries.
DataPartitionPolicyTableProactiveTest: sparse assignment, use of new groups, recovery, and AUTO/CUSTOM compatibility.
RegionGroupExtensionPolicyConfigTest: parsing, invalid values, file loading, and independent hot reload.

Existing ClusterSchemaManagerTest and DataPartitionPolicyTableTest provide resource-limit and allocation regression coverage.

Added ITs:

IoTDBProactiveRegionGroupDistributionIT: AUTO/PROACTIVE comparisons on 1C3D, 1C6D, and 1C9D; replication, SQL reads/writes, hot reload, new time partitions, and ConfigNode restart. Six targeted hot-reload cases cover AUTO/CUSTOM/PROACTIVE transitions and preserved historical mappings.
IoTDBProactiveRegionGroupExtensionIT: five topology/consensus combinations covering partition counts, shared slots, caps, ConfigNode recovery, and mapping retention.

The recorded local targeted run completed with 65 UT cases (0 failures, 0 errors, 3 skipped) and all six hot-reload IT cases passing. The topology matrix and existing IoTDBPartitionInheritStrategyIT were not part of that run.

Side effects and risks

Changing the default from AUTO to PROACTIVE can create more RegionGroups earlier, increasing consensus, memory, and storage overhead within resource limits. Explicit AUTO and CUSTOM settings remain available. Policy changes can affect placement of newly allocated partitions, but do not migrate historical data or shrink existing groups. Allocation may still fail when insufficient DataNodes are available.

This PR has:

added documentation for new or modified features or behaviors.
added comments explaining the "why" and the intent of the code wherever would not be obvious
for an unfamiliar reader.
added integration tests.
been tested in a test IoTDB cluster.

Key changed/added classes (or packages if there are too many classes) in this PR

RegionGroupExtensionPolicy and ConfigNodeConfig: PROACTIVE policy and defaults.
PartitionManager, PartitionInfo, and DatabasePartitionTable: distinct-slot counting and bounded proactive allocation.
DataPartitionPolicyTable: active-slot-based retention during balancing and recovery.
ConfigManager: refresh resource-derived maxima after policy hot reload.
New proactive/configuration UTs and proactive distribution/extension ITs: allocation and switching coverage.

Copilot

Copilot review overview

🟡 Changes recommended

One or more issues must be addressed before approval.

Get a fresh assessment by requesting another Copilot review.

Review effort: Lite
Findings: 1

Open (1)

Deduplicate pending slots in minimum-growth calculation · New

What changed in this PR

Adds proactive Schema/Data RegionGroup allocation and policy hot reload, with slot-aware balancing and recovery behavior.

Changes:

Adds PROACTIVE policy, defaults, and documentation.
Implements distinct-slot allocation and active-slot retention.
Adds hot-reload handling plus extensive unit/integration tests.

File	Description
iotdb-core/node-commons/src/assembly/resources/conf/iotdb-system.properties.template	Updated as part of this pull request.
iotdb-core/confignode/src/test/java/org/apache/iotdb/confignode/manager/partition/PartitionManagerProactiveExtensionTest.java	Updated as part of this pull request.
iotdb-core/confignode/src/test/java/org/apache/iotdb/confignode/manager/load/balancer/partition/DataPartitionPolicyTableProactiveTest.java	Updated as part of this pull request.
iotdb-core/confignode/src/test/java/org/apache/iotdb/confignode/conf/RegionGroupExtensionPolicyConfigTest.java	Updated as part of this pull request.
iotdb-core/confignode/src/main/java/org/apache/iotdb/confignode/persistence/partition/PartitionInfo.java	Updated as part of this pull request.
iotdb-core/confignode/src/main/java/org/apache/iotdb/confignode/persistence/partition/DatabasePartitionTable.java	Updated as part of this pull request.
iotdb-core/confignode/src/main/java/org/apache/iotdb/confignode/manager/partition/RegionGroupExtensionPolicy.java	Updated as part of this pull request.
iotdb-core/confignode/src/main/java/org/apache/iotdb/confignode/manager/partition/PartitionManager.java	Updated as part of this pull request.
iotdb-core/confignode/src/main/java/org/apache/iotdb/confignode/manager/load/balancer/partition/DataPartitionPolicyTable.java	Updated as part of this pull request.
iotdb-core/confignode/src/main/java/org/apache/iotdb/confignode/manager/ConfigManager.java	Updated as part of this pull request.
iotdb-core/confignode/src/main/java/org/apache/iotdb/confignode/conf/ConfigNodeConfig.java	Updated as part of this pull request.
integration-test/src/test/java/org/apache/iotdb/confignode/it/partition/IoTDBProactiveRegionGroupExtensionIT.java	Updated as part of this pull request.
integration-test/src/test/java/org/apache/iotdb/confignode/it/partition/IoTDBProactiveRegionGroupDistributionIT.java	Updated as part of this pull request.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

CRZbulabula

PTAL.

CRZbulabula

LGTM!

Copilot

Copilot review overview

🟡 Changes recommended

Empty partition entries can cause incorrect proactive RegionGroup allocation.

Get a fresh assessment by requesting another Copilot review.

Review effort: Lite
Findings: 1

Open (1)

Exclude empty partition tables from proactive RegionGroup counting · New

Resolved since last review (1)

Deduplicate pending slots in minimum-growth calculation

…to the maximum RegionGroup number. Cover allocation, recovery, and policy switching with unit and integration tests.

Copilot

Copilot review overview

🟡 Changes recommended

One or more issues must be addressed before approval.

Get a fresh assessment by requesting another Copilot review.

Review effort: Lite
Findings: 1

Open (1)

Unknown group status is misclassified as disabled during recovery · New

Resolved since last review (1)

Exclude empty partition tables from proactive RegionGroup counting

d-wang-commit · 2026-09-23T02:37:09Z

+          && partitionInfo.getAllRegionGroupIds(database, consensusGroupType).stream()
+              .allMatch(
+                  regionGroupId ->
+                      RegionGroupStatus.Disabled.equals(
+                          getLoadManager().getRegionGroupStatus(regionGroupId)))) {


The max region group number caps any extra allocation. Also, a successfully created group is immediately activated, so subsequent requests no longer satisfy the “all disabled” condition. Given the bounded impact, we’ll keep the current implementation

CRZbulabula requested a lite review from Copilot September 22, 2026 06:22

Copilot started reviewing on behalf of CRZbulabula September 22, 2026 06:22 View session

Copilot AI reviewed Sep 22, 2026

View reviewed changes

Comment thread ...confignode/src/main/java/org/apache/iotdb/confignode/manager/partition/PartitionManager.java Outdated

CRZbulabula requested changes Sep 22, 2026

View reviewed changes

Comment thread .../src/main/java/org/apache/iotdb/confignode/persistence/partition/DatabasePartitionTable.java

d-wang-commit force-pushed the add_proactive_region_group_extension_policy branch 2 times, most recently from 8088887 to d54ff28 Compare September 22, 2026 10:42

CRZbulabula approved these changes Sep 22, 2026

View reviewed changes

CRZbulabula requested a lite review from Copilot September 22, 2026 13:27

Copilot started reviewing on behalf of CRZbulabula September 22, 2026 13:27 View session

Copilot AI reviewed Sep 22, 2026

View reviewed changes

Comment thread .../src/main/java/org/apache/iotdb/confignode/persistence/partition/DatabasePartitionTable.java Outdated

Make PROACTIVE the default and grow groups by active series slots up …

22231b1

…to the maximum RegionGroup number. Cover allocation, recovery, and policy switching with unit and integration tests.

d-wang-commit force-pushed the add_proactive_region_group_extension_policy branch from d54ff28 to 22231b1 Compare September 22, 2026 15:09

CRZbulabula requested a lite review from Copilot September 23, 2026 01:40

Copilot started reviewing on behalf of CRZbulabula September 23, 2026 01:40 View session

Copilot AI reviewed Sep 23, 2026

View reviewed changes

d-wang-commit marked this pull request as draft September 23, 2026 03:08

Navigation Menu

Add proactive RegionGroup allocation and policy hot reload - #18692

Add proactive RegionGroup allocation and policy hot reload#18692
d-wang-commit wants to merge 1 commit into
apache:masterfrom
d-wang-commit:add_proactive_region_group_extension_policy

d-wang-commit commented Sep 22, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

CRZbulabula left a comment

Uh oh!

Uh oh!

CRZbulabula left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

d-wang-commit Sep 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

d-wang-commit commented Sep 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Policy use cases

Proactive RegionGroup allocation

Policy hot reload

Tests

Side effects and risks

Key changed/added classes (or packages if there are too many classes) in this PR

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot review overview

🟡 Changes recommended

Uh oh!

Uh oh!

CRZbulabula left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

CRZbulabula left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot review overview

🟡 Changes recommended

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot review overview

🟡 Changes recommended

Uh oh!

d-wang-commit Sep 23, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

d-wang-commit commented Sep 22, 2026 •

edited

Loading