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

TOC.md

@@ -788,6 +788,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 +853,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 +876,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-distribute-table.md

@@ -0,0 +1,124 @@
+---
+title: DISTRIBUTE TABLE
+summary: 介绍 TiDB 数据库中 DISTRIBUTE TABLE 的使用概况。
+---
+
+# DISTRIBUTE TABLE
+
+`DISTRIBUTE TABLE` 语句用于对指定表的 Region 进行重新打散和调度，以实现表级别的均衡分布。执行该语句可以防止个别 Region 集中在少数 TiFlash 或 TiKV 节点上，从而解决表中 Region 分布不均衡的问题。
+
+## 语法图
+
+```ebnf+diagram
+DistributeTableStmt ::=
+    "DISTRIBUTE"  "TABLE" TableName PartitionNameList?  EngineOption? RoleOption?
+
+TableName ::=
+    (SchemaName ".")? Identifier
+
+PartitionNameList ::=
+    "PARTITION" "(" PartitionName ("," PartitionName)* ")"
+
+EngineOption ::=
+    "ENGINE" Expression
+
+RoleOption ::=
+    "Role" Expression
+```
+
+## 示例
+
+通过 `DISTRIBUTE TABLE` 语句重新调度表中的 Region 时，你可以根据需求指定存储引擎（如 TiFlash 或 TiKV）以及不同的 Raft 角色（如 Leader、Learner、Voter）进行均衡打散操作。
+
+对表 `t1` 在 TiKV 上的 Leader 所在的 Region 重新进行均衡调度：
+
+```sql
+CREATE TABLE t1 (a INT);
+...
+DISTRIBUTE TABLE t1 engine tikv role leader
+```
+
+```
++---------+
+| JOB_ID  |
+100
++---------+
+```
+
+对表 `t2` 在 TiFlash 上的 Learner 所在的 Region 重新进行均衡调度：
+
+```sql
+CREATE TABLE t2 (a INT);
+...
+DISTRIBUTE TABLE t2 ENGINE tiflash role learner;
+```
+
+```
++---------+
+| JOB_ID  |
+101
++---------+
+```
+
+对分区表 `t3` 的 `p1` 和 `p2` 分区在 TiKV 上的 Leader 所在的 Region 重新进行均衡调度：
+
+```sql
+CREATE TABLE t3 (a INT);
+...
+DISTRIBUTE TABLE t3 PARTITION (p1, p2) ENGINE tikv role leader;
+```
+
+```
++---------+
+| JOB_ID  |
+102
++---------+
+```
+
+执行 [`SHOW DISTRIBUTION JOBS`](/sql-statements/sql-statement-show-distribution-jobs.md) 语句查看当前所有的调度任务：
+
+```sql
+SHOW DISTRIBUTION JOBS;
+```
+
+```
++---------+------------+------------+-----------------+------------+-----------+----------+-------------+---------------+
+| JOB_ID  |  DB_NAME   | TABLE_NAME | PARTITION_NAMES | ENGINE_TYPE | ROLE_TYPE | STATUS  | CREATE_USER | CREATE_TIME   |
++---------+------------+------------+-----------------+------------+-----------+--------+---------------+---------------+
+|    1    |   db_1     |    t1      |                 | TIKV       | LEADER    | RUNNING  | ADMIN       | 20240712      |
+|    2    |   db_1     |    t2      |                 | TIFLASH    | LEARNER   | FINISHED | ADMIN       | 20240715      |
+|    3    |   db_1     |    t3      |                 | TiKV       | VOTER     | STOPPED  | ADMIN       | 20240713      |
+|    4    |   db_1     |    t4      |                 | TIFLASH    | LEARNER   | FINISHED | ADMIN       | 20240713      |
++---------+------------+------------+-----------------+------------+-----------+----------+-------------+---------------+
+```
+
+执行 [`SHOW TABLE DISTRIBUTION`](/sql-statements/sql-statement-show-table-distribution.md) 语句查看表 `t1` 的 Region 分布情况：
+
+```sql
+SHOW TABLE DISTRIBUTION t1;
+```
+
+```
++---------+------------+----------------+----------+------------+-------------------+--------------------+-----------------+------------------+
+| DB_NAME | TABLE_NAME | PARTITION_NAME | STORE_ID | STORE_TYPE | REGION_LEADER_NUM | REGION_LEADER_BYTE | REGION_PEER_NUM | REGION_PEER_BYTE |
++---------+------------+----------------+----------+------------+-------------------+--------------------+-----------------+------------------+
+| db_1    |     t1     |                | 1        | TiKV       |               315 |        24057934521 |            1087 |      86938746542 |
+| db_1    |     t1     |                | 2        | TiKV       |               324 |        28204839240 |            1104 |      91039476832 |
+| db_1    |     t1     |                | 3        | TiKV       |               319 |        25986274812 |            1091 |      89405367423 |
+| db_1    |     t1     |                | 4        | TiKV       |               503 |        41039587625 |            1101 |      90482317797 |
++---------+------------+----------------+----------+------------+-------------------+--------------------+-----------------+------------------+
+```
+
+## 注意事项
+
+`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)

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  |  DB_NAME   | TABLE_NAME | PARTITION_NAMES | ENGINE_TYPE | ROLE_TYPE | STATUS  | CREATE_USER | CREATE_TIME   |
++---------+------------+------------+-----------------+------------+-----------+--------+---------------+---------------+
+|    1    |   db_1     |    t1      |                 | TIKV       | LEADER    | RUNNING  | ADMIN       | 20240712      |
+|    2    |   db_1     |    t2      |                 | TIFLASH    | LEARNER   | FINISHED | ADMIN       | 20240715      |
+|    3    |   db_1     |    t3      |                 | TiKV       | VOTER     | STOPPED  | ADMIN       | 20240713      |
+|    4    |   db_1     |    t4      |                 | TIFLASH    | LEARNER   | FINISHED | ADMIN       | 20240713      |
++---------+------------+------------+-----------------+------------+-----------+----------+-------------+---------------+
+```
+
+## MySQL 兼容性
+
+该语句是 TiDB 对 MySQL 语法的扩展。
+
+## 另请参阅
+
+- [`DISTRIBUTE TABLE`](/sql-statements/sql-statement-distribute-table.md)
+- [`SHOW TABLE DISTRIBUTION`](/sql-statements/sql-statement-show-table-distribution.md)

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

