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,39 @@
+---
+title: CANCEL DISTRIBUTION
+summary: TiDB 数据库中 CANCEL DISTRIBUTION 的使用情况。
+---
+
+# CANCEL IMPORT
+
+`CANCEL DISTRIBUTION` 语句用于取消 TiDB 中创建的 region 调度任务。
+。
+
+## 语法图
+
+```ebnf+diagram
+CancelImportJobsStmt ::=
+    '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,106 @@
+---
+title: DISTRIBUTE TABLE
+summary: 介绍 TiDB 数据库中 DISTRIBUTE TABLE 的使用概况。
+---
+
+# DISTRIBUTE TABLE
+
+`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）进行均衡打散操作。
+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` 分区在 TiKV 上的 Leader 所在的 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 = `leader-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,45 @@
+---
+title: SHOW TABLE DISTRIBUTION
+summary: 介绍 TiDB 数据库中 SHOW TABLE DISTRIBUTION 的使用概况。
+---
+
+# SHOW TABLE DISTRIBUTION
+
+`SHOW TABLE DISTRIBUTION` 语句用于显示指定表的 Region 分布情况。
+
+## 语法图
+
+```ebnf+diagram
+ShowTableDistributionStmt ::=
+    "SHOW" "TABLE" "DISTRIBUTION" TableName
+
+TableName ::=
+    (SchemaName ".")? Identifier
+```
+
+## 示例
+
+显示当前表 `t1` 的 Region 分布情况：
+
+```sql
+SHOW TABLE DISTRIBUTION t1;
+```
+
+```
++--------+----------+-------+----------------+--------+----------------+-----------+---------------------+---------------------+---------------------+
+| 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 DISTRIBUTION JOBS`](/sql-statements/sql-statement-show-distribution-jobs.md)