pd,tidb: support affinity schedule

TOC.md

@@ -884,6 +884,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)
@@ -1004,6 +1005,7 @@
     - [临时表](/temporary-tables.md)
     - [缓存表](/cached-tables.md)
     - [外键约束](/foreign-key.md)
+    - [表级数据亲和性](/table-affinity.md)
     - 字符集和排序规则
       - [概述](/character-set-and-collation.md)
       - [GBK](/character-set-gbk.md)

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)
 ```
 

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。

pd-configuration-file.md

@@ -288,6 +288,12 @@ 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>
+
++ 当 Region 属于亲和性分组且大小小于该值时，PD 会尝试将其与相邻的同一亲和性分组的 Region 合并。设置为 `0` 表示关闭配置了亲和性的 Region 合并。
++ 默认：256
++ 单位：MiB
+
 ### `patrol-region-interval`
 
 + 控制 checker 检查 Region 健康状态的运行频率，越短则运行越快，通常状况不需要调整
@@ -363,6 +369,11 @@ pd-server 相关配置项。
 + 同时进行的 Region Merge 调度的任务，设置为 0 则关闭 Region Merge。
 + 默认值：8
 
+### `affinity-schedule-limit` <span class="version-mark">从 v8.5.5 版本开始引入</span>
+
++ 控制同时进行的亲和性调度任务数量。设置为 `0` 表示禁用亲和性调度。
++ 默认值：0
+
 ### `high-space-ratio`
 
 + 设置 store 空间充裕的阈值。当节点的空间占用比例小于该阈值时，PD 调度时会忽略节点的剩余空间，主要根据实际数据量进行均衡。此配置仅在 `region-score-formula-version = v1` 时生效。

sql-statements/sql-statement-alter-table.md

@@ -55,6 +55,7 @@ AlterTableSpec ::=
         | TTLEnable EqOpt ( 'ON' | 'OFF' )
         | TTLJobInterval EqOpt stringLit
     )
+|   'AFFINITY' EqOpt stringLit
 |   PlacementPolicyOption
 
 PlacementPolicyOption ::=
@@ -173,6 +174,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)。
 

sql-statements/sql-statement-create-table.md

@@ -118,6 +118,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 ::=
@@ -172,10 +173,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` 时，当前不支持对该表进行分区方案变更（如添加、删除、重组或交换分区），也不支持在临时表或视图上设置该选项。
 
 ## 示例
 

sql-statements/sql-statement-show-affinity.md

@@ -0,0 +1,54 @@
+---
+title: SHOW AFFINITY
+summary: 介绍 TiDB 数据库中 SHOW AFFINITY 的使用概况。
+---
+
+# SHOW AFFINITY <span class="version-mark">从 v8.5.5 开始引入</span>
+
+`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)

table-affinity.md

@@ -0,0 +1,78 @@
+---
+title: 表级数据亲和性
+summary: 通过表或分区的亲和性约束，控制 Region 的副本分布并查看调度状态。
+---
+
+# 表级数据亲和性 <span class="version-mark">实验特性，自 v8.5.5 起提供</span>
+
+> **警告：**
+>
+> 该功能为实验特性，不建议在生产环境中使用。行为和接口可能在未来版本变更或移除。如遇问题，请在 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`。