Skip to content

table-affinity: clarify scheduling microservice version support #24206

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
lhy1024 wants to merge 5 commits into
base: master
Choose a base branch
from
Open

table-affinity: clarify scheduling microservice version support #24206

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
ef5d754
table-affinity: clarify scheduling microservice version support
lhy1024 Oct 8, 2026
40344f0
table-affinity: describe microservice support positively
lhy1024 Oct 8, 2026
43e2afa
table-affinity: use verified microservice support version
lhy1024 Oct 8, 2026
1d64d5f
table-affinity: distinguish deployment mode support versions
lhy1024 Oct 8, 2026
e70d552
table-affinity: correct microservice support version
lhy1024 Oct 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion table-affinity.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,11 +13,12 @@ Table-level data affinity is a PD mechanism for scheduling data distribution at

When you enable PD affinity scheduling and set the `AFFINITY` option of a table to `table` or `partition`, PD groups Regions belonging to the same table or partition into the same affinity group. During scheduling, PD prioritizes placing the Leader and Voter replicas of these Regions on the same subset of a few TiKV nodes. This reduces network latency caused by cross-node access during queries, thereby improving query performance.

Table-level data affinity is available starting from v8.5.5 when PD is not deployed in [PD Microservices Mode](/pd-microservices.md). Starting from v8.5.7, it is also available in PD Microservices Mode when scheduling is handled by the scheduling microservice.

@coderabbitai coderabbitai Bot Oct 8, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

🔎 Supported by static analysis

🏁 Script executed:

set -u
printf '%s\n' '--- changed file context ---'
nl -ba table-affinity.md | sed -n '10,30p'
printf '%s\n' '--- PR diff for the file ---'
git diff --no-ext-diff --unified=12 6ba85765e2f9e8d080a7f1789a3b46641a09d960 e70d552cc8e7dba3ee7c458c6080e2bc4a7660ea -- table-affinity.md
printf '%s\n' '--- local predicate/source references ---'
rg -n -F --glob '!node_modules/**' --glob '!dist/**' --glob '!build/**' -- 'affinityRegionSizeBufferMB' . || test "$?" -eq 1
rg -n -F --glob '!node_modules/**' --glob '!dist/**' --glob '!build/**' -- 'ApproximateKeys' . || test "$?" -eq 1
printf '%s\n' '--- splitting wording references ---'
rg -n -F -- 'four times' . || test "$?" -eq 1

Repository: pingcap/docs

Length of output: 7915

🌐 Web query:

site:github.com/tikv/pd v8.5.7 pkg/schedule/affinity/split.go grpc_service.go MCS scheduling affinity split

💡 Result:

In **PD v8.5.7**, affinity split handling is split across these files:

- [`pkg/schedule/affinity/split.go`](https://github.com/tikv/pd/blob/v8.5.7/pkg/schedule/affinity/split.go): `Manager.AllowSplit` allows splitting for nil regions, admin splits, or when affinity scheduling is disabled. For affinity regions where regular scheduling is disallowed, it blocks automatic splits below a size/key threshold; larger regions may still split. ([raw.githubusercontent.com](https://raw.githubusercontent.com/tikv/pd/v8.5.7/pkg/schedule/affinity/split.go))
- [`pkg/mcs/scheduling/server/grpc_service.go`](https://github.com/tikv/pd/blob/v8.5.7/pkg/mcs/scheduling/server/grpc_service.go): `AskBatchSplit` calls `AllowSplit`. If denied, it disables auto-splitting for the region and returns `"cannot split affinity region"`; otherwise it allocates the new region and peer IDs. ([raw.githubusercontent.com](https://raw.githubusercontent.com/tikv/pd/v8.5.7/pkg/mcs/scheduling/server/grpc_service.go))
- [`server/grpc_service.go`](https://github.com/tikv/pd/blob/v8.5.7/server/grpc_service.go) is the PD server’s separate gRPC implementation. The MCS scheduling split path is in `pkg/mcs/scheduling/server/grpc_service.go`, not this file. ([raw.githubusercontent.com](https://raw.githubusercontent.com/tikv/pd/v8.5.7/server/grpc_service.go))

These links and findings are for the **v8.5.7** tag.

Citations:

- 1: https://raw.githubusercontent.com/tikv/pd/v8.5.7/pkg/schedule/affinity/split.go
- 2: https://raw.githubusercontent.com/tikv/pd/v8.5.7/pkg/mcs/scheduling/server/grpc_service.go
- 3: https://raw.githubusercontent.com/tikv/pd/v8.5.7/server/grpc_service.go

Document both automatic-splitting triggers for MCS.

The new availability statement makes the automatic-splitting note apply to MCS. In v8.5.7, AskBatchSplit calls AllowSplit, which permits splitting when approximate size reaches (configured merge size + 10 MiB) × 4 or approximate key count reaches its threshold. The current “only when ... exceeds four times” wording can cause operators to miss key-count-triggered splits and use an incorrect size threshold.

Suggested fix 
-- **Automatic splitting of Regions**: when a Region belongs to an affinity group and affinity is in effect, automatic splitting of that Region is disabled by default to avoid the creation of too many Regions that could weaken the affinity effect. Automatic splitting is triggered only when the Region size exceeds four times the value of [`schedule.max-affinity-merge-region-size`](/pd-configuration-file.md#max-affinity-merge-region-size-new-in-v855-and-v900). Note that splits triggered by components other than TiKV or PD (such as manual splits triggered by [`SPLIT TABLE`](/sql-statements/sql-statement-split-region.md)) are not subject to this restriction.
+- **Automatic splitting of Regions**: when a Region belongs to an affinity group and affinity is in effect, automatic splitting of that Region is disabled by default to avoid the creation of too many Regions that could weaken the affinity effect. Automatic splitting is triggered when the Region's approximate size reaches four times the value of [`schedule.max-affinity-merge-region-size`](/pd-configuration-file.md#max-affinity-merge-region-size-new-in-v855-and-v900) plus the 10 MiB buffer, or when its approximate key count reaches the configured threshold. Note that splits triggered by components other than TiKV or PD (such as manual splits triggered by [`SPLIT TABLE`](/sql-statements/sql-statement-split-region.md)) are not subject to this restriction.


## Limitations

Before using table-level data affinity, note the following limitations:

- This feature does not take effect in [PD Microservices Mode](/pd-microservices.md).
- This feature does not work with [Temporary tables](/temporary-tables.md) and [views](/views.md).
- After data affinity is configured for a [partitioned table](/partitioned-table.md), **modifying the table partitioning scheme is not supported**, including adding, dropping, reorganizing, or swapping partitions. To change the partitioning scheme, you must first remove the affinity configuration for that table.
- **Evaluate disk capacity in advance for large data volumes**: after affinity is enabled, PD prioritizes scheduling Regions of a table or partition to the same subset of a few TiKV nodes. For tables or partitions with large data volumes, this might significantly increase disk usage on these nodes. It is recommended to evaluate disk capacity and monitor it in advance.
Expand Down
Loading