From 92949ea063e04be95cc24968cedb94a436b34f97 Mon Sep 17 00:00:00 2001 From: lhy1024 Date: Mon, 22 Dec 2025 17:09:14 +0800 Subject: [PATCH 01/30] pd,tidb:: support affinity schedule Signed-off-by: lhy1024 --- TOC.md | 2 + .../information-schema-partitions.md | 5 +- .../information-schema-tables.md | 18 ++++- pd-configuration-file.md | 11 +++ sql-statements/sql-statement-alter-table.md | 2 + sql-statements/sql-statement-create-table.md | 3 + sql-statements/sql-statement-show-affinity.md | 54 +++++++++++++ table-affinity.md | 78 +++++++++++++++++++ 8 files changed, 169 insertions(+), 4 deletions(-) create mode 100644 sql-statements/sql-statement-show-affinity.md create mode 100644 table-affinity.md diff --git a/TOC.md b/TOC.md index 79adf0d7ef7f..6c170c7c72ee 100644 --- a/TOC.md +++ b/TOC.md @@ -882,6 +882,7 @@ - [`SET ROLE`](/sql-statements/sql-statement-set-role.md) - [`SET TRANSACTION`](/sql-statements/sql-statement-set-transaction.md) - [`SET `](/sql-statements/sql-statement-set-variable.md) + - [`SHOW AFFINITY`](/sql-statements/sql-statement-show-affinity.md) - [`SHOW [BACKUPS|RESTORES]`](/sql-statements/sql-statement-show-backups.md) - [`SHOW ANALYZE STATUS`](/sql-statements/sql-statement-show-analyze-status.md) - [`SHOW BINDINGS`](/sql-statements/sql-statement-show-bindings.md) @@ -999,6 +1000,7 @@ - [临时表](/temporary-tables.md) - [缓存表](/cached-tables.md) - [外键约束](/foreign-key.md) + - [表级数据亲和性](/table-affinity.md) - 字符集和排序规则 - [概述](/character-set-and-collation.md) - [GBK](/character-set-gbk.md) diff --git a/information-schema/information-schema-partitions.md b/information-schema/information-schema-partitions.md index 007113f7b1b1..976fb655bcc9 100644 --- a/information-schema/information-schema-partitions.md +++ b/information-schema/information-schema-partitions.md @@ -45,8 +45,9 @@ DESC PARTITIONS; | TABLESPACE_NAME | varchar(64) | YES | | NULL | | | TIDB_PARTITION_ID | bigint(21) | YES | | NULL | | | TIDB_PLACEMENT_POLICY_NAME | varchar(64) | YES | | NULL | | +| TIDB_AFFINITY | varchar(128) | YES | | NULL | | +-------------------------------+--------------+------+------+---------+-------+ -27 rows in set (0.00 sec) +28 rows in set (0.00 sec) ``` ```sql @@ -85,6 +86,7 @@ SUBPARTITION_ORDINAL_POSITION: NULL TABLESPACE_NAME: NULL TIDB_PARTITION_ID: 89 TIDB_PLACEMENT_POLICY_NAME: NULL + TIDB_AFFINITY: NULL *************************** 2. row *************************** TABLE_CATALOG: def TABLE_SCHEMA: test @@ -113,6 +115,7 @@ SUBPARTITION_ORDINAL_POSITION: NULL TABLESPACE_NAME: NULL TIDB_PARTITION_ID: 90 TIDB_PLACEMENT_POLICY_NAME: NULL + TIDB_AFFINITY: NULL 2 rows in set (0.00 sec) ``` diff --git a/information-schema/information-schema-tables.md b/information-schema/information-schema-tables.md index ff7ac01c5887..c9e2faddf7e8 100644 --- a/information-schema/information-schema-tables.md +++ b/information-schema/information-schema-tables.md @@ -41,8 +41,12 @@ DESC tables; | TABLE_COMMENT | varchar(2048) | YES | | NULL | | | TIDB_TABLE_ID | bigint(21) | YES | | NULL | | | TIDB_ROW_ID_SHARDING_INFO | varchar(255) | YES | | NULL | | +| TIDB_PK_TYPE | varchar(64) | YES | | NULL | | +| TIDB_PLACEMENT_POLICY_NAME | varchar(64) | YES | | NULL | | +| TIDB_TABLE_MODE | varchar(16) | YES | | NULL | | +| TIDB_AFFINITY | varchar(128) | YES | | NULL | | +---------------------------+---------------+------+------+----------+-------+ -23 rows in set (0.00 sec) +27 rows in set (0.00 sec) ``` {{< copyable "sql" >}} @@ -75,7 +79,11 @@ SELECT * FROM tables WHERE table_schema='mysql' AND table_name='user'\G CREATE_OPTIONS: TABLE_COMMENT: TIDB_TABLE_ID: 5 -TIDB_ROW_ID_SHARDING_INFO: NULL + TIDB_ROW_ID_SHARDING_INFO: NULL + TIDB_PK_TYPE: CLUSTERED + TIDB_PLACEMENT_POLICY_NAME: NULL + TIDB_TABLE_MODE: Normal + TIDB_AFFINITY: NULL 1 row in set (0.00 sec) ``` @@ -115,7 +123,7 @@ SHOW TABLES * `CREATE_OPTIONS`：创建选项。 * `TABLE_COMMENT`：表的注释、备注。 -表中的信息大部分定义自 MySQL，只有两列是 TiDB 新增的： +表中的信息大部分定义自 MySQL，以下列为 TiDB 新增： * `TIDB_TABLE_ID`：标识表的内部 ID，该 ID 在一个 TiDB 集群内部唯一。 * `TIDB_ROW_ID_SHARDING_INFO`：标识表的 Sharding 类型，可能的值为： @@ -124,3 +132,7 @@ SHOW TABLES - `"PK_AUTO_RANDOM_BITS={bit_number}"`：一个定义了整型主键的表由于定义了 `AUTO_RANDOM` 而被 Shard。 - `"SHARD_BITS={bit_number}"`：表使用 `SHARD_ROW_ID_BITS={bit_number}` 进行了 Shard。 - NULL：表属于系统表或 View，无法被 Shard。 +* `TIDB_PK_TYPE`：表的主键类型，可能的值包括 `CLUSTERED`（聚簇主键）和 `NONCLUSTERED`。 +* `TIDB_PLACEMENT_POLICY_NAME`：应用于该表的放置策略名称。 +* `TIDB_TABLE_MODE`：表的模式，例如 `Normal`、`Import` 或 `Restore`。 +* `TIDB_AFFINITY`：表的亲和性等级，非分区表为 `table`，分区表为 `partition`，未开启亲和性时为 NULL。 diff --git a/pd-configuration-file.md b/pd-configuration-file.md index 27baea8258f2..894e1f5857d4 100644 --- a/pd-configuration-file.md +++ b/pd-configuration-file.md @@ -287,6 +287,12 @@ pd-server 相关配置项。 + 控制 Region Merge 的 key 上限，当 Region key 大于指定值时 PD 不会将其与相邻的 Region 合并。 + 默认：540000。在 v8.4.0 之前，默认值为 200000；从 v8.4.0 开始，默认值为 540000。 +### `max-affinity-merge-region-size` 从 v8.5.5 版本开始引入 + ++ 当 Region 属于亲和性分组且大小小于该值时，PD 会尝试将其与相邻的同一亲和性分组的 Region 合并。设置为 `0` 表示关闭配置了亲和性的 Region 合并。 ++ 默认：256 ++ 单位：MiB + ### `patrol-region-interval` + 控制 checker 检查 Region 健康状态的运行频率，越短则运行越快，通常状况不需要调整 @@ -362,6 +368,11 @@ pd-server 相关配置项。 + 同时进行的 Region Merge 调度的任务，设置为 0 则关闭 Region Merge。 + 默认值：8 +### `affinity-schedule-limit` 从 v8.5.5 版本开始引入 + ++ 控制同时进行的亲和性调度任务数量。设置为 `0` 表示禁用亲和性调度。 ++ 默认值：0 + ### `high-space-ratio` + 设置 store 空间充裕的阈值。当节点的空间占用比例小于该阈值时，PD 调度时会忽略节点的剩余空间，主要根据实际数据量进行均衡。此配置仅在 `region-score-formula-version = v1` 时生效。 diff --git a/sql-statements/sql-statement-alter-table.md b/sql-statements/sql-statement-alter-table.md index 91701dbda670..5fc6ee3761f6 100644 --- a/sql-statements/sql-statement-alter-table.md +++ b/sql-statements/sql-statement-alter-table.md @@ -54,6 +54,7 @@ AlterTableSpec ::= | TTLEnable EqOpt ( 'ON' | 'OFF' ) | TTLJobInterval EqOpt stringLit ) +| 'AFFINITY' EqOpt stringLit | PlacementPolicyOption PlacementPolicyOption ::= @@ -172,6 +173,7 @@ TiDB 中的 `ALTER TABLE` 语法主要存在以下限制： - 不支持分区表上的列类型变更。 - 不支持生成列上的列类型变更。 - 不支持部分数据类型（例如，部分时间类型、Bit、Set、Enum、JSON 等）的变更，因为 TiDB 中的 `CAST` 函数与 MySQL 的行为存在兼容性问题。 +- `AFFINITY` 选项为 TiDB 扩展语法。开启 `AFFINITY` 后，不支持变更该表的分区方案（如添加、删除、重组或交换分区），需要先移除 `AFFINITY`。 - 不支持空间数据类型。 - `ALTER TABLE t CACHE | NOCACHE` 不是 MySQL 标准语法，而是 TiDB 扩展功能，参见[缓存表](/cached-tables.md)。 diff --git a/sql-statements/sql-statement-create-table.md b/sql-statements/sql-statement-create-table.md index 7b4fdd224fc3..bc39944d1ed9 100644 --- a/sql-statements/sql-statement-create-table.md +++ b/sql-statements/sql-statement-create-table.md @@ -117,6 +117,7 @@ TableOption ::= | 'UNION' EqOpt '(' TableNameListOpt ')' | 'ENCRYPTION' EqOpt EncryptionOpt | 'TTL' EqOpt TimeColumnName '+' 'INTERVAL' Expression TimeUnit (TTLEnable EqOpt ( 'ON' | 'OFF' ))? (TTLJobInterval EqOpt stringLit)? +| 'AFFINITY' EqOpt StringName | PlacementPolicyOption OnCommitOpt ::= @@ -170,10 +171,12 @@ TiDB 支持以下 `table_option`。TiDB 会解析并忽略其他 `table_option` |`CHARACTER SET` |指定该表所使用的[字符集](/character-set-and-collation.md) | `CHARACTER SET` = 'utf8mb4'| |`COLLATE` |指定该表所使用的字符集排序规则 | `COLLATE` = 'utf8mb4_bin'| |`COMMENT` |注释信息 | `COMMENT` = 'comment info'| +|`AFFINITY` |为表或分区开启亲和性调度。非分区表可设置为 `'table'`，分区表可设置为 `'partition'`；设置为 `'none'` 或留空可关闭 |`AFFINITY` = 'table'| > **注意：** > > 在 TiDB 配置文件中，`split-table` 默认开启。当该配置项开启时，建表操作会为每个表建立单独的 Region，详情参见 [TiDB 配置文件描述](/tidb-configuration-file.md)。 +> 使用 `AFFINITY` 时，当前不支持对该表进行分区方案变更（如添加、删除、重组或交换分区），也不支持在临时表或视图上设置该选项。 ## 示例 diff --git a/sql-statements/sql-statement-show-affinity.md b/sql-statements/sql-statement-show-affinity.md new file mode 100644 index 000000000000..403d805ace70 --- /dev/null +++ b/sql-statements/sql-statement-show-affinity.md @@ -0,0 +1,54 @@ +--- +title: SHOW AFFINITY +summary: 介绍 TiDB 数据库中 SHOW AFFINITY 的使用概况。 +--- + +# SHOW AFFINITY 从 v8.5.5 开始引入 + +`SHOW AFFINITY` 语句用于查看开启了 `AFFINITY` 选项的表或分区的亲和性调度信息，以及 PD 当前记录的目标副本分布。 + +## 语法图 + +```ebnf+diagram +ShowAffinityStmt ::= + "SHOW" "AFFINITY" ShowLikeOrWhereOpt +``` + +`SHOW AFFINITY` 支持使用 `LIKE` 或 `WHERE` 过滤表名。 + +## 示例 + +```sql +CREATE TABLE t1 (a INT) AFFINITY = 'table'; +CREATE TABLE tp1 (a INT) AFFINITY = 'partition' PARTITION BY HASH(a) PARTITIONS 2; + +SHOW AFFINITY; +``` + +输出结果类似于： + +```sql ++---------+------------+----------------+-----------------+------------------+----------+--------------+----------------------+ +| Db_name | Table_name | Partition_name | Leader_store_id | Voter_store_ids | Status | Region_count | Affinity_region_count| ++---------+------------+----------------+-----------------+------------------+----------+--------------+----------------------+ +| test | t1 | NULL | 1 | 1,2,3 | Stable | 8 | 8 | +| test | tp1 | p0 | 4 | 4,5,6 | Preparing| 4 | 2 | +| test | tp1 | p1 | 4 | 4,5,6 | Preparing| 3 | 2 | ++---------+------------+----------------+-----------------+------------------+----------+--------------+----------------------+ +``` + +各列含义如下： + +- `LEADER_STORE_ID`、`VOTER_STORE_IDS`：PD 为该表或分区记录的目标 Leader 副本和 Voter 副本所在的 store ID。当亲和性尚未确定时显示为 `NULL`。 +- `STATUS`：`Pending` 表示 PD 尚未进行亲和性调度，`Preparing` 表示正在调度 Region 以满足亲和性要求，`Stable` 表示所有 Region 已经达到目标分布。 +- `REGION_COUNT`：当前在该亲和性组中的 Region 数量。 +- `AFFINITY_REGION_COUNT`：已经满足亲和性副本分布的 Region 数量。 + +## MySQL 兼容性 + +该语句是 TiDB 对 MySQL 语法的扩展。 + +## 另请参阅 + +- [`CREATE TABLE`](/sql-statements/sql-statement-create-table.md) +- [`ALTER TABLE`](/sql-statements/sql-statement-alter-table.md) diff --git a/table-affinity.md b/table-affinity.md new file mode 100644 index 000000000000..1417c730f15c --- /dev/null +++ b/table-affinity.md @@ -0,0 +1,78 @@ +--- +title: 表级数据亲和性 +summary: 通过表或分区的亲和性约束，控制 Region 的副本分布并查看调度状态。 +--- + +# 表级数据亲和性 实验特性，自 v8.5.5 起提供 + +> **警告：** +> +> 该功能为实验特性，不建议在生产环境中使用。行为和接口可能在未来版本变更或移除。如遇问题，请在 GitHub 提交 [issue](https://github.com/pingcap/tidb/issues) 反馈。 + +表级数据亲和性用于将表或分区的 Region 归为同一亲和性分组，并让 PD 将这些 Region 的 Leader、Voter 优先调度到指定的 Store 上，减少跨节点分散带来的延迟。亲和性信息由 PD 维护，TiDB 通过 `AFFINITY` 表选项声明亲和性级别。 + +## 前置条件 + +- 集群版本：TiDB/PD/TiKV 均需为 v8.5.5 及以上的相互兼容版本。 +- 在 PD 侧开启调度：将 `schedule.affinity-schedule-limit` 设置为大于 0，否则亲和性调度不会生效。示例： + + ```bash + pd-ctl config set schedule.affinity-schedule-limit 4 + ``` + +- 可选：根据需要设置 `schedule.max-affinity-merge-region-size`（MiB），控制亲和性 Region 的合并阈值，设置为 `0` 表示关闭亲和性场景下的自动合并。 + +## 支持的亲和性级别 + +- 非分区表：`AFFINITY='table'`。 +- 分区表：`AFFINITY='partition'`，每个分区会生成独立的亲和性分组。 +- 取消亲和性：设置为 `AFFINITY=''` 或 `AFFINITY='none'`。 +- 不支持在临时表、视图上开启亲和性。 + +## 基本用法 + +1. **创建或修改表时声明亲和性** + + ```sql + CREATE TABLE t1 (a INT) AFFINITY = 'table'; + + CREATE TABLE tp1 (a INT) + AFFINITY = 'partition' + PARTITION BY HASH(a) PARTITIONS 4; + + ALTER TABLE t1 AFFINITY = 'table'; -- 开启 + ALTER TABLE t1 AFFINITY = ''; -- 关闭 + ``` + + 开启后，TiDB 会在 PD 中为表或分区自动创建亲和性分组，并向 PD 维护对应的 key range。 + +2. **查看调度状态** + + - `SHOW AFFINITY;` 展示当前已开启亲和性的表或分区及其在 PD 中记录的目标副本分布。`STATUS` 含义： + - `Pending`：PD 尚未开始进行亲和性调度（比如未确定 Leader/Voter）。 + - `Preparing`：正在调度 Region 以满足亲和性要求。 + - `Stable`：所有 Region 已达到目标分布。 + - INFORMATION_SCHEMA 也会暴露亲和性信息： + - `TABLES.TIDB_AFFINITY`：表级亲和性。 + - `PARTITIONS.TIDB_AFFINITY`：分区级亲和性。 + +## 调度行为与内部机制 + +- **自动分裂拦截**：当 Region 属于亲和性分组，- 亲和性生效时，Region 默认不进行自动分裂（除非大小或 key 数超过阈值），避免产生过多 Region 影响亲和性效果。手工 `ADMIN SPLIT` 不受此限制。 +- **降级与过期**：若分组目标的 Leader/Voter 所在 Store 不可用（如节点 down 、磁盘不足等），PD 会将分组标记为降级。若 10 分钟内未恢复，将自动过期并允许常规调度；此时亲和性调度暂停，`SHOW AFFINITY` 的状态会回到 `Pending`。恢复后可重新更新分组的 Leader/Voter 以重新启用亲和性。 + +## 限制与注意事项 + +- 开启亲和性后，**不支持修改分区方案**（如新增/删除/重组/交换分区）。如需调整分区，请先移除亲和性。 +- 临时表、视图不支持亲和性。 +- 亲和性调度依赖 PD 调度参数： + - `schedule.affinity-schedule-limit` 默认 0（关闭）。需显式配置后，PD 才会为亲和性分组创建调度任务。 + - `schedule.max-affinity-merge-region-size` 为亲和性 Region 的合并阈值；设置为 0 关闭亲和性合并。 +- 亲和性生效时，小于阈值的 Region 默认不进行自动分裂，手工 `ADMIN SPLIT` 仍可执行。 +- 当目标 Store 处于不可用、被驱逐 Leader、或与放置规则冲突时，PD 会将分组标记为降级或过期，亲和性调度暂停。恢复后可通过 `SHOW AFFINITY` 观察状态，必要时重新更新分组的 Leader/Voter。 + +## 相关语句与配置 + +- `CREATE TABLE` / `ALTER TABLE` 的 `AFFINITY` 选项。 +- `SHOW AFFINITY` 语句。 +- PD 调度参数：`schedule.affinity-schedule-limit`、`schedule.max-affinity-merge-region-size`。 From a3608948d06b6ed14c77fba776318e78921a9504 Mon Sep 17 00:00:00 2001 From: lhy1024 Date: Tue, 23 Dec 2025 16:34:59 +0800 Subject: [PATCH 02/30] address comments Signed-off-by: lhy1024 --- table-affinity.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/table-affinity.md b/table-affinity.md index 1417c730f15c..9529c1ffb09f 100644 --- a/table-affinity.md +++ b/table-affinity.md @@ -65,10 +65,12 @@ summary: 通过表或分区的亲和性约束，控制 Region 的副本分布并 - 开启亲和性后，**不支持修改分区方案**（如新增/删除/重组/交换分区）。如需调整分区，请先移除亲和性。 - 临时表、视图不支持亲和性。 +- **数据量较大时需注意磁盘空间**：开启亲和性后，PD 会将表或分区的 Region 调度到指定的少数 Store 上。如果表数据量较大，可能导致这些 Store 的磁盘占用显著增加，需提前评估磁盘容量并做好监控。 - 亲和性调度依赖 PD 调度参数： - `schedule.affinity-schedule-limit` 默认 0（关闭）。需显式配置后，PD 才会为亲和性分组创建调度任务。 - `schedule.max-affinity-merge-region-size` 为亲和性 Region 的合并阈值；设置为 0 关闭亲和性合并。 - 亲和性生效时，小于阈值的 Region 默认不进行自动分裂，手工 `ADMIN SPLIT` 仍可执行。 +- 不支持 Learner 副本的亲和性调度：如果表配置了包含 Learner 副本的放置规则（比如 TiFlash），亲和性调度不会对 Learner 副本生效，但不影响现有 Learner 副本的分布。 - 当目标 Store 处于不可用、被驱逐 Leader、或与放置规则冲突时，PD 会将分组标记为降级或过期，亲和性调度暂停。恢复后可通过 `SHOW AFFINITY` 观察状态，必要时重新更新分组的 Leader/Voter。 ## 相关语句与配置 From 37860a99a20a1b6693d5621ba939e8b3db949ed8 Mon Sep 17 00:00:00 2001 From: lhy1024 Date: Tue, 23 Dec 2025 19:08:50 +0800 Subject: [PATCH 03/30] address comments Signed-off-by: lhy1024 --- sql-statements/sql-statement-show-affinity.md | 2 +- table-affinity.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/sql-statements/sql-statement-show-affinity.md b/sql-statements/sql-statement-show-affinity.md index 403d805ace70..dfc4b0cbecb7 100644 --- a/sql-statements/sql-statement-show-affinity.md +++ b/sql-statements/sql-statement-show-affinity.md @@ -42,7 +42,7 @@ SHOW AFFINITY; - `LEADER_STORE_ID`、`VOTER_STORE_IDS`：PD 为该表或分区记录的目标 Leader 副本和 Voter 副本所在的 store ID。当亲和性尚未确定时显示为 `NULL`。 - `STATUS`：`Pending` 表示 PD 尚未进行亲和性调度，`Preparing` 表示正在调度 Region 以满足亲和性要求，`Stable` 表示所有 Region 已经达到目标分布。 - `REGION_COUNT`：当前在该亲和性组中的 Region 数量。 -- `AFFINITY_REGION_COUNT`：已经满足亲和性副本分布的 Region 数量。 +- `AFFINITY_REGION_COUNT`：已经满足亲和性副本分布的 Region 数量。若 region_count > Affinity_region_count 时，表示pd调度没有完成；若 region_count = Affinity_region_count 时，表示 pd 的基于亲和性的副本搬迁调度工作完成，也就意味着副本分布已经满足亲和性要求，但是不意味着 merge 操作已经完成。 ## MySQL 兼容性 diff --git a/table-affinity.md b/table-affinity.md index 9529c1ffb09f..97a3b0bcf3fc 100644 --- a/table-affinity.md +++ b/table-affinity.md @@ -25,8 +25,8 @@ summary: 通过表或分区的亲和性约束，控制 Region 的副本分布并 ## 支持的亲和性级别 - 非分区表：`AFFINITY='table'`。 -- 分区表：`AFFINITY='partition'`，每个分区会生成独立的亲和性分组。 -- 取消亲和性：设置为 `AFFINITY=''` 或 `AFFINITY='none'`。 +- 分区表：`AFFINITY='partition'`，每个分区会生成独立的亲和性分组。如若表有4个分区，则会分别针对每个分区生成亲和性分组，故总共有4个独立的亲和性分组。 +- 取消亲和性：设置为 `AFFINITY=''` 或 `AFFINITY='none'`。当表从affinity='table' or 'partition' 修改为 'none' 后， PD 会删除该表或分区的亲和性分组，不再受到亲和性相关的调度约束，但是 TiKV 的 Split 状态会在最迟 10 分钟内恢复。 - 不支持在临时表、视图上开启亲和性。 ## 基本用法 From b4a756adb4e46eaf05c23b3ffc29682882dbe734 Mon Sep 17 00:00:00 2001 From: qiancai Date: Fri, 26 Dec 2025 11:00:12 +0800 Subject: [PATCH 04/30] revise descriptions in table-affinity.md --- table-affinity.md | 128 ++++++++++++++++++++++++++++------------------ 1 file changed, 78 insertions(+), 50 deletions(-) diff --git a/table-affinity.md b/table-affinity.md index 97a3b0bcf3fc..8afdc04db3a9 100644 --- a/table-affinity.md +++ b/table-affinity.md @@ -3,78 +3,106 @@ title: 表级数据亲和性 summary: 通过表或分区的亲和性约束，控制 Region 的副本分布并查看调度状态。 --- -# 表级数据亲和性 实验特性，自 v8.5.5 起提供 +# 表级数据亲和性 从 v8.5.5 和 v9.0.0 开始引入 > **警告：** > -> 该功能为实验特性，不建议在生产环境中使用。行为和接口可能在未来版本变更或移除。如遇问题，请在 GitHub 提交 [issue](https://github.com/pingcap/tidb/issues) 反馈。 +> 该功能为实验特性，不建议在生产环境中使用。该功能可能会在未事先通知的情况下发生变化或删除。如果发现 bug，请在 GitHub 上提 [issue](https://github.com/pingcap/tidb/issues) 反馈。 -表级数据亲和性用于将表或分区的 Region 归为同一亲和性分组，并让 PD 将这些 Region 的 Leader、Voter 优先调度到指定的 Store 上，减少跨节点分散带来的延迟。亲和性信息由 PD 维护，TiDB 通过 `AFFINITY` 表选项声明亲和性级别。 +表级数据亲和性是 PD 在表级别上的数据分布调度机制，用于控制同一个表或分区中 Region 的 Leader 和 Voter 副本在 TiKV 集群中的分布。 -## 前置条件 +开启 PD 数据亲和性调度并设置表的 `AFFINITY` 选项为 `table` 或 `partition` 后，PD 会将同一张表或同一个分区的 Region 归入同一个亲和性分组，并在调度过程中优先将这些 Region 的 Leader 和 Voter 副本放置到相同或物理相邻的少数 TiKV 节点上，从而减少查询过程中跨节点访问带来的网络延迟，提升查询性能。 -- 集群版本：TiDB/PD/TiKV 均需为 v8.5.5 及以上的相互兼容版本。 -- 在 PD 侧开启调度：将 `schedule.affinity-schedule-limit` 设置为大于 0，否则亲和性调度不会生效。示例： +## 使用限制 - ```bash - pd-ctl config set schedule.affinity-schedule-limit 4 - ``` +- [临时表](/temporary-tables.md)和[视图](/views.md)不支持配置数据亲和性。 +- 为[分区表](/partitioned-table.md)配置数据亲和性后，**不支持修改该表的分区方案**（包括新增、删除、重组或交换分区）。如需调整分区配置，请先移除该表的亲和性设置。 +- **数据量较大时需提前评估磁盘容量**：开启数据亲和性后，PD 会将表或分区的 Region 优先调度到指定的少数 TiKV 节点上。对于数据量较大的表或分区，可能导致这些节点的磁盘使用率显著升高，建议提前评估磁盘容量并做好监控。 +- 数据亲和性调度仅针对 Leader 和 Voter 副本的分布生效。如果表有 Learner 副本（如 TiFlash），Learner 副本的分布不受亲和性配置影响。 -- 可选：根据需要设置 `schedule.max-affinity-merge-region-size`（MiB），控制亲和性 Region 的合并阈值，设置为 `0` 表示关闭亲和性场景下的自动合并。 +## 前提条件 -## 支持的亲和性级别 +PD 亲和性调度特性默认关闭，在设置表或分区的亲和性前，请开启并配置该特性。 -- 非分区表：`AFFINITY='table'`。 -- 分区表：`AFFINITY='partition'`，每个分区会生成独立的亲和性分组。如若表有4个分区，则会分别针对每个分区生成亲和性分组，故总共有4个独立的亲和性分组。 -- 取消亲和性：设置为 `AFFINITY=''` 或 `AFFINITY='none'`。当表从affinity='table' or 'partition' 修改为 'none' 后， PD 会删除该表或分区的亲和性分组，不再受到亲和性相关的调度约束，但是 TiKV 的 Split 状态会在最迟 10 分钟内恢复。 -- 不支持在临时表、视图上开启亲和性。 +1. 将 PD 配置项 [`schedule.affinity-schedule-limit`](/pd-configuration-file.md#affinity-schedule-limit-从-v855-和-v900-版本开始引入) 设置为大于 `0` 的值以开启 PD 的亲和性调度。 -## 基本用法 + 例如： -1. **创建或修改表时声明亲和性** + ```bash + pd-ctl config set schedule.affinity-schedule-limit 4 + ``` - ```sql - CREATE TABLE t1 (a INT) AFFINITY = 'table'; + `schedule.affinity-schedule-limit` 为 4，表示 PD 同时可进行的亲和性调度任务数为 4。默认值为 `0`，表示禁用亲和性调度。 - CREATE TABLE tp1 (a INT) - AFFINITY = 'partition' - PARTITION BY HASH(a) PARTITIONS 4; +2. （可选步骤）根据需要设置 PD 配置项 [`schedule.max-affinity-merge-region-size`](/pd-configuration-file.md#max-affinity-merge-region-size-从-v855-和-v900-版本开始引入)（单位为 MiB，默认值为 `256`），用于控制属于同一亲和性分组中相邻的小 Region 自动合并的阈值。设置为 `0` 表示关闭亲和性分组中相邻的小 Region 的自动合并。 - ALTER TABLE t1 AFFINITY = 'table'; -- 开启 - ALTER TABLE t1 AFFINITY = ''; -- 关闭 - ``` +## 使用方法 - 开启后，TiDB 会在 PD 中为表或分区自动创建亲和性分组，并向 PD 维护对应的 key range。 +本节介绍如何配置表或分区的亲和性，以及如何查看亲和性调度状态。 -2. **查看调度状态** +### 配置表或分区的亲和性 - - `SHOW AFFINITY;` 展示当前已开启亲和性的表或分区及其在 PD 中记录的目标副本分布。`STATUS` 含义： - - `Pending`：PD 尚未开始进行亲和性调度（比如未确定 Leader/Voter）。 - - `Preparing`：正在调度 Region 以满足亲和性要求。 - - `Stable`：所有 Region 已达到目标分布。 - - INFORMATION_SCHEMA 也会暴露亲和性信息： - - `TABLES.TIDB_AFFINITY`：表级亲和性。 - - `PARTITIONS.TIDB_AFFINITY`：分区级亲和性。 +你可以通过 `CREATE TABLE` 或 `ALTER TABLE` 语句中的 `AFFINITY` 选项配置表或分区的亲和性。 -## 调度行为与内部机制 +| 亲和性等级 | 适用范围 | 效果 | +|---|---|---| +| `AFFINITY='table'` | 非分区表 | 开启该表的亲和性，PD 会为此表的所有 Region 创建一个亲和性分组。 | +| `AFFINITY='partition'` | 分区表 | 开启该表中每个分区的亲和性，PD 会为此表的**每个分区**对应的 Region 分别创建独立的亲和性分组。例如，当表包含 4 个分区时，PD 将为该表创建 4 个相互独立的亲和性分组。 | +| `AFFINITY=''` 或 `AFFINITY='none'` | 已设置 `AFFINITY='table'` 或 `AFFINITY='partition'` 的表 | 关闭该表或分区的亲和性。设置后，PD 会删除对应表或分区的亲和性分组，表或分区的 Region 将不再受到亲和性调度约束。TiKV 上 Region 的自动分裂将在最长 10 分钟内恢复为默认状态。 | -- **自动分裂拦截**：当 Region 属于亲和性分组，- 亲和性生效时，Region 默认不进行自动分裂（除非大小或 key 数超过阈值），避免产生过多 Region 影响亲和性效果。手工 `ADMIN SPLIT` 不受此限制。 -- **降级与过期**：若分组目标的 Leader/Voter 所在 Store 不可用（如节点 down 、磁盘不足等），PD 会将分组标记为降级。若 10 分钟内未恢复，将自动过期并允许常规调度；此时亲和性调度暂停，`SHOW AFFINITY` 的状态会回到 `Pending`。恢复后可重新更新分组的 Leader/Voter 以重新启用亲和性。 +**示例**： -## 限制与注意事项 +创建非分区表时开启该表的亲和性： -- 开启亲和性后，**不支持修改分区方案**（如新增/删除/重组/交换分区）。如需调整分区，请先移除亲和性。 -- 临时表、视图不支持亲和性。 -- **数据量较大时需注意磁盘空间**：开启亲和性后，PD 会将表或分区的 Region 调度到指定的少数 Store 上。如果表数据量较大，可能导致这些 Store 的磁盘占用显著增加，需提前评估磁盘容量并做好监控。 -- 亲和性调度依赖 PD 调度参数： - - `schedule.affinity-schedule-limit` 默认 0（关闭）。需显式配置后，PD 才会为亲和性分组创建调度任务。 - - `schedule.max-affinity-merge-region-size` 为亲和性 Region 的合并阈值；设置为 0 关闭亲和性合并。 -- 亲和性生效时，小于阈值的 Region 默认不进行自动分裂，手工 `ADMIN SPLIT` 仍可执行。 -- 不支持 Learner 副本的亲和性调度：如果表配置了包含 Learner 副本的放置规则（比如 TiFlash），亲和性调度不会对 Learner 副本生效，但不影响现有 Learner 副本的分布。 -- 当目标 Store 处于不可用、被驱逐 Leader、或与放置规则冲突时，PD 会将分组标记为降级或过期，亲和性调度暂停。恢复后可通过 `SHOW AFFINITY` 观察状态，必要时重新更新分组的 Leader/Voter。 +```sql +CREATE TABLE t1 (a INT) AFFINITY = 'table'; +``` + +创建分区表时开启该表中每个分区的亲和性： + +```sql +CREATE TABLE tp1 (a INT) + AFFINITY = 'partition' + PARTITION BY HASH(a) PARTITIONS 4; +``` + +为现有非分区表开启亲和性： + +```sql +CREATE TABLE t2 (a INT); +ALTER TABLE t2 AFFINITY = 'table'; +``` + +关闭表的亲和性： + +``` +ALTER TABLE t1 AFFINITY = ''; +``` + +### 查看亲和性 + +可以通过以下方式查看表的亲和性信息： + +- 执行 [`SHOW AFFINITY;`](/sql-statements/sql-statement-show-affinity.md)，在 `STATUS` 列查看已开启亲和性的表或分区及其调度状态。`STATUS` 列的含义如下： + + - `Pending`：PD 尚未对该表或分区进行亲和性调度 （比如未确定 Leader 或 Voter 时）。 + - `Preparing`：PD 正在调度 Region 以满足亲和性要求。 + - `Stable`：所有 Region 已达到目标分布。 + +- 通过 [`INFORMATION_SCHEMA.TABLES`](/information-schema/information-schema-tables.md) 表的 `TIDB_AFFINITY` 列查看表的亲和性等级。 +- 通过 [`INFORMATION_SCHEMA.PARTITIONS`](/information-schema/information-schema-partitions.md) 表的 `TIDB_AFFINITY` 列查看分区的亲和性等级。 + +## 注意事项 + +- **Region 的自动分裂**：当 Region 属于某个亲和性分组且亲和性生效时，Region 默认不会自动分裂（除非大小或 Key 数量超过阈值），以避免产生过多 Region 影响亲和性效果。手动执行的 [`ADMIN SPLIT`](/sql-statements/sql-statement-admin-split.md) 不受此限制。 + +- **降级与过期机制**：如果亲和性分组中目标 Leader 或 Voter 所在的 TiKV 节点处于不可用状态（例如节点宕机或磁盘空间不足），Leader 被驱逐，或与现有放置规则发生冲突时，PD 会将该亲和性分组标记为降级状态。在降级期间，对应表或分区的亲和性调度将暂停。 + + - 若在 10 分钟内相关节点恢复正常，PD 会继续按照原有亲和性设置进行调度。 + - 若超过 10 分钟仍未恢复，该亲和性分组将被标记为过期，PD 将恢复常规调度行为，此时 [`SHOW AFFINITY`](/sql-statements/sql-statement-show-affinity.md) 的状态会回到 `Pending`。后续可通过重新更新分组的 Leader 和 Voter 来重新启用亲和性调度。 ## 相关语句与配置 -- `CREATE TABLE` / `ALTER TABLE` 的 `AFFINITY` 选项。 -- `SHOW AFFINITY` 语句。 -- PD 调度参数：`schedule.affinity-schedule-limit`、`schedule.max-affinity-merge-region-size`。 +- [`CREATE TABLE`](/sql-statements/sql-statement-create-table.md) 或 [`ALTER TABLE`](/sql-statements/sql-statement-alter-table.md) 的 `AFFINITY` 选项 +- [`SHOW AFFINITY`](/sql-statements/sql-statement-show-affinity.md) +- PD 配置项：[`schedule.affinity-schedule-limit`](/pd-configuration-file.md#affinity-schedule-limit-从-v855-和-v900-版本开始引入) 和 [`schedule.max-affinity-merge-region-size`](/pd-configuration-file.md#max-affinity-merge-region-size-从-v855-和-v900-版本开始引入) \ No newline at end of file From 35fd19b4535abc37a7966a3a78d589e8db255abe Mon Sep 17 00:00:00 2001 From: lhy1024 Date: Fri, 26 Dec 2025 14:25:24 +0800 Subject: [PATCH 05/30] Update sql-statements/sql-statement-show-affinity.md Co-authored-by: Grace Cai --- sql-statements/sql-statement-show-affinity.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sql-statements/sql-statement-show-affinity.md b/sql-statements/sql-statement-show-affinity.md index dfc4b0cbecb7..2d287a632e35 100644 --- a/sql-statements/sql-statement-show-affinity.md +++ b/sql-statements/sql-statement-show-affinity.md @@ -3,7 +3,7 @@ title: SHOW AFFINITY summary: 介绍 TiDB 数据库中 SHOW AFFINITY 的使用概况。 --- -# SHOW AFFINITY 从 v8.5.5 开始引入 +# SHOW AFFINITY 从 v8.5.5 和 v9.0.0 版本开始引入 `SHOW AFFINITY` 语句用于查看开启了 `AFFINITY` 选项的表或分区的亲和性调度信息，以及 PD 当前记录的目标副本分布。 From 3ace92ccf37924e35a5c1212fd9d44d7e4004541 Mon Sep 17 00:00:00 2001 From: lhy1024 Date: Fri, 26 Dec 2025 14:25:34 +0800 Subject: [PATCH 06/30] Update pd-configuration-file.md Co-authored-by: Grace Cai --- pd-configuration-file.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pd-configuration-file.md b/pd-configuration-file.md index 894e1f5857d4..9af7dbfe62b3 100644 --- a/pd-configuration-file.md +++ b/pd-configuration-file.md @@ -287,7 +287,7 @@ pd-server 相关配置项。 + 控制 Region Merge 的 key 上限，当 Region key 大于指定值时 PD 不会将其与相邻的 Region 合并。 + 默认：540000。在 v8.4.0 之前，默认值为 200000；从 v8.4.0 开始，默认值为 540000。 -### `max-affinity-merge-region-size` 从 v8.5.5 版本开始引入 +### `max-affinity-merge-region-size` 从 v8.5.5 和 v9.0.0 版本开始引入 + 当 Region 属于亲和性分组且大小小于该值时，PD 会尝试将其与相邻的同一亲和性分组的 Region 合并。设置为 `0` 表示关闭配置了亲和性的 Region 合并。 + 默认：256 From 97135588228dedcaab4891ee9aff40a15ccfdac2 Mon Sep 17 00:00:00 2001 From: lhy1024 Date: Fri, 26 Dec 2025 14:25:46 +0800 Subject: [PATCH 07/30] Update pd-configuration-file.md Co-authored-by: Grace Cai --- pd-configuration-file.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pd-configuration-file.md b/pd-configuration-file.md index 9af7dbfe62b3..b20f63ba9cf0 100644 --- a/pd-configuration-file.md +++ b/pd-configuration-file.md @@ -368,7 +368,7 @@ pd-server 相关配置项。 + 同时进行的 Region Merge 调度的任务，设置为 0 则关闭 Region Merge。 + 默认值：8 -### `affinity-schedule-limit` 从 v8.5.5 版本开始引入 +### `affinity-schedule-limit` 从 v8.5.5 和 v9.0.0 版本开始引入 + 控制同时进行的亲和性调度任务数量。设置为 `0` 表示禁用亲和性调度。 + 默认值：0 From f2ea463df69753fcb2e345b795ab64b93034ec48 Mon Sep 17 00:00:00 2001 From: lhy1024 Date: Fri, 26 Dec 2025 14:37:49 +0800 Subject: [PATCH 08/30] Update sql-statements/sql-statement-show-affinity.md Co-authored-by: Grace Cai --- sql-statements/sql-statement-show-affinity.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sql-statements/sql-statement-show-affinity.md b/sql-statements/sql-statement-show-affinity.md index 2d287a632e35..81fc9dd2ae78 100644 --- a/sql-statements/sql-statement-show-affinity.md +++ b/sql-statements/sql-statement-show-affinity.md @@ -5,7 +5,7 @@ summary: 介绍 TiDB 数据库中 SHOW AFFINITY 的使用概况。 # SHOW AFFINITY 从 v8.5.5 和 v9.0.0 版本开始引入 -`SHOW AFFINITY` 语句用于查看开启了 `AFFINITY` 选项的表或分区的亲和性调度信息，以及 PD 当前记录的目标副本分布。 +`SHOW AFFINITY` 语句用于查看配置了 `AFFINITY` 选项的表或分区的亲和性调度信息，以及 PD 当前记录的目标副本分布。 ## 语法图 From ae9eb310403c040c30f123993313f9498374978f Mon Sep 17 00:00:00 2001 From: lhy1024 Date: Fri, 26 Dec 2025 14:37:58 +0800 Subject: [PATCH 09/30] Update sql-statements/sql-statement-show-affinity.md Co-authored-by: Grace Cai --- sql-statements/sql-statement-show-affinity.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sql-statements/sql-statement-show-affinity.md b/sql-statements/sql-statement-show-affinity.md index 81fc9dd2ae78..b16c29b28563 100644 --- a/sql-statements/sql-statement-show-affinity.md +++ b/sql-statements/sql-statement-show-affinity.md @@ -25,7 +25,7 @@ CREATE TABLE tp1 (a INT) AFFINITY = 'partition' PARTITION BY HASH(a) PARTITIONS SHOW AFFINITY; ``` -输出结果类似于： +输出结果示例如下： ```sql +---------+------------+----------------+-----------------+------------------+----------+--------------+----------------------+ From 0eb9eaa152137fbdb243749daa192e7dfd908199 Mon Sep 17 00:00:00 2001 From: lhy1024 Date: Fri, 26 Dec 2025 14:38:05 +0800 Subject: [PATCH 10/30] Update table-affinity.md Co-authored-by: Grace Cai --- table-affinity.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/table-affinity.md b/table-affinity.md index 8afdc04db3a9..57ba8de0fd10 100644 --- a/table-affinity.md +++ b/table-affinity.md @@ -11,7 +11,7 @@ summary: 通过表或分区的亲和性约束，控制 Region 的副本分布并 表级数据亲和性是 PD 在表级别上的数据分布调度机制，用于控制同一个表或分区中 Region 的 Leader 和 Voter 副本在 TiKV 集群中的分布。 -开启 PD 数据亲和性调度并设置表的 `AFFINITY` 选项为 `table` 或 `partition` 后，PD 会将同一张表或同一个分区的 Region 归入同一个亲和性分组，并在调度过程中优先将这些 Region 的 Leader 和 Voter 副本放置到相同或物理相邻的少数 TiKV 节点上，从而减少查询过程中跨节点访问带来的网络延迟，提升查询性能。 +开启 PD 数据亲和性调度并设置表的 `AFFINITY` 选项为 `table` 或 `partition` 后，PD 会将同一张表或同一个分区的 Region 归入同一个亲和性分组，并在调度过程中优先将这些 Region 的 Leader 和 Voter 副本放置到相同的少数 TiKV 节点上，从而减少查询过程中跨节点访问带来的网络延迟，提升查询性能。 ## 使用限制 From 070e088a9b967e5365ced76a35672647a97ba803 Mon Sep 17 00:00:00 2001 From: lhy1024 Date: Fri, 26 Dec 2025 17:12:36 +0800 Subject: [PATCH 11/30] Update information-schema/information-schema-partitions.md Co-authored-by: Grace Cai --- information-schema/information-schema-partitions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/information-schema/information-schema-partitions.md b/information-schema/information-schema-partitions.md index 976fb655bcc9..25f1e2829346 100644 --- a/information-schema/information-schema-partitions.md +++ b/information-schema/information-schema-partitions.md @@ -115,7 +115,7 @@ SUBPARTITION_ORDINAL_POSITION: NULL TABLESPACE_NAME: NULL TIDB_PARTITION_ID: 90 TIDB_PLACEMENT_POLICY_NAME: NULL - TIDB_AFFINITY: NULL + TIDB_AFFINITY: NULL 2 rows in set (0.00 sec) ``` From 60c3575665e18dc08728a444d6771d330bc265ca Mon Sep 17 00:00:00 2001 From: lhy1024 Date: Fri, 26 Dec 2025 17:14:03 +0800 Subject: [PATCH 12/30] Update information-schema/information-schema-tables.md Co-authored-by: Grace Cai --- information-schema/information-schema-tables.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/information-schema/information-schema-tables.md b/information-schema/information-schema-tables.md index c9e2faddf7e8..87985a401d78 100644 --- a/information-schema/information-schema-tables.md +++ b/information-schema/information-schema-tables.md @@ -123,7 +123,7 @@ SHOW TABLES * `CREATE_OPTIONS`：创建选项。 * `TABLE_COMMENT`：表的注释、备注。 -表中的信息大部分定义自 MySQL，以下列为 TiDB 新增： +表中的大部分列都和 MySQL 相同，除了以下列是 TiDB 新增的： * `TIDB_TABLE_ID`：标识表的内部 ID，该 ID 在一个 TiDB 集群内部唯一。 * `TIDB_ROW_ID_SHARDING_INFO`：标识表的 Sharding 类型，可能的值为： From be89f1f124a9733c4774d417c91916d9a0107db2 Mon Sep 17 00:00:00 2001 From: lhy1024 Date: Fri, 26 Dec 2025 17:14:16 +0800 Subject: [PATCH 13/30] Update information-schema/information-schema-partitions.md Co-authored-by: Grace Cai --- information-schema/information-schema-partitions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/information-schema/information-schema-partitions.md b/information-schema/information-schema-partitions.md index 25f1e2829346..3c5235f15309 100644 --- a/information-schema/information-schema-partitions.md +++ b/information-schema/information-schema-partitions.md @@ -86,7 +86,7 @@ SUBPARTITION_ORDINAL_POSITION: NULL TABLESPACE_NAME: NULL TIDB_PARTITION_ID: 89 TIDB_PLACEMENT_POLICY_NAME: NULL - TIDB_AFFINITY: NULL + TIDB_AFFINITY: NULL *************************** 2. row *************************** TABLE_CATALOG: def TABLE_SCHEMA: test From b1ababa542166661f3402ea7998c17e8fccc7126 Mon Sep 17 00:00:00 2001 From: lhy1024 Date: Fri, 26 Dec 2025 17:14:26 +0800 Subject: [PATCH 14/30] Update information-schema/information-schema-tables.md Co-authored-by: Grace Cai --- information-schema/information-schema-tables.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/information-schema/information-schema-tables.md b/information-schema/information-schema-tables.md index 87985a401d78..93b3b12e4107 100644 --- a/information-schema/information-schema-tables.md +++ b/information-schema/information-schema-tables.md @@ -42,7 +42,7 @@ DESC tables; | TIDB_TABLE_ID | bigint(21) | YES | | NULL | | | TIDB_ROW_ID_SHARDING_INFO | varchar(255) | YES | | NULL | | | TIDB_PK_TYPE | varchar(64) | YES | | NULL | | -| TIDB_PLACEMENT_POLICY_NAME | varchar(64) | YES | | NULL | | +| TIDB_PLACEMENT_POLICY_NAME | varchar(64) | YES | | NULL | | | TIDB_TABLE_MODE | varchar(16) | YES | | NULL | | | TIDB_AFFINITY | varchar(128) | YES | | NULL | | +---------------------------+---------------+------+------+----------+-------+ From 57bb2b31ae57fae07c0e969ad73e16f1e91b50c7 Mon Sep 17 00:00:00 2001 From: lhy1024 Date: Fri, 26 Dec 2025 17:14:35 +0800 Subject: [PATCH 15/30] Update information-schema/information-schema-tables.md Co-authored-by: Grace Cai --- information-schema/information-schema-tables.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/information-schema/information-schema-tables.md b/information-schema/information-schema-tables.md index 93b3b12e4107..1aa8d98ce4be 100644 --- a/information-schema/information-schema-tables.md +++ b/information-schema/information-schema-tables.md @@ -79,11 +79,11 @@ SELECT * FROM tables WHERE table_schema='mysql' AND table_name='user'\G CREATE_OPTIONS: TABLE_COMMENT: TIDB_TABLE_ID: 5 - TIDB_ROW_ID_SHARDING_INFO: NULL - TIDB_PK_TYPE: CLUSTERED - TIDB_PLACEMENT_POLICY_NAME: NULL +TIDB_ROW_ID_SHARDING_INFO: NULL + TIDB_PK_TYPE: CLUSTERED +TIDB_PLACEMENT_POLICY_NAME: NULL TIDB_TABLE_MODE: Normal - TIDB_AFFINITY: NULL + TIDB_AFFINITY: NULL 1 row in set (0.00 sec) ``` From 5b792e708ef6050a472be09d237ab8e2c69d9864 Mon Sep 17 00:00:00 2001 From: lhy1024 Date: Fri, 26 Dec 2025 17:15:07 +0800 Subject: [PATCH 16/30] Update pd-configuration-file.md Co-authored-by: Grace Cai --- pd-configuration-file.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pd-configuration-file.md b/pd-configuration-file.md index b20f63ba9cf0..0e250154cb65 100644 --- a/pd-configuration-file.md +++ b/pd-configuration-file.md @@ -289,7 +289,7 @@ pd-server 相关配置项。 ### `max-affinity-merge-region-size` 从 v8.5.5 和 v9.0.0 版本开始引入 -+ 当 Region 属于亲和性分组且大小小于该值时，PD 会尝试将其与相邻的同一亲和性分组的 Region 合并。设置为 `0` 表示关闭配置了亲和性的 Region 合并。 +- 控制属于同一[亲和性](table-affinity.md)分组中相邻的小 Region 自动合并的阈值。当 Region 属于某个亲和性分组，且其大小小于该配置值时，PD 会尝试将该 Region 与同一亲和性分组中相邻的其它小 Region 进行合并，以减少 Region 数量并维持亲和性效果。设置为 `0` 表示关闭亲和性分组中相邻小 Region 的自动合并。 + 默认：256 + 单位：MiB From 9147177df1394244ac8236263981d2ed8db0a4a5 Mon Sep 17 00:00:00 2001 From: lhy1024 Date: Fri, 26 Dec 2025 17:15:48 +0800 Subject: [PATCH 17/30] Update sql-statements/sql-statement-show-affinity.md Co-authored-by: Grace Cai --- sql-statements/sql-statement-show-affinity.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/sql-statements/sql-statement-show-affinity.md b/sql-statements/sql-statement-show-affinity.md index b16c29b28563..67fe494f9f88 100644 --- a/sql-statements/sql-statement-show-affinity.md +++ b/sql-statements/sql-statement-show-affinity.md @@ -42,7 +42,9 @@ SHOW AFFINITY; - `LEADER_STORE_ID`、`VOTER_STORE_IDS`：PD 为该表或分区记录的目标 Leader 副本和 Voter 副本所在的 store ID。当亲和性尚未确定时显示为 `NULL`。 - `STATUS`：`Pending` 表示 PD 尚未进行亲和性调度，`Preparing` 表示正在调度 Region 以满足亲和性要求，`Stable` 表示所有 Region 已经达到目标分布。 - `REGION_COUNT`：当前在该亲和性组中的 Region 数量。 -- `AFFINITY_REGION_COUNT`：已经满足亲和性副本分布的 Region 数量。若 region_count > Affinity_region_count 时，表示pd调度没有完成；若 region_count = Affinity_region_count 时，表示 pd 的基于亲和性的副本搬迁调度工作完成，也就意味着副本分布已经满足亲和性要求，但是不意味着 merge 操作已经完成。 +- `Affinity_region_count`：当前已满足亲和性副本分布要求的 Region 数量。 + - 当 `Affinity_region_count` < `Region_count` 时，表示仍有部分 Region 尚未完成基于亲和性的副本调度。 + - 当 `Affinity_region_count` = `Region_count` 时，表示基于亲和性的 Region 副本迁移调度已完成，也就意味着所有 Region 的分布已经满足亲和性要求，但并不意味着相关 Region 的合并操作已完成。 ## MySQL 兼容性 From 70fe83b3aa037e9eb226d5689fe46ec981a26ee0 Mon Sep 17 00:00:00 2001 From: lhy1024 Date: Fri, 26 Dec 2025 17:16:05 +0800 Subject: [PATCH 18/30] Update pd-configuration-file.md Co-authored-by: Grace Cai --- pd-configuration-file.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pd-configuration-file.md b/pd-configuration-file.md index 0e250154cb65..8e6e74ade124 100644 --- a/pd-configuration-file.md +++ b/pd-configuration-file.md @@ -370,7 +370,7 @@ pd-server 相关配置项。 ### `affinity-schedule-limit` 从 v8.5.5 和 v9.0.0 版本开始引入 -+ 控制同时进行的亲和性调度任务数量。设置为 `0` 表示禁用亲和性调度。 ++ 控制同时进行的[亲和性](table-affinity.md)调度任务数量。设置为 `0` 表示禁用亲和性调度。 + 默认值：0 ### `high-space-ratio` From 5701acc1a8e66c0da7922ea09b0c2eb842047343 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Tue, 30 Dec 2025 12:12:02 +0800 Subject: [PATCH 19/30] apply suggestions from lhy1024 --- sql-statements/sql-statement-show-affinity.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/sql-statements/sql-statement-show-affinity.md b/sql-statements/sql-statement-show-affinity.md index 67fe494f9f88..7716e7591983 100644 --- a/sql-statements/sql-statement-show-affinity.md +++ b/sql-statements/sql-statement-show-affinity.md @@ -39,8 +39,11 @@ SHOW AFFINITY; 各列含义如下： -- `LEADER_STORE_ID`、`VOTER_STORE_IDS`：PD 为该表或分区记录的目标 Leader 副本和 Voter 副本所在的 store ID。当亲和性尚未确定时显示为 `NULL`。 -- `STATUS`：`Pending` 表示 PD 尚未进行亲和性调度，`Preparing` 表示正在调度 Region 以满足亲和性要求，`Stable` 表示所有 Region 已经达到目标分布。 +- `Leader_store_id`、`Voter_store_ids`：PD 为该表或分区记录的目标 Leader 副本和 Voter 副本所在的 TiKV Store ID。如果亲和性分组尚未确定目标副本位置或 [`schedule.affinity-schedule-limit`](/pd-configuration-file.md#affinity-schedule-limit-从-v855-和-v900-版本开始引入) 为 `0` ，则显示为 `NULL`。 +- `Status`：表示当前亲和性调度的状态。 + - `Pending`：PD 尚未对该表或分区进行亲和性调度（比如未确定 Leader 或 Voter 时）。 + - `Preparing`：PD 正在调度 Region 以满足亲和性要求。 + - `Stable`：所有 Region 已达到目标分布。 - `REGION_COUNT`：当前在该亲和性组中的 Region 数量。 - `Affinity_region_count`：当前已满足亲和性副本分布要求的 Region 数量。 - 当 `Affinity_region_count` < `Region_count` 时，表示仍有部分 Region 尚未完成基于亲和性的副本调度。 From 98662ed18aff3c180d5461e5fb42ac167c6410b6 Mon Sep 17 00:00:00 2001 From: lhy1024 Date: Tue, 30 Dec 2025 14:01:38 +0800 Subject: [PATCH 20/30] Update table-affinity.md Co-authored-by: Grace Cai --- table-affinity.md | 1 + 1 file changed, 1 insertion(+) diff --git a/table-affinity.md b/table-affinity.md index 57ba8de0fd10..9b40dc367a20 100644 --- a/table-affinity.md +++ b/table-affinity.md @@ -15,6 +15,7 @@ summary: 通过表或分区的亲和性约束，控制 Region 的副本分布并 ## 使用限制 +- 在[PD 微服务模式下](/pd-microservices.md)下，该功能不会生效。 - [临时表](/temporary-tables.md)和[视图](/views.md)不支持配置数据亲和性。 - 为[分区表](/partitioned-table.md)配置数据亲和性后，**不支持修改该表的分区方案**（包括新增、删除、重组或交换分区）。如需调整分区配置，请先移除该表的亲和性设置。 - **数据量较大时需提前评估磁盘容量**：开启数据亲和性后，PD 会将表或分区的 Region 优先调度到指定的少数 TiKV 节点上。对于数据量较大的表或分区，可能导致这些节点的磁盘使用率显著升高，建议提前评估磁盘容量并做好监控。 From aaacf4f90fbb77c9462d0612c8e894501fcbf4c1 Mon Sep 17 00:00:00 2001 From: lhy1024 Date: Tue, 30 Dec 2025 14:01:53 +0800 Subject: [PATCH 21/30] Update table-affinity.md Co-authored-by: Grace Cai --- table-affinity.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/table-affinity.md b/table-affinity.md index 9b40dc367a20..a9f3deec0b39 100644 --- a/table-affinity.md +++ b/table-affinity.md @@ -84,7 +84,7 @@ ALTER TABLE t1 AFFINITY = ''; 可以通过以下方式查看表的亲和性信息： -- 执行 [`SHOW AFFINITY;`](/sql-statements/sql-statement-show-affinity.md)，在 `STATUS` 列查看已开启亲和性的表或分区及其调度状态。`STATUS` 列的含义如下： +- 执行 [`SHOW AFFINITY;`](/sql-statements/sql-statement-show-affinity.md)，在 `Status` 列查看已开启亲和性的表或分区及其调度状态。`STATUS` 列的含义如下： - `Pending`：PD 尚未对该表或分区进行亲和性调度 （比如未确定 Leader 或 Voter 时）。 - `Preparing`：PD 正在调度 Region 以满足亲和性要求。 From fb88e77db208d9ba2004fc67dbc8f5beab176775 Mon Sep 17 00:00:00 2001 From: lhy1024 Date: Tue, 30 Dec 2025 14:41:28 +0800 Subject: [PATCH 22/30] address comments Signed-off-by: lhy1024 --- table-affinity.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/table-affinity.md b/table-affinity.md index a9f3deec0b39..cd7aba8e7717 100644 --- a/table-affinity.md +++ b/table-affinity.md @@ -95,12 +95,12 @@ ALTER TABLE t1 AFFINITY = ''; ## 注意事项 -- **Region 的自动分裂**：当 Region 属于某个亲和性分组且亲和性生效时，Region 默认不会自动分裂（除非大小或 Key 数量超过阈值），以避免产生过多 Region 影响亲和性效果。手动执行的 [`ADMIN SPLIT`](/sql-statements/sql-statement-admin-split.md) 不受此限制。 +- **Region 的自动分裂**：当 Region 属于某个亲和性分组且亲和性生效时，Region 默认不会自动分裂（除非大小或 Key 数量超过阈值，该阈值通常为 max-affinity-merge-region-size 的四倍左右），以避免产生过多 Region 影响亲和性效果。手动执行的 [`ADMIN SPLIT`](/sql-statements/sql-statement-admin-split.md) 不受此限制。 - **降级与过期机制**：如果亲和性分组中目标 Leader 或 Voter 所在的 TiKV 节点处于不可用状态（例如节点宕机或磁盘空间不足），Leader 被驱逐，或与现有放置规则发生冲突时，PD 会将该亲和性分组标记为降级状态。在降级期间，对应表或分区的亲和性调度将暂停。 - 若在 10 分钟内相关节点恢复正常，PD 会继续按照原有亲和性设置进行调度。 - - 若超过 10 分钟仍未恢复，该亲和性分组将被标记为过期，PD 将恢复常规调度行为，此时 [`SHOW AFFINITY`](/sql-statements/sql-statement-show-affinity.md) 的状态会回到 `Pending`。后续可通过重新更新分组的 Leader 和 Voter 来重新启用亲和性调度。 + - 若超过 10 分钟仍未恢复，该亲和性分组将被标记为过期，PD 将恢复常规调度行为，此时 [`SHOW AFFINITY`](/sql-statements/sql-statement-show-affinity.md) 的状态会回到 `Pending`。接下来，PD 将会自动更新亲和性分组中的 Leader 和 Voter 以重新启用亲和性调度。 ## 相关语句与配置 From a7ccefa8f9331672b527443cdaa70367fcf5a423 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Tue, 30 Dec 2025 18:18:19 +0800 Subject: [PATCH 23/30] Apply suggestions from code review --- table-affinity.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/table-affinity.md b/table-affinity.md index cd7aba8e7717..20412f451bde 100644 --- a/table-affinity.md +++ b/table-affinity.md @@ -95,12 +95,12 @@ ALTER TABLE t1 AFFINITY = ''; ## 注意事项 -- **Region 的自动分裂**：当 Region 属于某个亲和性分组且亲和性生效时，Region 默认不会自动分裂（除非大小或 Key 数量超过阈值，该阈值通常为 max-affinity-merge-region-size 的四倍左右），以避免产生过多 Region 影响亲和性效果。手动执行的 [`ADMIN SPLIT`](/sql-statements/sql-statement-admin-split.md) 不受此限制。 +- **Region 的自动分裂**：当 Region 属于某个亲和性分组且亲和性生效时，Region 默认不会自动分裂（除非 Region 大小超过 [`schedule.max-affinity-merge-region-size`](/pd-configuration-file.md#max-affinity-merge-region-size-从-v855-和-v900-版本开始引入) 的四倍以上），以避免产生过多 Region 影响亲和性效果。手动执行的 [`ADMIN SPLIT`](/sql-statements/sql-statement-admin-split.md) 不受此限制。 - **降级与过期机制**：如果亲和性分组中目标 Leader 或 Voter 所在的 TiKV 节点处于不可用状态（例如节点宕机或磁盘空间不足），Leader 被驱逐，或与现有放置规则发生冲突时，PD 会将该亲和性分组标记为降级状态。在降级期间，对应表或分区的亲和性调度将暂停。 - 若在 10 分钟内相关节点恢复正常，PD 会继续按照原有亲和性设置进行调度。 - - 若超过 10 分钟仍未恢复，该亲和性分组将被标记为过期，PD 将恢复常规调度行为，此时 [`SHOW AFFINITY`](/sql-statements/sql-statement-show-affinity.md) 的状态会回到 `Pending`。接下来，PD 将会自动更新亲和性分组中的 Leader 和 Voter 以重新启用亲和性调度。 + - 若超过 10 分钟仍未恢复，该亲和性分组将被标记为过期，此时 PD 会先恢复常规调度行为（[`SHOW AFFINITY`](/sql-statements/sql-statement-show-affinity.md) 的状态会回到 `Pending`），然后自动更新亲和性分组中的 Leader 和 Voter 以重新启用亲和性调度。 ## 相关语句与配置 From b42917b44531f3e548a7a1a8e3e841f2e3efcb6b Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Tue, 30 Dec 2025 18:19:53 +0800 Subject: [PATCH 24/30] Update sql-statements/sql-statement-show-affinity.md --- sql-statements/sql-statement-show-affinity.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sql-statements/sql-statement-show-affinity.md b/sql-statements/sql-statement-show-affinity.md index 7716e7591983..57b65182df72 100644 --- a/sql-statements/sql-statement-show-affinity.md +++ b/sql-statements/sql-statement-show-affinity.md @@ -5,7 +5,7 @@ summary: 介绍 TiDB 数据库中 SHOW AFFINITY 的使用概况。 # SHOW AFFINITY 从 v8.5.5 和 v9.0.0 版本开始引入 -`SHOW AFFINITY` 语句用于查看配置了 `AFFINITY` 选项的表或分区的亲和性调度信息，以及 PD 当前记录的目标副本分布。 +`SHOW AFFINITY` 语句用于查看配置了 `AFFINITY` 选项的表的[亲和性](table-affinity.md)调度信息，以及 PD 当前记录的目标副本分布。 ## 语法图 From 9192c4b4c1b5bf1ed52d4959c3243c7d5d25a1bd Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Wed, 31 Dec 2025 15:19:00 +0800 Subject: [PATCH 25/30] Apply suggestions from code review Co-authored-by: Aolin --- pd-configuration-file.md | 2 +- table-affinity.md | 44 ++++++++++++++++++++-------------------- 2 files changed, 23 insertions(+), 23 deletions(-) diff --git a/pd-configuration-file.md b/pd-configuration-file.md index 8e6e74ade124..dd743e361b71 100644 --- a/pd-configuration-file.md +++ b/pd-configuration-file.md @@ -290,7 +290,7 @@ pd-server 相关配置项。 ### `max-affinity-merge-region-size` 从 v8.5.5 和 v9.0.0 版本开始引入 - 控制属于同一[亲和性](table-affinity.md)分组中相邻的小 Region 自动合并的阈值。当 Region 属于某个亲和性分组，且其大小小于该配置值时，PD 会尝试将该 Region 与同一亲和性分组中相邻的其它小 Region 进行合并，以减少 Region 数量并维持亲和性效果。设置为 `0` 表示关闭亲和性分组中相邻小 Region 的自动合并。 -+ 默认：256 ++ 默认值：256 + 单位：MiB ### `patrol-region-interval` diff --git a/table-affinity.md b/table-affinity.md index 20412f451bde..c51017e1b02a 100644 --- a/table-affinity.md +++ b/table-affinity.md @@ -1,6 +1,6 @@ --- title: 表级数据亲和性 -summary: 通过表或分区的亲和性约束，控制 Region 的副本分布并查看调度状态。 +summary: 通过为表或分区配置亲和性约束，控制 Region 副本的分布并查看调度状态。 --- # 表级数据亲和性 从 v8.5.5 和 v9.0.0 开始引入 @@ -11,31 +11,31 @@ summary: 通过表或分区的亲和性约束，控制 Region 的副本分布并 表级数据亲和性是 PD 在表级别上的数据分布调度机制，用于控制同一个表或分区中 Region 的 Leader 和 Voter 副本在 TiKV 集群中的分布。 -开启 PD 数据亲和性调度并设置表的 `AFFINITY` 选项为 `table` 或 `partition` 后，PD 会将同一张表或同一个分区的 Region 归入同一个亲和性分组，并在调度过程中优先将这些 Region 的 Leader 和 Voter 副本放置到相同的少数 TiKV 节点上，从而减少查询过程中跨节点访问带来的网络延迟，提升查询性能。 +开启 PD 数据亲和性调度，并将表的 `AFFINITY` 选项设置为 `table` 或 `partition` 后，PD 会将同一张表或同一个分区的 Region 归入同一个亲和性分组，并在调度过程中优先将这些 Region 的 Leader 和 Voter 副本放置到相同的少数 TiKV 节点上，从而减少查询过程中跨节点访问带来的网络延迟，提升查询性能。 ## 使用限制 -- 在[PD 微服务模式下](/pd-microservices.md)下，该功能不会生效。 +使用表级数据亲和性前，请注意以下限制： + +- 在 [PD 微服务模式](/pd-microservices.md)下，该功能不会生效。 - [临时表](/temporary-tables.md)和[视图](/views.md)不支持配置数据亲和性。 -- 为[分区表](/partitioned-table.md)配置数据亲和性后，**不支持修改该表的分区方案**（包括新增、删除、重组或交换分区）。如需调整分区配置，请先移除该表的亲和性设置。 -- **数据量较大时需提前评估磁盘容量**：开启数据亲和性后，PD 会将表或分区的 Region 优先调度到指定的少数 TiKV 节点上。对于数据量较大的表或分区，可能导致这些节点的磁盘使用率显著升高，建议提前评估磁盘容量并做好监控。 -- 数据亲和性调度仅针对 Leader 和 Voter 副本的分布生效。如果表有 Learner 副本（如 TiFlash），Learner 副本的分布不受亲和性配置影响。 +- 为[分区表](/partitioned-table.md)配置数据亲和性后，**不支持修改该表的分区方案**，包括新增、删除、重组或交换分区。如需调整分区配置，请先移除该表的亲和性设置。 +- **数据量较大时需提前评估磁盘容量**：开启数据亲和性后，PD 会优先将表或分区的 Region 调度到相同的少数 TiKV 节点上。对于数据量较大的表或分区，可能导致这些节点的磁盘使用率显著升高。建议提前评估磁盘容量并做好监控。 +- 数据亲和性调度仅影响 Leader 和 Voter 副本的分布。如果表有 Learner 副本（如 TiFlash），Learner 副本的分布不受亲和性配置影响。 ## 前提条件 -PD 亲和性调度特性默认关闭，在设置表或分区的亲和性前，请开启并配置该特性。 +PD 亲和性调度特性默认关闭。在设置表或分区的亲和性前，请开启并配置该特性。 -1. 将 PD 配置项 [`schedule.affinity-schedule-limit`](/pd-configuration-file.md#affinity-schedule-limit-从-v855-和-v900-版本开始引入) 设置为大于 `0` 的值以开启 PD 的亲和性调度。 +1. 将 PD 配置项 [`schedule.affinity-schedule-limit`](/pd-configuration-file.md#affinity-schedule-limit-从-v855-和-v900-版本开始引入) 设置为大于 `0` 的值，以开启 PD 的亲和性调度。 - 例如： + 例如，执行以下命令将该配置项设置为 `4`，表示允许 PD 最多同时执行 4 个亲和性调度任务： ```bash pd-ctl config set schedule.affinity-schedule-limit 4 ``` - `schedule.affinity-schedule-limit` 为 4，表示 PD 同时可进行的亲和性调度任务数为 4。默认值为 `0`，表示禁用亲和性调度。 - -2. （可选步骤）根据需要设置 PD 配置项 [`schedule.max-affinity-merge-region-size`](/pd-configuration-file.md#max-affinity-merge-region-size-从-v855-和-v900-版本开始引入)（单位为 MiB，默认值为 `256`），用于控制属于同一亲和性分组中相邻的小 Region 自动合并的阈值。设置为 `0` 表示关闭亲和性分组中相邻的小 Region 的自动合并。 +2. （可选）根据需要设置 PD 配置项 [`schedule.max-affinity-merge-region-size`](/pd-configuration-file.md#max-affinity-merge-region-size-从-v855-和-v900-版本开始引入)（默认值为 `256`，单位为 MiB），用于控制属于同一亲和性分组中相邻的小 Region 自动合并的阈值。设置为 `0` 表示关闭亲和性分组中相邻的小 Region 的自动合并。 ## 使用方法 @@ -76,31 +76,31 @@ ALTER TABLE t2 AFFINITY = 'table'; 关闭表的亲和性： -``` +```sql ALTER TABLE t1 AFFINITY = ''; ``` ### 查看亲和性 -可以通过以下方式查看表的亲和性信息： +可以通过以下方式查看表或分区的亲和性信息： -- 执行 [`SHOW AFFINITY;`](/sql-statements/sql-statement-show-affinity.md)，在 `Status` 列查看已开启亲和性的表或分区及其调度状态。`STATUS` 列的含义如下： +- 执行 [`SHOW AFFINITY`](/sql-statements/sql-statement-show-affinity.md) 语句，在 `Status` 列查看已开启亲和性的表或分区及其调度状态。`Status` 列的值含义如下： - - `Pending`：PD 尚未对该表或分区进行亲和性调度 （比如未确定 Leader 或 Voter 时）。 + - `Pending`：PD 尚未对该表或分区进行亲和性调度，比如未确定 Leader 或 Voter 时。 - `Preparing`：PD 正在调度 Region 以满足亲和性要求。 - `Stable`：所有 Region 已达到目标分布。 -- 通过 [`INFORMATION_SCHEMA.TABLES`](/information-schema/information-schema-tables.md) 表的 `TIDB_AFFINITY` 列查看表的亲和性等级。 -- 通过 [`INFORMATION_SCHEMA.PARTITIONS`](/information-schema/information-schema-partitions.md) 表的 `TIDB_AFFINITY` 列查看分区的亲和性等级。 +- 查询 [`INFORMATION_SCHEMA.TABLES`](/information-schema/information-schema-tables.md) 表的 `TIDB_AFFINITY` 列查看表的亲和性等级。 +- 查询 [`INFORMATION_SCHEMA.PARTITIONS`](/information-schema/information-schema-partitions.md) 表的 `TIDB_AFFINITY` 列查看分区的亲和性等级。 ## 注意事项 -- **Region 的自动分裂**：当 Region 属于某个亲和性分组且亲和性生效时，Region 默认不会自动分裂（除非 Region 大小超过 [`schedule.max-affinity-merge-region-size`](/pd-configuration-file.md#max-affinity-merge-region-size-从-v855-和-v900-版本开始引入) 的四倍以上），以避免产生过多 Region 影响亲和性效果。手动执行的 [`ADMIN SPLIT`](/sql-statements/sql-statement-admin-split.md) 不受此限制。 +- **Region 的自动分裂**：当 Region 属于某个亲和性分组且亲和性生效时，Region 默认不会自动分裂，以避免产生过多 Region 影响亲和性效果。只有当 Region 大小超过 [`schedule.max-affinity-merge-region-size`](/pd-configuration-file.md#max-affinity-merge-region-size-从-v855-和-v900-版本开始引入) 值的四倍时，才会触发自动分裂。手动执行的 [`ADMIN SPLIT`](/sql-statements/sql-statement-admin-split.md) 不受此限制。 -- **降级与过期机制**：如果亲和性分组中目标 Leader 或 Voter 所在的 TiKV 节点处于不可用状态（例如节点宕机或磁盘空间不足），Leader 被驱逐，或与现有放置规则发生冲突时，PD 会将该亲和性分组标记为降级状态。在降级期间，对应表或分区的亲和性调度将暂停。 +- **降级与过期机制**：如果亲和性分组中目标 Leader 或 Voter 所在的 TiKV 节点处于不可用状态（例如节点宕机或磁盘空间不足）、Leader 被驱逐，或与现有放置规则发生冲突时，PD 会将该亲和性分组标记为降级状态。在降级期间，对应表或分区的亲和性调度将暂停。 - - 若在 10 分钟内相关节点恢复正常，PD 会继续按照原有亲和性设置进行调度。 - - 若超过 10 分钟仍未恢复，该亲和性分组将被标记为过期，此时 PD 会先恢复常规调度行为（[`SHOW AFFINITY`](/sql-statements/sql-statement-show-affinity.md) 的状态会回到 `Pending`），然后自动更新亲和性分组中的 Leader 和 Voter 以重新启用亲和性调度。 + - 若相关节点在 10 分钟内恢复正常，PD 会继续按照原有亲和性设置进行调度。 + - 若超过 10 分钟仍未恢复，该亲和性分组将被标记为过期。此时 PD 会先恢复常规调度行为（[`SHOW AFFINITY`](/sql-statements/sql-statement-show-affinity.md) 的状态会回到 `Pending`），然后自动更新亲和性分组中的 Leader 和 Voter，以重新启用亲和性调度。 ## 相关语句与配置 From 882d66d0e573934823b5345ae56317cf2889a0d3 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Tue, 6 Jan 2026 12:49:44 +0800 Subject: [PATCH 26/30] Apply suggestions from code review Co-authored-by: Aolin --- information-schema/information-schema-tables.md | 8 ++++---- pd-configuration-file.md | 5 +++-- sql-statements/sql-statement-create-table.md | 6 +++--- sql-statements/sql-statement-show-affinity.md | 16 +++++++++------- 4 files changed, 19 insertions(+), 16 deletions(-) diff --git a/information-schema/information-schema-tables.md b/information-schema/information-schema-tables.md index 1aa8d98ce4be..a1b38ae3294a 100644 --- a/information-schema/information-schema-tables.md +++ b/information-schema/information-schema-tables.md @@ -131,8 +131,8 @@ SHOW TABLES - `"NOT_SHARDED(PK_IS_HANDLE)"`：一个定义了整型主键的表未被 Shard。 - `"PK_AUTO_RANDOM_BITS={bit_number}"`：一个定义了整型主键的表由于定义了 `AUTO_RANDOM` 而被 Shard。 - `"SHARD_BITS={bit_number}"`：表使用 `SHARD_ROW_ID_BITS={bit_number}` 进行了 Shard。 - - NULL：表属于系统表或 View，无法被 Shard。 -* `TIDB_PK_TYPE`：表的主键类型，可能的值包括 `CLUSTERED`（聚簇主键）和 `NONCLUSTERED`。 -* `TIDB_PLACEMENT_POLICY_NAME`：应用于该表的放置策略名称。 + - `NULL`：表属于系统表或 View，无法被 Shard。 +* `TIDB_PK_TYPE`：表的主键类型，可能的值包括 `CLUSTERED`（聚簇主键）和 `NONCLUSTERED`（非聚簇主键）。 +* `TIDB_PLACEMENT_POLICY_NAME`：应用于该表的放置策略 (placement policy) 名称。 * `TIDB_TABLE_MODE`：表的模式，例如 `Normal`、`Import` 或 `Restore`。 -* `TIDB_AFFINITY`：表的亲和性等级，非分区表为 `table`，分区表为 `partition`，未开启亲和性时为 NULL。 +* `TIDB_AFFINITY`：表的亲和性等级，非分区表为 `table`，分区表为 `partition`，未开启亲和性时为 `NULL`。 diff --git a/pd-configuration-file.md b/pd-configuration-file.md index dd743e361b71..7d5052b2af0d 100644 --- a/pd-configuration-file.md +++ b/pd-configuration-file.md @@ -289,7 +289,8 @@ pd-server 相关配置项。 ### `max-affinity-merge-region-size` 从 v8.5.5 和 v9.0.0 版本开始引入 -- 控制属于同一[亲和性](table-affinity.md)分组中相邻的小 Region 自动合并的阈值。当 Region 属于某个亲和性分组，且其大小小于该配置值时，PD 会尝试将该 Region 与同一亲和性分组中相邻的其它小 Region 进行合并，以减少 Region 数量并维持亲和性效果。设置为 `0` 表示关闭亲和性分组中相邻小 Region 的自动合并。 ++ 控制属于同一[亲和性](/table-affinity.md)分组中相邻的小 Region 自动合并的阈值。当 Region 属于某个亲和性分组，且其大小小于该配置值时，PD 会尝试将该 Region 与同一亲和性分组中相邻的其它小 Region 进行合并，以减少 Region 数量并保持亲和性效果。 ++ 设置为 `0` 表示关闭亲和性分组中相邻小 Region 的自动合并。 + 默认值：256 + 单位：MiB @@ -370,7 +371,7 @@ pd-server 相关配置项。 ### `affinity-schedule-limit` 从 v8.5.5 和 v9.0.0 版本开始引入 -+ 控制同时进行的[亲和性](table-affinity.md)调度任务数量。设置为 `0` 表示禁用亲和性调度。 ++ 控制同时进行的[亲和性](/table-affinity.md)调度任务数量。设置为 `0` 表示禁用亲和性调度。 + 默认值：0 ### `high-space-ratio` diff --git a/sql-statements/sql-statement-create-table.md b/sql-statements/sql-statement-create-table.md index bc39944d1ed9..2c571491dad6 100644 --- a/sql-statements/sql-statement-create-table.md +++ b/sql-statements/sql-statement-create-table.md @@ -171,12 +171,12 @@ TiDB 支持以下 `table_option`。TiDB 会解析并忽略其他 `table_option` |`CHARACTER SET` |指定该表所使用的[字符集](/character-set-and-collation.md) | `CHARACTER SET` = 'utf8mb4'| |`COLLATE` |指定该表所使用的字符集排序规则 | `COLLATE` = 'utf8mb4_bin'| |`COMMENT` |注释信息 | `COMMENT` = 'comment info'| -|`AFFINITY` |为表或分区开启亲和性调度。非分区表可设置为 `'table'`，分区表可设置为 `'partition'`；设置为 `'none'` 或留空可关闭 |`AFFINITY` = 'table'| +|`AFFINITY` |为表或分区开启亲和性调度。非分区表可设置为 `'table'`，分区表可设置为 `'partition'`。设置为 `'none'` 或留空可关闭亲和性调度 |`AFFINITY` = 'table'| > **注意：** > -> 在 TiDB 配置文件中，`split-table` 默认开启。当该配置项开启时，建表操作会为每个表建立单独的 Region，详情参见 [TiDB 配置文件描述](/tidb-configuration-file.md)。 -> 使用 `AFFINITY` 时，当前不支持对该表进行分区方案变更（如添加、删除、重组或交换分区），也不支持在临时表或视图上设置该选项。 +> - 在 TiDB 配置文件中，`split-table` 默认开启。当该配置项开启时，建表操作会为每个表建立单独的 Region，详情参见 [TiDB 配置文件描述](/tidb-configuration-file.md)。 +> - 使用 `AFFINITY` 时，当前不支持对该表进行分区方案变更（如添加、删除、重组或交换分区），也不支持在临时表或视图上设置该选项。 ## 示例 diff --git a/sql-statements/sql-statement-show-affinity.md b/sql-statements/sql-statement-show-affinity.md index 57b65182df72..c027c99a007d 100644 --- a/sql-statements/sql-statement-show-affinity.md +++ b/sql-statements/sql-statement-show-affinity.md @@ -5,7 +5,7 @@ summary: 介绍 TiDB 数据库中 SHOW AFFINITY 的使用概况。 # SHOW AFFINITY 从 v8.5.5 和 v9.0.0 版本开始引入 -`SHOW AFFINITY` 语句用于查看配置了 `AFFINITY` 选项的表的[亲和性](table-affinity.md)调度信息，以及 PD 当前记录的目标副本分布。 +`SHOW AFFINITY` 语句用于查看配置了 `AFFINITY` 选项的表的[亲和性](/table-affinity.md)调度信息，以及 PD 当前记录的目标副本分布。 ## 语法图 @@ -14,10 +14,12 @@ ShowAffinityStmt ::= "SHOW" "AFFINITY" ShowLikeOrWhereOpt ``` -`SHOW AFFINITY` 支持使用 `LIKE` 或 `WHERE` 过滤表名。 +`SHOW AFFINITY` 支持使用 `LIKE` 或 `WHERE` 子句过滤表名。 ## 示例 +以下示例创建两个启用了亲和性调度的表，并查看其调度信息： + ```sql CREATE TABLE t1 (a INT) AFFINITY = 'table'; CREATE TABLE tp1 (a INT) AFFINITY = 'partition' PARTITION BY HASH(a) PARTITIONS 2; @@ -39,15 +41,15 @@ SHOW AFFINITY; 各列含义如下： -- `Leader_store_id`、`Voter_store_ids`：PD 为该表或分区记录的目标 Leader 副本和 Voter 副本所在的 TiKV Store ID。如果亲和性分组尚未确定目标副本位置或 [`schedule.affinity-schedule-limit`](/pd-configuration-file.md#affinity-schedule-limit-从-v855-和-v900-版本开始引入) 为 `0` ，则显示为 `NULL`。 -- `Status`：表示当前亲和性调度的状态。 +- `Leader_store_id`、`Voter_store_ids`：PD 为该表或分区记录的目标 Leader 副本和 Voter 副本所在的 TiKV Store ID。如果亲和性分组尚未确定目标副本位置或 [`schedule.affinity-schedule-limit`](/pd-configuration-file.md#affinity-schedule-limit-从-v855-和-v900-版本开始引入) 为 `0`，则显示为 `NULL`。 +- `Status`：表示当前亲和性调度的状态。可能的取值如下： - `Pending`：PD 尚未对该表或分区进行亲和性调度（比如未确定 Leader 或 Voter 时）。 - `Preparing`：PD 正在调度 Region 以满足亲和性要求。 - `Stable`：所有 Region 已达到目标分布。 -- `REGION_COUNT`：当前在该亲和性组中的 Region 数量。 +- `Region_count`：当前在该亲和性组中的 Region 数量。 - `Affinity_region_count`：当前已满足亲和性副本分布要求的 Region 数量。 - - 当 `Affinity_region_count` < `Region_count` 时，表示仍有部分 Region 尚未完成基于亲和性的副本调度。 - - 当 `Affinity_region_count` = `Region_count` 时，表示基于亲和性的 Region 副本迁移调度已完成，也就意味着所有 Region 的分布已经满足亲和性要求，但并不意味着相关 Region 的合并操作已完成。 + - 当 `Affinity_region_count` 小于 `Region_count` 时，表示仍有部分 Region 尚未完成基于亲和性的副本调度。 + - 当 `Affinity_region_count` 等于 `Region_count` 时，表示基于亲和性的 Region 副本迁移调度已完成，也就意味着所有 Region 的分布已经满足亲和性要求，但并不代表相关 Region 的合并操作已完成。 ## MySQL 兼容性 From 4f1b8917925dac139b4c249e48a9ee5406d56a43 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Tue, 6 Jan 2026 13:33:42 +0800 Subject: [PATCH 27/30] update ADMIN SPLIT --- table-affinity.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/table-affinity.md b/table-affinity.md index c51017e1b02a..baf984c1874c 100644 --- a/table-affinity.md +++ b/table-affinity.md @@ -95,7 +95,7 @@ ALTER TABLE t1 AFFINITY = ''; ## 注意事项 -- **Region 的自动分裂**：当 Region 属于某个亲和性分组且亲和性生效时，Region 默认不会自动分裂，以避免产生过多 Region 影响亲和性效果。只有当 Region 大小超过 [`schedule.max-affinity-merge-region-size`](/pd-configuration-file.md#max-affinity-merge-region-size-从-v855-和-v900-版本开始引入) 值的四倍时，才会触发自动分裂。手动执行的 [`ADMIN SPLIT`](/sql-statements/sql-statement-admin-split.md) 不受此限制。 +- **Region 的自动分裂**：当 Region 属于某个亲和性分组且亲和性生效时，Region 默认不会自动分裂，以避免产生过多 Region 影响亲和性效果。只有当 Region 大小超过 [`schedule.max-affinity-merge-region-size`](/pd-configuration-file.md#max-affinity-merge-region-size-从-v855-和-v900-版本开始引入) 值的四倍时，才会触发自动分裂。需要注意的是，非 TiKV 或 PD 自动触发的 Region 分裂（例如手动执行的 [`SPLIT TABLE`](/sql-statements/sql-statement-split-region.md)）不受此限制。 - **降级与过期机制**：如果亲和性分组中目标 Leader 或 Voter 所在的 TiKV 节点处于不可用状态（例如节点宕机或磁盘空间不足）、Leader 被驱逐，或与现有放置规则发生冲突时，PD 会将该亲和性分组标记为降级状态。在降级期间，对应表或分区的亲和性调度将暂停。 From 32894690f95955d22f4dea33038c0e519b07c3ed Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Thu, 8 Jan 2026 14:05:41 +0800 Subject: [PATCH 28/30] format udpates --- table-affinity.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/table-affinity.md b/table-affinity.md index baf984c1874c..baedb36a3c22 100644 --- a/table-affinity.md +++ b/table-affinity.md @@ -31,9 +31,9 @@ PD 亲和性调度特性默认关闭。在设置表或分区的亲和性前， 例如，执行以下命令将该配置项设置为 `4`，表示允许 PD 最多同时执行 4 个亲和性调度任务： - ```bash - pd-ctl config set schedule.affinity-schedule-limit 4 - ``` + ```bash + pd-ctl config set schedule.affinity-schedule-limit 4 + ``` 2. （可选）根据需要设置 PD 配置项 [`schedule.max-affinity-merge-region-size`](/pd-configuration-file.md#max-affinity-merge-region-size-从-v855-和-v900-版本开始引入)（默认值为 `256`，单位为 MiB），用于控制属于同一亲和性分组中相邻的小 Region 自动合并的阈值。设置为 `0` 表示关闭亲和性分组中相邻的小 Region 的自动合并。 @@ -104,6 +104,6 @@ ALTER TABLE t1 AFFINITY = ''; ## 相关语句与配置 -- [`CREATE TABLE`](/sql-statements/sql-statement-create-table.md) 或 [`ALTER TABLE`](/sql-statements/sql-statement-alter-table.md) 的 `AFFINITY` 选项 +- [`CREATE TABLE`](/sql-statements/sql-statement-create-table.md) 和 [`ALTER TABLE`](/sql-statements/sql-statement-alter-table.md) 的 `AFFINITY` 选项 - [`SHOW AFFINITY`](/sql-statements/sql-statement-show-affinity.md) - PD 配置项：[`schedule.affinity-schedule-limit`](/pd-configuration-file.md#affinity-schedule-limit-从-v855-和-v900-版本开始引入) 和 [`schedule.max-affinity-merge-region-size`](/pd-configuration-file.md#max-affinity-merge-region-size-从-v855-和-v900-版本开始引入) \ No newline at end of file From 97d6a140af5dcbc737513dc90af580e859ab391f Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Tue, 13 Jan 2026 18:21:07 +0800 Subject: [PATCH 29/30] remove the info about v9.0.0 --- pd-configuration-file.md | 4 ++-- sql-statements/sql-statement-show-affinity.md | 4 ++-- table-affinity.md | 8 ++++---- 3 files changed, 8 insertions(+), 8 deletions(-) diff --git a/pd-configuration-file.md b/pd-configuration-file.md index 7d5052b2af0d..910e075d8f69 100644 --- a/pd-configuration-file.md +++ b/pd-configuration-file.md @@ -287,7 +287,7 @@ pd-server 相关配置项。 + 控制 Region Merge 的 key 上限，当 Region key 大于指定值时 PD 不会将其与相邻的 Region 合并。 + 默认：540000。在 v8.4.0 之前，默认值为 200000；从 v8.4.0 开始，默认值为 540000。 -### `max-affinity-merge-region-size` 从 v8.5.5 和 v9.0.0 版本开始引入 +### `max-affinity-merge-region-size` 从 v8.5.5 版本开始引入 + 控制属于同一[亲和性](/table-affinity.md)分组中相邻的小 Region 自动合并的阈值。当 Region 属于某个亲和性分组，且其大小小于该配置值时，PD 会尝试将该 Region 与同一亲和性分组中相邻的其它小 Region 进行合并，以减少 Region 数量并保持亲和性效果。 + 设置为 `0` 表示关闭亲和性分组中相邻小 Region 的自动合并。 @@ -369,7 +369,7 @@ pd-server 相关配置项。 + 同时进行的 Region Merge 调度的任务，设置为 0 则关闭 Region Merge。 + 默认值：8 -### `affinity-schedule-limit` 从 v8.5.5 和 v9.0.0 版本开始引入 +### `affinity-schedule-limit` 从 v8.5.5 版本开始引入 + 控制同时进行的[亲和性](/table-affinity.md)调度任务数量。设置为 `0` 表示禁用亲和性调度。 + 默认值：0 diff --git a/sql-statements/sql-statement-show-affinity.md b/sql-statements/sql-statement-show-affinity.md index c027c99a007d..500d16fbd2c1 100644 --- a/sql-statements/sql-statement-show-affinity.md +++ b/sql-statements/sql-statement-show-affinity.md @@ -3,7 +3,7 @@ title: SHOW AFFINITY summary: 介绍 TiDB 数据库中 SHOW AFFINITY 的使用概况。 --- -# SHOW AFFINITY 从 v8.5.5 和 v9.0.0 版本开始引入 +# SHOW AFFINITY 从 v8.5.5 开始引入 `SHOW AFFINITY` 语句用于查看配置了 `AFFINITY` 选项的表的[亲和性](/table-affinity.md)调度信息，以及 PD 当前记录的目标副本分布。 @@ -41,7 +41,7 @@ SHOW AFFINITY; 各列含义如下： -- `Leader_store_id`、`Voter_store_ids`：PD 为该表或分区记录的目标 Leader 副本和 Voter 副本所在的 TiKV Store ID。如果亲和性分组尚未确定目标副本位置或 [`schedule.affinity-schedule-limit`](/pd-configuration-file.md#affinity-schedule-limit-从-v855-和-v900-版本开始引入) 为 `0`，则显示为 `NULL`。 +- `Leader_store_id`、`Voter_store_ids`：PD 为该表或分区记录的目标 Leader 副本和 Voter 副本所在的 TiKV Store ID。如果亲和性分组尚未确定目标副本位置或 [`schedule.affinity-schedule-limit`](/pd-configuration-file.md#affinity-schedule-limit-从-v855-版本开始引入) 为 `0`，则显示为 `NULL`。 - `Status`：表示当前亲和性调度的状态。可能的取值如下： - `Pending`：PD 尚未对该表或分区进行亲和性调度（比如未确定 Leader 或 Voter 时）。 - `Preparing`：PD 正在调度 Region 以满足亲和性要求。 diff --git a/table-affinity.md b/table-affinity.md index baedb36a3c22..621997732163 100644 --- a/table-affinity.md +++ b/table-affinity.md @@ -3,7 +3,7 @@ title: 表级数据亲和性 summary: 通过为表或分区配置亲和性约束，控制 Region 副本的分布并查看调度状态。 --- -# 表级数据亲和性 从 v8.5.5 和 v9.0.0 开始引入 +# 表级数据亲和性 从 v8.5.5 开始引入 > **警告：** > @@ -35,7 +35,7 @@ PD 亲和性调度特性默认关闭。在设置表或分区的亲和性前， pd-ctl config set schedule.affinity-schedule-limit 4 ``` -2. （可选）根据需要设置 PD 配置项 [`schedule.max-affinity-merge-region-size`](/pd-configuration-file.md#max-affinity-merge-region-size-从-v855-和-v900-版本开始引入)（默认值为 `256`，单位为 MiB），用于控制属于同一亲和性分组中相邻的小 Region 自动合并的阈值。设置为 `0` 表示关闭亲和性分组中相邻的小 Region 的自动合并。 +2. （可选）根据需要设置 PD 配置项 [`schedule.max-affinity-merge-region-size`](/pd-configuration-file.md#max-affinity-merge-region-size-从-v855-版本开始引入)（默认值为 `256`，单位为 MiB），用于控制属于同一亲和性分组中相邻的小 Region 自动合并的阈值。设置为 `0` 表示关闭亲和性分组中相邻的小 Region 的自动合并。 ## 使用方法 @@ -95,7 +95,7 @@ ALTER TABLE t1 AFFINITY = ''; ## 注意事项 -- **Region 的自动分裂**：当 Region 属于某个亲和性分组且亲和性生效时，Region 默认不会自动分裂，以避免产生过多 Region 影响亲和性效果。只有当 Region 大小超过 [`schedule.max-affinity-merge-region-size`](/pd-configuration-file.md#max-affinity-merge-region-size-从-v855-和-v900-版本开始引入) 值的四倍时，才会触发自动分裂。需要注意的是，非 TiKV 或 PD 自动触发的 Region 分裂（例如手动执行的 [`SPLIT TABLE`](/sql-statements/sql-statement-split-region.md)）不受此限制。 +- **Region 的自动分裂**：当 Region 属于某个亲和性分组且亲和性生效时，Region 默认不会自动分裂，以避免产生过多 Region 影响亲和性效果。只有当 Region 大小超过 [`schedule.max-affinity-merge-region-size`](/pd-configuration-file.md#max-affinity-merge-region-size-从-v855-版本开始引入) 值的四倍时，才会触发自动分裂。需要注意的是，非 TiKV 或 PD 自动触发的 Region 分裂（例如手动执行的 [`SPLIT TABLE`](/sql-statements/sql-statement-split-region.md)）不受此限制。 - **降级与过期机制**：如果亲和性分组中目标 Leader 或 Voter 所在的 TiKV 节点处于不可用状态（例如节点宕机或磁盘空间不足）、Leader 被驱逐，或与现有放置规则发生冲突时，PD 会将该亲和性分组标记为降级状态。在降级期间，对应表或分区的亲和性调度将暂停。 @@ -106,4 +106,4 @@ ALTER TABLE t1 AFFINITY = ''; - [`CREATE TABLE`](/sql-statements/sql-statement-create-table.md) 和 [`ALTER TABLE`](/sql-statements/sql-statement-alter-table.md) 的 `AFFINITY` 选项 - [`SHOW AFFINITY`](/sql-statements/sql-statement-show-affinity.md) -- PD 配置项：[`schedule.affinity-schedule-limit`](/pd-configuration-file.md#affinity-schedule-limit-从-v855-和-v900-版本开始引入) 和 [`schedule.max-affinity-merge-region-size`](/pd-configuration-file.md#max-affinity-merge-region-size-从-v855-和-v900-版本开始引入) \ No newline at end of file +- PD 配置项：[`schedule.affinity-schedule-limit`](/pd-configuration-file.md#affinity-schedule-limit-从-v855-版本开始引入) 和 [`schedule.max-affinity-merge-region-size`](/pd-configuration-file.md#max-affinity-merge-region-size-从-v855-版本开始引入) \ No newline at end of file From 5f4cd7aa4184de6fde8d90879fbb9fb61a356015 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Tue, 13 Jan 2026 18:21:39 +0800 Subject: [PATCH 30/30] Update table-affinity.md --- table-affinity.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/table-affinity.md b/table-affinity.md index 621997732163..f0a818fd0667 100644 --- a/table-affinity.md +++ b/table-affinity.md @@ -27,7 +27,7 @@ summary: 通过为表或分区配置亲和性约束，控制 Region 副本的分 PD 亲和性调度特性默认关闭。在设置表或分区的亲和性前，请开启并配置该特性。 -1. 将 PD 配置项 [`schedule.affinity-schedule-limit`](/pd-configuration-file.md#affinity-schedule-limit-从-v855-和-v900-版本开始引入) 设置为大于 `0` 的值，以开启 PD 的亲和性调度。 +1. 将 PD 配置项 [`schedule.affinity-schedule-limit`](/pd-configuration-file.md#affinity-schedule-limit-从-v855-版本开始引入) 设置为大于 `0` 的值，以开启 PD 的亲和性调度。 例如，执行以下命令将该配置项设置为 `4`，表示允许 PD 最多同时执行 4 个亲和性调度任务：