distribute-table: support to scatter the region distribution of the given table and engine

TOC.md

@@ -771,6 +771,7 @@
       - [`BATCH`](/sql-statements/sql-statement-batch.md)
       - [`BEGIN`](/sql-statements/sql-statement-begin.md)
       - [`CALIBRATE RESOURCE`](/sql-statements/sql-statement-calibrate-resource.md)
+      - [`CANCEL DISTRIBUTION JOB`](/sql-statements/sql-statement-cancel-distribution-job.md)
       - [`CANCEL IMPORT JOB`](/sql-statements/sql-statement-cancel-import-job.md)
       - [`COMMIT`](/sql-statements/sql-statement-commit.md)
       - [`CREATE BINDING`](/sql-statements/sql-statement-create-binding.md)
@@ -788,6 +789,7 @@
       - [`DELETE`](/sql-statements/sql-statement-delete.md)
       - [`DESC`](/sql-statements/sql-statement-desc.md)
       - [`DESCRIBE`](/sql-statements/sql-statement-describe.md)
+      - [`DISTRIBUTE TABLE`](/sql-statements/sql-statement-distribute-table.md)
       - [`DO`](/sql-statements/sql-statement-do.md)
       - [`DROP BINDING`](/sql-statements/sql-statement-drop-binding.md)
       - [`DROP DATABASE`](/sql-statements/sql-statement-drop-database.md)
@@ -852,6 +854,7 @@
       - [`SHOW CREATE DATABASE`](/sql-statements/sql-statement-show-create-database.md)
       - [`SHOW CREATE USER`](/sql-statements/sql-statement-show-create-user.md)
       - [`SHOW DATABASES`](/sql-statements/sql-statement-show-databases.md)
+      - [`SHOW DISTRIBUTION JOBS`](/sql-statements/sql-statement-show-distribution-jobs.md)
       - [`SHOW ENGINES`](/sql-statements/sql-statement-show-engines.md)
       - [`SHOW ERRORS`](/sql-statements/sql-statement-show-errors.md)
       - [`SHOW FIELDS FROM`](/sql-statements/sql-statement-show-fields-from.md)
@@ -874,6 +877,7 @@
       - [`SHOW STATS_META`](/sql-statements/sql-statement-show-stats-meta.md)
       - [`SHOW STATS_TOPN`](/sql-statements/sql-statement-show-stats-topn.md)
       - [`SHOW STATUS`](/sql-statements/sql-statement-show-status.md)
+      - [`SHOW TABLE DISTRIBUTION`](/sql-statements/sql-statement-show-table-distribution.md)
       - [`SHOW TABLE NEXT_ROW_ID`](/sql-statements/sql-statement-show-table-next-rowid.md)
       - [`SHOW TABLE REGIONS`](/sql-statements/sql-statement-show-table-regions.md)
       - [`SHOW TABLE STATUS`](/sql-statements/sql-statement-show-table-status.md)

sql-statements/sql-statement-cancel-distribution-job.md

@@ -0,0 +1,38 @@
+---
+title: CANCEL DISTRIBUTION
+summary: TiDB 数据库中 CANCEL DISTRIBUTION 的使用情况。
+---
+
+# CANCEL DISTRIBUTION
+
+`CANCEL DISTRIBUTION` 语句用于取消 TiDB 中通过 [`DISTRIBUTE TABLE`](sql-statements/sql-statement-distribute-table.md) 语句创建的 Region 调度任务。
+
+## 语法图
+
+```ebnf+diagram
+CancelDistributionJobsStmt ::=
+    'CANCEL' 'DISTRIBUTION' 'JOB' JobID
+```
+
+## 示例
+
+下面示例取消 ID 为 1 的导入任务：
+
+```sql
+CANCEL DISTRIBUTION JOB 1;
+```
+
+输出结果如下：
+
+```
+Query OK, 0 rows affected (0.01 sec)
+```
+
+## MySQL 兼容性
+
+该语句是 TiDB 对 MySQL 语法的扩展。
+
+## 另请参阅
+
+* [`DISTRIBUTE TABLE`](/sql-statements/sql-statement-distribute-table.md)
+* [`SHOW DISTRIBUTION JOB`](/sql-statements/sql-statement-show-distribution-jobs.md)

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

