Skip to content

Commit 988f395

Browse files
bufferfliesbufferflies
authored
distribute-table: support to scatter the region distribution of the given table and engine (#19534)
1 parent 8b299a3 commit 988f395

5 files changed

+265
-0
lines changed

‎TOC.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -813,6 +813,7 @@
813813
- [`BATCH`](/sql-statements/sql-statement-batch.md)
814814
- [`BEGIN`](/sql-statements/sql-statement-begin.md)
815815
- [`CALIBRATE RESOURCE`](/sql-statements/sql-statement-calibrate-resource.md)
816+
- [`CANCEL DISTRIBUTION JOB`](/sql-statements/sql-statement-cancel-distribution-job.md)
816817
- [`CANCEL IMPORT JOB`](/sql-statements/sql-statement-cancel-import-job.md)
817818
- [`CANCEL TRAFFIC JOBS`](/sql-statements/sql-statement-cancel-traffic-jobs.md)
818819
- [`COMMIT`](/sql-statements/sql-statement-commit.md)
@@ -831,6 +832,7 @@
831832
- [`DELETE`](/sql-statements/sql-statement-delete.md)
832833
- [`DESC`](/sql-statements/sql-statement-desc.md)
833834
- [`DESCRIBE`](/sql-statements/sql-statement-describe.md)
835+
- [`DISTRIBUTE TABLE`](/sql-statements/sql-statement-distribute-table.md)
834836
- [`DO`](/sql-statements/sql-statement-do.md)
835837
- [`DROP BINDING`](/sql-statements/sql-statement-drop-binding.md)
836838
- [`DROP DATABASE`](/sql-statements/sql-statement-drop-database.md)
@@ -895,6 +897,7 @@
895897
- [`SHOW CREATE DATABASE`](/sql-statements/sql-statement-show-create-database.md)
896898
- [`SHOW CREATE USER`](/sql-statements/sql-statement-show-create-user.md)
897899
- [`SHOW DATABASES`](/sql-statements/sql-statement-show-databases.md)
900+
- [`SHOW DISTRIBUTION JOBS`](/sql-statements/sql-statement-show-distribution-jobs.md)
898901
- [`SHOW ENGINES`](/sql-statements/sql-statement-show-engines.md)
899902
- [`SHOW ERRORS`](/sql-statements/sql-statement-show-errors.md)
900903
- [`SHOW FIELDS FROM`](/sql-statements/sql-statement-show-fields-from.md)
@@ -917,6 +920,7 @@
917920
- [`SHOW STATS_META`](/sql-statements/sql-statement-show-stats-meta.md)
918921
- [`SHOW STATS_TOPN`](/sql-statements/sql-statement-show-stats-topn.md)
919922
- [`SHOW STATUS`](/sql-statements/sql-statement-show-status.md)
923+
- [`SHOW TABLE DISTRIBUTION`](/sql-statements/sql-statement-show-table-distribution.md)
920924
- [`SHOW TABLE NEXT_ROW_ID`](/sql-statements/sql-statement-show-table-next-rowid.md)
921925
- [`SHOW TABLE REGIONS`](/sql-statements/sql-statement-show-table-regions.md)
922926
- [`SHOW TABLE STATUS`](/sql-statements/sql-statement-show-table-status.md)

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

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
---
2+
title: CANCEL DISTRIBUTION JOB
3+
summary: TiDB 数据库中 CANCEL DISTRIBUTION JOB 的使用情况。
4+
---
5+
6+
# CANCEL DISTRIBUTION JOB <span class="version-mark">从 v9.0.0 开始引入</span>
7+
8+
`CANCEL DISTRIBUTION JOB` 语句用于取消 TiDB 中通过 [`DISTRIBUTE TABLE`](/sql-statements/sql-statement-distribute-table.md) 语句创建的 Region 调度任务。
9+
10+
## 语法图
11+
12+
```ebnf+diagram
13+
CancelDistributionJobsStmt ::=
14+
'CANCEL' 'DISTRIBUTION' 'JOB' JobID
15+
```
16+
17+
## 示例
18+
19+
下面示例取消 ID 为 1 的导入任务：
20+
21+
```sql
22+
CANCEL DISTRIBUTION JOB 1;
23+
```
24+
25+
输出结果如下：
26+
27+
```
28+
Query OK, 0 rows affected (0.01 sec)
29+
```
30+
31+
## MySQL 兼容性
32+
33+
该语句是 TiDB 对 MySQL 语法的扩展。
34+
35+
## 另请参阅
36+
37+
* [`DISTRIBUTE TABLE`](/sql-statements/sql-statement-distribute-table.md)
38+
* [`SHOW DISTRIBUTION JOBS`](/sql-statements/sql-statement-show-distribution-jobs.md)

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

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
---
2+
title: DISTRIBUTE TABLE
3+
summary: 介绍 TiDB 数据库中 DISTRIBUTE TABLE 的使用概况。
4+
---
5+
6+
# DISTRIBUTE TABLE <span class="version-mark">从 v9.0.0 开始引入</span>
7+
8+
> **警告：**
9+
>
10+
> 该功能目前为实验特性，不建议在生产环境中使用。该功能可能会在未事先通知的情况下发生变化或删除。如果发现 bug，请在 GitHub 上提 [issue](https://github.com/pingcap/tidb/issues) 反馈。
11+
12+
`DISTRIBUTE TABLE` 语句用于对指定表的 Region 进行重新打散和调度，以实现表级别的均衡分布。执行该语句可以防止个别 Region 集中在少数 TiFlash 或 TiKV 节点上，从而解决表中 Region 分布不均衡的问题。
13+
14+
## 语法图
15+
16+
```ebnf+diagram
17+
DistributeTableStmt ::=
18+
"DISTRIBUTE" "TABLE" TableName PartitionNameListOpt "RULE" EqOrAssignmentEq Identifier "ENGINE" EqOrAssignmentEq Identifier "TIMEOUT" EqOrAssignmentEq Identifier
19+
20+
TableName ::=
21+
(SchemaName ".")? Identifier
22+
23+
PartitionNameList ::=
24+
"PARTITION" "(" PartitionName ("," PartitionName)* ")"
25+
```
26+
27+
## 参数说明
28+
29+
通过 `DISTRIBUTE TABLE` 语句重新调度表中的 Region 时，你可以根据需求指定存储引擎（如 TiFlash 或 TiKV）以及不同的 Raft 角色（如 Leader、Learner、Voter）进行均衡。
30+
31+
- `RULE`：指定针对哪个 Raft 角色所在的 Region 进行均衡调度，可选值为 `"leader-scatter"`、`"peer-scatter"` 和 `"learner-scatter"`。
32+
- `ENGINE`：指定存储引擎，可选值为 `"tikv"` 和 `"tiflash"`。
33+
- `TIMEOUT`：指定打散操作的超时限制。如果 PD 未在该时间内进行打散，打散任务将会自动退出。当未指定该参数时，默认值为 `"30m"`。
34+
35+
## 示例
36+
37+
对表 `t1` 在 TiKV 上的 Leader 所在的 Region 重新进行均衡调度：
38+
39+
```sql
40+
CREATE TABLE t1 (a INT);
41+
...
42+
DISTRIBUTE TABLE t1 RULE = "leader-scatter" ENGINE = "tikv" TIMEOUT = "1h";
43+
```
44+
45+
```
46+
+--------+
47+
| JOB_ID |
48+
+--------+
49+
| 100 |
50+
+--------+
51+
```
52+
53+
对表 `t2` 在 TiFlash 上的 Learner 所在的 Region 重新进行均衡调度：
54+
55+
```sql
56+
CREATE TABLE t2 (a INT);
57+
...
58+
DISTRIBUTE TABLE t2 RULE = "learner-scatter" ENGINE = "tiflash";
59+
```
60+
61+
```
62+
+--------+
63+
| JOB_ID |
64+
+--------+
65+
| 101 |
66+
+--------+
67+
```
68+
69+
对分区表 `t3` 的 `p1` 和 `p2` 分区在 TiKV 上的 Peer 所在的 Region 重新进行均衡调度：
70+
71+
```sql
72+
CREATE TABLE t3 ( a INT, b INT, INDEX idx(b)) PARTITION BY RANGE( a ) (
73+
PARTITION p1 VALUES LESS THAN (10000),
74+
PARTITION p2 VALUES LESS THAN (20000),
75+
PARTITION p3 VALUES LESS THAN (MAXVALUE) );
76+
...
77+
DISTRIBUTE TABLE t3 PARTITION (p1, p2) RULE = "peer-scatter" ENGINE = "tikv";
78+
```
79+
80+
```
81+
+--------+
82+
| JOB_ID |
83+
+--------+
84+
| 102 |
85+
+--------+
86+
```
87+
88+
对分区表 `t4` 的 `p1` 和 `p2` 分区在 TiFlash 上的 Learner 所在的 Region 重新进行均衡调度：
89+
90+
```sql
91+
CREATE TABLE t4 ( a INT, b INT, INDEX idx(b)) PARTITION BY RANGE( a ) (
92+
PARTITION p1 VALUES LESS THAN (10000),
93+
PARTITION p2 VALUES LESS THAN (20000),
94+
PARTITION p3 VALUES LESS THAN (MAXVALUE) );
95+
...
96+
DISTRIBUTE TABLE t4 PARTITION (p1, p2) RULE = "learner-scatter" ENGINE="tiflash";
97+
```
98+
99+
```
100+
+--------+
101+
| JOB_ID |
102+
+--------+
103+
| 103 |
104+
+--------+
105+
```
106+
107+
## 注意事项
108+
109+
`DISTRIBUTE TABLE` 语句在重新调度表中的 Region 时，可能会受到 PD 热点调度器的影响。调度完成后，随着时间推移，表的 Region 分布可能再次失衡。
110+
111+
## MySQL 兼容性
112+
113+
该语句是 TiDB 对 MySQL 语法的扩展。
114+
115+
## 另请参阅
116+
117+
- [`SHOW DISTRIBUTION JOBS`](/sql-statements/sql-statement-show-distribution-jobs.md)
118+
- [`SHOW TABLE DISTRIBUTION`](/sql-statements/sql-statement-show-table-distribution.md)
119+
- [`SHOW TABLE REGIONS`](/sql-statements/sql-statement-show-table-regions.md)
120+
- [`CANCEL DISTRIBUTION JOB`](/sql-statements/sql-statement-cancel-distribution-job.md)

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

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
---
2+
title: SHOW DISTRIBUTION JOBS
3+
summary: 介绍 TiDB 数据库中 SHOW DISTRIBUTION JOBS 的使用概况。
4+
---
5+
6+
# SHOW DISTRIBUTION JOBS <span class="version-mark">从 v9.0.0 开始引入</span>
7+
8+
`SHOW DISTRIBUTION JOBS` 语句用于显示当前所有的 Region 调度任务。
9+
10+
## 语法图
11+
12+
```ebnf+diagram
13+
ShowDistributionJobsStmt ::=
14+
"SHOW" "DISTRIBUTION" "JOBS"
15+
```
16+
17+
## 示例
18+
19+
显示当前所有的 Region 调度任务：
20+
21+
```sql
22+
SHOW DISTRIBUTION JOBS;
23+
```
24+
25+
```
26+
+--------+----------+-------+----------------+--------+----------------+-----------+---------------------+---------------------+---------------------+
27+
| Job_ID | Database | Table | Partition_List | Engine | Rule | Status | Create_Time | Start_Time | Finish_Time |
28+
+--------+----------+-------+----------------+--------+----------------+-----------+---------------------+---------------------+---------------------+
29+
| 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 |
30+
| 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 |
31+
| 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 |
32+
+--------+----------+-------+----------------+--------+----------------+-----------+---------------------+---------------------+---------------------+
33+
```
34+
35+
## MySQL 兼容性
36+
37+
该语句是 TiDB 对 MySQL 语法的扩展。
38+
39+
## 另请参阅
40+
41+
- [`DISTRIBUTE TABLE`](/sql-statements/sql-statement-distribute-table.md)
42+
- [`SHOW TABLE DISTRIBUTION`](/sql-statements/sql-statement-show-table-distribution.md)
43+
- [`CANCEL DISTRIBUTION JOB`](/sql-statements/sql-statement-cancel-distribution-job.md)

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

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
---
2+
title: SHOW TABLE DISTRIBUTION
3+
summary: 介绍 TiDB 数据库中 SHOW TABLE DISTRIBUTION 的使用概况。
4+
---
5+
6+
# SHOW TABLE DISTRIBUTION <span class="version-mark">从 v9.0.0 开始引入</span>
7+
8+
`SHOW TABLE DISTRIBUTION` 语句用于显示指定表的 Region 分布情况。
9+
10+
## 语法图
11+
12+
```ebnf+diagram
13+
ShowTableDistributionStmt ::=
14+
"SHOW" "TABLE" TableName "DISTRIBUTIONS"
15+
16+
TableName ::=
17+
(SchemaName ".")? Identifier
18+
```
19+
20+
## 示例
21+
22+
显示当前表 `t1` 的 Region 分布情况：
23+
24+
```sql
25+
CREATE TABLE `t` (
26+
`a` int DEFAULT NULL,
27+
`b` int DEFAULT NULL,
28+
KEY `idx` (`b`)
29+
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin
30+
PARTITION BY RANGE (`a`)
31+
(PARTITION `p1` VALUES LESS THAN (10000),
32+
PARTITION `p2` VALUES LESS THAN (MAXVALUE)) |
33+
SHOW TABLE t1 DISTRIBUTIONS;
34+
```
35+
36+
```
37+
+----------------+----------+------------+---------------------+-------------------+--------------------+-------------------+--------------------+--------------------------+-------------------------+--------------------------+------------------------+-----------------------+------------------------+
38+
| 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 |
39+
+----------------+----------+------------+---------------------+-------------------+--------------------+-------------------+--------------------+--------------------------+-------------------------+--------------------------+------------------------+-----------------------+------------------------+
40+
| p1 | 1 | tikv | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
41+
| p1 | 15 | tikv | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
42+
| p1 | 4 | tikv | 1 | 1 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
43+
| p1 | 5 | tikv | 0 | 1 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
44+
| p1 | 6 | tikv | 0 | 1 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
45+
| p2 | 1 | tikv | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
46+
| p2 | 15 | tikv | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
47+
| p2 | 4 | tikv | 0 | 1 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
48+
| p2 | 5 | tikv | 1 | 1 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
49+
| p2 | 6 | tikv | 0 | 1 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
50+
+----------------+----------+------------+---------------------+-------------------+--------------------+-------------------+--------------------+--------------------------+-------------------------+--------------------------+------------------------+-----------------------+------------------------+
51+
```
52+
53+
## MySQL 兼容性
54+
55+
该语句是 TiDB 对 MySQL 语法的扩展。
56+
57+
## 另请参阅
58+
59+
- [`DISTRIBUTE TABLE`](/sql-statements/sql-statement-distribute-table.md)
60+
- [`SHOW DISTRIBUTION JOBS`](/sql-statements/sql-statement-show-distribution-jobs.md)

0 commit comments

Comments
 (0)