@@ -0,0 +1,46 @@
+---
+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;
+```
+
+```
++---------+------------+----------------+----------+------------+-------------------+--------------------+-----------------+------------------+
+| DB_NAME | TABLE_NAME | PARTITION_NAME | STORE_ID | STORE_TYPE | REGION_LEADER_NUM | REGION_LEADER_BYTE | REGION_PEER_NUM | REGION_PEER_BYTE |
++---------+------------+----------------+----------+------------+-------------------+--------------------+-----------------+------------------+
+| db_1    |     t1     |                | 1        | TiKV       |               315 |        24057934521 |            1087 |      86938746542 |
+| db_1    |     t1     |                | 2        | TiKV       |               324 |        28204839240 |            1104 |      91039476832 |
+| db_1    |     t1     |                | 3        | TiKV       |               319 |        25986274812 |            1091 |      89405367423 |
+| db_1    |     t1     |                | 4        | TiKV       |               503 |        41039587625 |            1101 |      90482317797 |
++---------+------------+----------------+----------+------------+-------------------+--------------------+-----------------+------------------+
+```
+
+## MySQL 兼容性
+
+该语句是 TiDB 对 MySQL 语法的扩展。
+
+## 另请参阅
+
+- [`DISTRIBUTE TABLE`](/sql-statements/sql-statement-distribute-table.md)
+- [`SHOW DISTRIBUTION JOBS`](/sql-statements/sql-statement-show-distribution-jobs.md)