v8.5.5 pd,tidb: support affinity schedule (#21207) (#21273)

ti-chi-bot · web-flow · commit 7304166f4f69 · 2026-01-13T10:45:32.000Z
diff --git a/TOC.md b/TOC.md
@@ -883,6 +883,7 @@
       - [`SET ROLE`](/sql-statements/sql-statement-set-role.md)
       - [`SET TRANSACTION`](/sql-statements/sql-statement-set-transaction.md)
       - [`SET <variable>`](/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)
@@ -1000,6 +1001,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
@@ -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
@@ -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" >}}
@@ -76,6 +80,10 @@ SELECT * FROM tables WHERE table_schema='mysql' AND table_name='user'\G
             TABLE_COMMENT: 
             TIDB_TABLE_ID: 5
 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,12 +123,16 @@ SHOW TABLES
 * `CREATE_OPTIONS`：创建选项。
 * `TABLE_COMMENT`：表的注释、备注。
 
-表中的信息大部分定义自 MySQL，只有两列是 TiDB 新增的：
+表中的大部分列都和 MySQL 相同，除了以下列是 TiDB 新增的：
 
 * `TIDB_TABLE_ID`：标识表的内部 ID，该 ID 在一个 TiDB 集群内部唯一。
 * `TIDB_ROW_ID_SHARDING_INFO`：标识表的 Sharding 类型，可能的值为：
     - `"NOT_SHARDED"`：表未被 Shard。
     - `"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。
+    - `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`。
diff --git a/pd-configuration-file.md b/pd-configuration-file.md
@@ -287,6 +287,13 @@ pd-server 相关配置项。
 + 控制 Region Merge 的 key 上限，当 Region key 大于指定值时 PD 不会将其与相邻的 Region 合并。
 + 默认：540000。在 v8.4.0 之前，默认值为 200000；从 v8.4.0 开始，默认值为 540000。
 
+### `max-affinity-merge-region-size` <span class="version-mark">从 v8.5.5 版本开始引入</span>
+
++ 控制属于同一[亲和性](/table-affinity.md)分组中相邻的小 Region 自动合并的阈值。当 Region 属于某个亲和性分组，且其大小小于该配置值时，PD 会尝试将该 Region 与同一亲和性分组中相邻的其它小 Region 进行合并，以减少 Region 数量并保持亲和性效果。
++ 设置为 `0` 表示关闭亲和性分组中相邻小 Region 的自动合并。
++ 默认值：256
++ 单位：MiB
+
 ### `patrol-region-interval`
 
 + 控制 checker 检查 Region 健康状态的运行频率，越短则运行越快，通常状况不需要调整
@@ -362,6 +369,11 @@ pd-server 相关配置项。
 + 同时进行的 Region Merge 调度的任务，设置为 0 则关闭 Region Merge。
 + 默认值：8
 
+### `affinity-schedule-limit` <span class="version-mark">从 v8.5.5 版本开始引入</span>
+
++ 控制同时进行的[亲和性](/table-affinity.md)调度任务数量。设置为 `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
@@ -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
@@ -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)。
+> - 在 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
@@ -0,0 +1,61 @@
+---
+title: SHOW AFFINITY
+summary: 介绍 TiDB 数据库中 SHOW AFFINITY 的使用概况。
+---
+
+# SHOW AFFINITY <span class="version-mark">从 v8.5.5 开始引入</span>
+
+`SHOW AFFINITY` 语句用于查看配置了 `AFFINITY` 选项的表的[亲和性](/table-affinity.md)调度信息，以及 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 副本所在的 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 以满足亲和性要求。
+    - `Stable`：所有 Region 已达到目标分布。
+- `Region_count`：当前在该亲和性组中的 Region 数量。
+- `Affinity_region_count`：当前已满足亲和性副本分布要求的 Region 数量。
+    - 当 `Affinity_region_count` 小于 `Region_count` 时，表示仍有部分 Region 尚未完成基于亲和性的副本调度。
+    - 当 `Affinity_region_count` 等于 `Region_count` 时，表示基于亲和性的 Region 副本迁移调度已完成，也就意味着所有 Region 的分布已经满足亲和性要求，但并不代表相关 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
@@ -0,0 +1,109 @@
+---
+title: 表级数据亲和性
+summary: 通过为表或分区配置亲和性约束，控制 Region 副本的分布并查看调度状态。
+---
+
+# 表级数据亲和性 <span class="version-mark">从 v8.5.5 开始引入</span>
+
+> **警告：**
+>
+> 该功能为实验特性，不建议在生产环境中使用。该功能可能会在未事先通知的情况下发生变化或删除。如果发现 bug，请在 GitHub 上提 [issue](https://github.com/pingcap/tidb/issues) 反馈。
+
+表级数据亲和性是 PD 在表级别上的数据分布调度机制，用于控制同一个表或分区中 Region 的 Leader 和 Voter 副本在 TiKV 集群中的分布。
+
+开启 PD 数据亲和性调度，并将表的 `AFFINITY` 选项设置为 `table` 或 `partition` 后，PD 会将同一张表或同一个分区的 Region 归入同一个亲和性分组，并在调度过程中优先将这些 Region 的 Leader 和 Voter 副本放置到相同的少数 TiKV 节点上，从而减少查询过程中跨节点访问带来的网络延迟，提升查询性能。
+
+## 使用限制
+
+使用表级数据亲和性前，请注意以下限制：
+
+- 在 [PD 微服务模式](/pd-microservices.md)下，该功能不会生效。
+- [临时表](/temporary-tables.md)和[视图](/views.md)不支持配置数据亲和性。
+- 为[分区表](/partitioned-table.md)配置数据亲和性后，**不支持修改该表的分区方案**，包括新增、删除、重组或交换分区。如需调整分区配置，请先移除该表的亲和性设置。
+- **数据量较大时需提前评估磁盘容量**：开启数据亲和性后，PD 会优先将表或分区的 Region 调度到相同的少数 TiKV 节点上。对于数据量较大的表或分区，可能导致这些节点的磁盘使用率显著升高。建议提前评估磁盘容量并做好监控。
+- 数据亲和性调度仅影响 Leader 和 Voter 副本的分布。如果表有 Learner 副本（如 TiFlash），Learner 副本的分布不受亲和性配置影响。
+
+## 前提条件
+
+PD 亲和性调度特性默认关闭。在设置表或分区的亲和性前，请开启并配置该特性。
+
+1. 将 PD 配置项 [`schedule.affinity-schedule-limit`](/pd-configuration-file.md#affinity-schedule-limit-从-v855-版本开始引入) 设置为大于 `0` 的值，以开启 PD 的亲和性调度。
+
+    例如，执行以下命令将该配置项设置为 `4`，表示允许 PD 最多同时执行 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-版本开始引入)（默认值为 `256`，单位为 MiB），用于控制属于同一亲和性分组中相邻的小 Region 自动合并的阈值。设置为 `0` 表示关闭亲和性分组中相邻的小 Region 的自动合并。
+
+## 使用方法
+
+本节介绍如何配置表或分区的亲和性，以及如何查看亲和性调度状态。
+
+### 配置表或分区的亲和性
+
+你可以通过 `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 分钟内恢复为默认状态。 |
+
+**示例**：
+
+创建非分区表时开启该表的亲和性：
+
+```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';
+```
+
+关闭表的亲和性：
+
+```sql
+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 默认不会自动分裂，以避免产生过多 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 会将该亲和性分组标记为降级状态。在降级期间，对应表或分区的亲和性调度将暂停。
+
+    - 若相关节点在 10 分钟内恢复正常，PD 会继续按照原有亲和性设置进行调度。
+    - 若超过 10 分钟仍未恢复，该亲和性分组将被标记为过期。此时 PD 会先恢复常规调度行为（[`SHOW AFFINITY`](/sql-statements/sql-statement-show-affinity.md) 的状态会回到 `Pending`），然后自动更新亲和性分组中的 Leader 和 Voter，以重新启用亲和性调度。
+
+## 相关语句与配置
+
+- [`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-版本开始引入) 和 [`schedule.max-affinity-merge-region-size`](/pd-configuration-file.md#max-affinity-merge-region-size-从-v855-版本开始引入)