@@ -0,0 +1,119 @@
+---
+title: DISTRIBUTE TABLE
+summary: 介绍 TiDB 数据库中 DISTRIBUTE TABLE 的使用概况。
+---
+
+# DISTRIBUTE TABLE
+> **警告：**
+>
+> 该功能目前为实验特性，不建议在生产环境中使用。该功能可能会在未事先通知的情况下发生变化或删除。如果发现 bug，请在 GitHub 上提 [issue](https://github.com/pingcap/tidb/issues) 反馈。
+
+`DISTRIBUTE TABLE` 语句用于对指定表的 Region 进行重新打散和调度，以实现表级别的均衡分布。执行该语句可以防止个别 Region 集中在少数 TiFlash 或 TiKV 节点上，从而解决表中 Region 分布不均衡的问题。
+
+## 语法图
+
+```ebnf+diagram
+DistributeTableStmt ::=
+    "DISTRIBUTE" "TABLE" TableName PartitionNameListOpt "RULE" EqOrAssignmentEq Identifier "ENGINE" EqOrAssignmentEq Identifier "TIMEOUT" EqOrAssignmentEq Identifier
+
+TableName ::=
+    (SchemaName ".")? Identifier
+
+PartitionNameList ::=
+    "PARTITION" "(" PartitionName ("," PartitionName)* ")"
+```
+
+## 参数说明
+
+通过 `DISTRIBUTE TABLE` 语句重新调度表中的 Region 时，你可以根据需求指定存储引擎（如 TiFlash 或 TiKV）以及不同的 Raft 角色（如 Leader、Learner、Voter）进行均衡。
+
+- `RULE`：指定针对哪个 Raft 角色所在的 Region 进行均衡调度，可选值为 `"leader-scatter"`、`"peer-scatter"` 和 `"learner-scatter"`。
+- `ENGINE`：指定存储引擎，可选值为 `"tikv"` 和 `"tiflash"`。
+- `TIMEOUT`：指定打散操作的超时限制。 如果 PD 未在该时间内进行打散，打散任务将会自动退出。当未指定该参数时，默认值为 `"30m"`。
+
+
+## 示例
+
+对表 `t1` 在 TiKV 上的 Leader 所在的 Region 重新进行均衡调度：
+
+```sql
+CREATE TABLE t1 (a INT);
+...
+DISTRIBUTE TABLE t1 RULE= "leader-scatter" ENGINE = "tikv" TIMEOUT="1h"
+```
+
+```
++--------+
+| JOB_ID |
++--------+
+|    100 |
++--------+
+```
+
+对表 `t2` 在 TiFlash 上的 Learner 所在的 Region 重新进行均衡调度：
+
+```sql
+CREATE TABLE t2 (a INT);
+...
+DISTRIBUTE TABLE t2  RULE = "learner-scatter" ENGINE = "tiflash";
+```
+
+```
++--------+
+| JOB_ID |
++--------+
+|    101 |
++--------+
+```
+
+对分区表 `t3` 的 `p1` 和 `p2` 分区在 TiKV 上的 Peer 所在的 Region 重新进行均衡调度：
+
+```sql
+CREATE TABLE t3 ( a INT, b INT, INDEX idx(b)) PARTITION BY RANGE( a ) (
+    PARTITION p1 VALUES LESS THAN (10000),
+    PARTITION p2 VALUES LESS THAN (20000),
+    PARTITION p3 VALUES LESS THAN (MAXVALUE) );
+...
+DISTRIBUTE TABLE t3 PARTITION (p1, p2) RULE = "peer-scatter" ENGINE = "tikv";
+```
+
+```
++--------+
+| JOB_ID |
++--------+
+|    102 |
++--------+
+```
+
+对分区表 `t4` 的 `p1` 和 `p2` 分区在 TiFlash 上的 Learner 所在的 Region 重新进行均衡调度：
+
+```sql
+CREATE TABLE t4 ( a INT, b INT, INDEX idx(b)) PARTITION BY RANGE( a ) (
+    PARTITION p1 VALUES LESS THAN (10000),
+    PARTITION p2 VALUES LESS THAN (20000),
+    PARTITION p3 VALUES LESS THAN (MAXVALUE) );
+DISTRIBUTE TABLE t4 PARTITION (p1, p2) RULE = "learner-scatter" ENGINE="tiflash";
+```
+
+```
++--------+
+| JOB_ID |
++--------+
+|    103 |
++--------+
+```
+
+## 注意事项
+
+`DISTRIBUTE TABLE` 语句在重新调度表中的 Region 时，可能会受到 PD 热点调度器的影响。调度完成后，随着时间推移，表的 Region 分布可能再次失衡。
+
+## MySQL 兼容性
+
+该语句是 TiDB 对 MySQL 语法的扩展。
+
+## 另请参阅
+
+- [`SHOW DISTRIBUTION JOBS`](/sql-statements/sql-statement-show-distribution-jobs.md)
+- [`SHOW TABLE DISTRIBUTION`](/sql-statements/sql-statement-show-table-distribution.md)
+- [`SHOW TABLE REGIONS`](/sql-statements/sql-statement-show-table-regions.md)
+- [`CANCEL DISTRIBUTION JOBS`] (/sql-statements/sql-statement-cancel-distribution-job.md)

sql-statements/sql-statement-show-distribution-jobs.md

@@ -0,0 +1,43 @@
+---
+title: SHOW DISTRIBUTION JOBS
+summary: 介绍 TiDB 数据库中 SHOW DISTRIBUTION JOBS 的使用概况。
+---
+
+# SHOW DISTRIBUTION JOBS
+
+`SHOW DISTRIBUTION JOBS` 语句用于显示当前所有的 Region 调度任务。
+
+## 语法图
+
+```ebnf+diagram
+ShowDistributionJobsStmt ::=
+    "SHOW" "DISTRIBUTION" "JOBS"
+```
+
+## 示例
+
+显示当前所有的 Region 调度任务：
+
+```sql
+SHOW DISTRIBUTION JOBS;
+```
+
+```
++--------+----------+-------+----------------+--------+----------------+-----------+---------------------+---------------------+---------------------+
+| Job_ID | Database | Table | Partition_List | Engine | Rule           | Status    | Create_Time         | Start_Time          | Finish_Time         |
++--------+----------+-------+----------------+--------+----------------+-----------+---------------------+---------------------+---------------------+
+|    100 | test     | t1    | NULL           | tikv   | leader-scatter | finished  | 2025-04-24 16:09:55 | 2025-04-24 16:09:55 | 2025-04-24 17:09:59 |
+|    101 | test     | t2    | NULL           | tikv   | learner-scatter| cancelled | 2025-05-08 15:33:29 | 2025-05-08 15:33:29 | 2025-05-08 15:33:37 |
+|    102 | test     | t5    | p1,p2          | tikv   | peer-scatter   | cancelled | 2025-05-21 15:32:44 | 2025-05-21 15:32:47 | 2025-05-21 15:32:47 |
++--------+----------+-------+----------------+--------+----------------+-----------+---------------------+---------------------+---------------------+
+```
+
+## MySQL 兼容性
+
+该语句是 TiDB 对 MySQL 语法的扩展。
+
+## 另请参阅
+
+- [`DISTRIBUTE TABLE`](/sql-statements/sql-statement-distribute-table.md)
+- [`SHOW TABLE DISTRIBUTION`](/sql-statements/sql-statement-show-table-distribution.md)
+- [`CANCEL DISTRIBUTION JOB`](/sql-statements/sql-statement-cancel-distribution-job.md)

sql-statements/sql-statement-show-table-distribution.md

@@ -0,0 +1,60 @@
+---
+title: SHOW TABLE DISTRIBUTION
+summary: 介绍 TiDB 数据库中 SHOW TABLE DISTRIBUTION 的使用概况。
+---
+
+# SHOW TABLE DISTRIBUTION
+
+`SHOW TABLE DISTRIBUTION` 语句用于显示指定表的 Region 分布情况。
+
+## 语法图
+
+```ebnf+diagram
+ShowTableDistributionStmt ::=
+    "SHOW" "TABLE" TableName "DISTRIBUTIONS"
+
+TableName ::=
+    (SchemaName ".")? Identifier
+```
+
+## 示例
+
+显示当前表 `t1` 的 Region 分布情况：
+
+```sql
+CREATE TABLE `t` (
+  `a` int DEFAULT NULL,
+  `b` int DEFAULT NULL,
+  KEY `idx` (`b`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin 
+PARTITION BY RANGE (`a`)
+(PARTITION `p1` VALUES LESS THAN (10000),
+ PARTITION `p2` VALUES LESS THAN (MAXVALUE)) |
+SHOW TABLE t1 DISTRIBUTIONS;
+```
+
+```
++----------------+----------+------------+---------------------+-------------------+--------------------+-------------------+--------------------+--------------------------+-------------------------+--------------------------+------------------------+-----------------------+------------------------+
+| PARTITION_NAME | STORE_ID | STORE_TYPE | REGION_LEADER_COUNT | REGION_PEER_COUNT | REGION_WRITE_BYTES | REGION_WRITE_KEYS | REGION_WRITE_QUERY | REGION_LEADER_READ_BYTES | REGION_LEADER_READ_KEYS | REGION_LEADER_READ_QUERY | REGION_PEER_READ_BYTES | REGION_PEER_READ_KEYS | REGION_PEER_READ_QUERY |
++----------------+----------+------------+---------------------+-------------------+--------------------+-------------------+--------------------+--------------------------+-------------------------+--------------------------+------------------------+-----------------------+------------------------+
+| p1             |        1 | tikv       |                   0 |                 0 |                  0 |                 0 |                  0 |                        0 |                       0 |                        0 |                      0 |                     0 |                      0 |
+| p1             |       15 | tikv       |                   0 |                 0 |                  0 |                 0 |                  0 |                        0 |                       0 |                        0 |                      0 |                     0 |                      0 |
+| p1             |        4 | tikv       |                   1 |                 1 |                  0 |                 0 |                  0 |                        0 |                       0 |                        0 |                      0 |                     0 |                      0 |
+| p1             |        5 | tikv       |                   0 |                 1 |                  0 |                 0 |                  0 |                        0 |                       0 |                        0 |                      0 |                     0 |                      0 |
+| p1             |        6 | tikv       |                   0 |                 1 |                  0 |                 0 |                  0 |                        0 |                       0 |                        0 |                      0 |                     0 |                      0 |
+| p2             |        1 | tikv       |                   0 |                 0 |                  0 |                 0 |                  0 |                        0 |                       0 |                        0 |                      0 |                     0 |                      0 |
+| p2             |       15 | tikv       |                   0 |                 0 |                  0 |                 0 |                  0 |                        0 |                       0 |                        0 |                      0 |                     0 |                      0 |
+| p2             |        4 | tikv       |                   0 |                 1 |                  0 |                 0 |                  0 |                        0 |                       0 |                        0 |                      0 |                     0 |                      0 |
+| p2             |        5 | tikv       |                   1 |                 1 |                  0 |                 0 |                  0 |                        0 |                       0 |                        0 |                      0 |                     0 |                      0 |
+| p2             |        6 | tikv       |                   0 |                 1 |                  0 |                 0 |                  0 |                        0 |                       0 |                        0 |                      0 |                     0 |                      0 |
++----------------+----------+------------+---------------------+-------------------+--------------------+-------------------+--------------------+--------------------------+-------------------------+--------------------------+------------------------+-----------------------+------------------------+
+```
+
+## MySQL 兼容性
+
+该语句是 TiDB 对 MySQL 语法的扩展。
+
+## 另请参阅
+
+- [`DISTRIBUTE TABLE`](/sql-statements/sql-statement-distribute-table.md)
+- [`SHOW DISTRIBUTION JOBS`](/sql-statements/sql-statement-show-distribution-jobs.md)