Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 32 commits into from
Sep 8, 2025
Merged

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

Show file tree
Hide file tree
Changes from 21 commits
Commits
Show all changes
32 commits
Select commit Hold shift + click to select a range
ca62ac6
add distribute table fd
bufferflies Jan 13, 2025
a4fc306
address comment
bufferflies Feb 6, 2025
c0b9415
address comment
bufferflies Feb 13, 2025
e80d334
add toc changes and anther two sql docs
qiancai Feb 20, 2025
1bdc893
Apply suggestions from code review
qiancai Feb 20, 2025
2bfb0e1
update the file naming style to use hyphen
qiancai Feb 21, 2025
acd05fa
Apply suggestions from code review
qiancai Mar 17, 2025
92d3a9c
add cancel job sql
bufferflies May 21, 2025
c7611d9
conflict
bufferflies May 21, 2025
20a6312
split
bufferflies May 21, 2025
a4ccf2c
address comment
bufferflies May 29, 2025
1e9b393
cancel distribution job
bufferflies May 30, 2025
51c781b
toc add cancel distribution job link
bufferflies Jun 4, 2025
8f08f70
add a section for parameter descriptions
qiancai Jun 9, 2025
418934e
Update sql-statements/sql-statement-cancel-distribution-job.md
qiancai Jun 19, 2025
17547f5
scatter
bufferflies Jun 19, 2025
e2f16f4
optimize parser
bufferflies Jun 20, 2025
3ce5099
add " " to wrap argument values
qiancai Jun 23, 2025
4e1386f
minor format updates
qiancai Jun 23, 2025
0ae5d5c
----
bufferflies Jun 25, 2025
0881fba
Merge branch 'distribute_table' of github.com:bufferflies/docs-cn int…
bufferflies Jun 25, 2025
f0545be
address comment
bufferflies Jun 27, 2025
7140d09
minor format updates
qiancai Jun 27, 2025
1bfac73
show distribution
bufferflies Jun 30, 2025
4bffb4e
Merge branch 'distribute_table' of github.com:bufferflies/docs-cn int…
bufferflies Jun 30, 2025
745d235
remove an empty line
qiancai Jun 30, 2025
4bcab8e
remove an empty line
qiancai Jun 30, 2025
5673ec1
add four comments about the support info
qiancai Jul 21, 2025
f5e6ffa
Apply suggestions from code review
qiancai Jul 24, 2025
9bae0eb
use <span> to wrap the version support info
qiancai Aug 12, 2025
97fc420
Merge branch 'distribute_table' of https://github.com/bufferflies/doc…
qiancai Aug 12, 2025
a27f6cd
show the version span in the doc title
qiancai Aug 20, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions TOC.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
40 changes: 40 additions & 0 deletions sql-statements/sql-statement-cancel-distribution-job.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
---
title: CANCEL DISTRIBUTION
summary: TiDB 数据库中 CANCEL DISTRIBUTION 的使用情况。
---

# CANCEL DISTRIBUTION

<!-- New in v9.0.0 -->

`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)
104 changes: 51 additions & 53 deletions sql-statements/sql-statement-distribute-table.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,108 +5,105 @@ summary: 介绍 TiDB 数据库中 DISTRIBUTE TABLE 的使用概况。

# DISTRIBUTE TABLE

<!-- New in v9.0.0 -->

> **警告：**
>
> 该功能目前为实验特性，不建议在生产环境中使用。该功能可能会在未事先通知的情况下发生变化或删除。如果发现 bug，请在 GitHub 上提 [issue](https://github.com/pingcap/tidb/issues) 反馈。

`DISTRIBUTE TABLE` 语句用于对指定表的 Region 进行重新打散和调度，以实现表级别的均衡分布。执行该语句可以防止个别 Region 集中在少数 TiFlash 或 TiKV 节点上，从而解决表中 Region 分布不均衡的问题。

## 语法图

```ebnf+diagram
DistributeTableStmt ::=
"DISTRIBUTE" "TABLE" TableName PartitionNameList? EngineOption? RoleOption?
"DISTRIBUTE" "TABLE" TableName PartitionNameListOpt "RULE" EqOrAssignmentEq Identifier "ENGINE" EqOrAssignmentEq Identifier "TIMEOUT" EqOrAssignmentEq Identifier

TableName ::=
(SchemaName ".")? Identifier

PartitionNameList ::=
"PARTITION" "(" PartitionName ("," PartitionName)* ")"
```

EngineOption ::=
"ENGINE" Expression
## 参数说明

RoleOption ::=
"Role" Expression
```
通过 `DISTRIBUTE TABLE` 语句重新调度表中的 Region 时，你可以根据需求指定存储引擎（如 TiFlash 或 TiKV）以及不同的 Raft 角色（如 Leader、Learner、Voter）进行均衡。

- `RULE`：指定针对哪个 Raft 角色所在的 Region 进行均衡调度，可选值为 `"leader-scatter"`、`"peer-scatter"` 和 `"learner-scatter"`。
- `ENGINE`：指定存储引擎，可选值为 `"tikv"` 和 `"tiflash"`。
- `TIMEOUT`：指定打散操作的超时限制。 如果 PD 未在该时间内进行打散，打散任务将会自动退出。当未指定该参数时，默认值为 `"30m"`。

## 示例

通过 `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
DISTRIBUTE TABLE t1 RULE= "leader-scatter" ENGINE = "tikv" TIMEOUT="1h"
```

```
+---------+
| JOB_ID |
100
+---------+
+--------+
| JOB_ID |
+--------+
| 100 |
+--------+
```

对表 `t2` 在 TiFlash 上的 Learner 所在的 Region 重新进行均衡调度：

```sql
CREATE TABLE t2 (a INT);
...
DISTRIBUTE TABLE t2 ENGINE tiflash role learner;
DISTRIBUTE TABLE t2 RULE = "learner-scatter" ENGINE = "tiflash";
```

```
+---------+
| JOB_ID |
101
+---------+
+--------+
| JOB_ID |
+--------+
| 101 |
+--------+
```

对分区表 `t3` 的 `p1` 和 `p2` 分区在 TiKV 上的 Leader 所在的 Region 重新进行均衡调度：
对分区表 `t3` 的 `p1` 和 `p2` 分区在 TiKV 上的 Peer 所在的 Region 重新进行均衡调度：

```sql
CREATE TABLE t3 (a INT);
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) ENGINE tikv role leader;
```

```
+---------+
| JOB_ID |
102
+---------+
```

执行 [`SHOW DISTRIBUTION JOBS`](/sql-statements/sql-statement-show-distribution-jobs.md) 语句查看当前所有的调度任务：

```sql
SHOW DISTRIBUTION JOBS;
DISTRIBUTE TABLE t3 PARTITION (p1, p2) RULE = "peer-scatter" ENGINE = "tikv";
```

```
+---------+------------+------------+-----------------+------------+-----------+----------+-------------+---------------+
| 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 |
+---------+------------+------------+-----------------+------------+-----------+----------+-------------+---------------+
+--------+
| JOB_ID |
+--------+
| 102 |
+--------+
```

执行 [`SHOW TABLE DISTRIBUTION`](/sql-statements/sql-statement-show-table-distribution.md) 语句查看表 `t1` 的 Region 分布情况：
对分区表 `t4` 的 `p1` 和 `p2` 分区在 TiFlash 上的 Learner 所在的 Region 重新进行均衡调度：

```sql
SHOW TABLE DISTRIBUTION t1;
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";
```

```
+---------+------------+----------------+----------+------------+-------------------+--------------------+-----------------+------------------+
| 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 |
+---------+------------+----------------+----------+------------+-------------------+--------------------+-----------------+------------------+
+--------+
| JOB_ID |
+--------+
| 103 |
+--------+
```

## 注意事项
Expand All @@ -121,4 +118,5 @@ SHOW TABLE DISTRIBUTION t1;

- [`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)
- [`SHOW TABLE REGIONS`](/sql-statements/sql-statement-show-table-regions.md)
- [`CANCEL DISTRIBUTION JOBS`] (/sql-statements/sql-statement-cancel-distribution-job.md)
20 changes: 11 additions & 9 deletions sql-statements/sql-statement-show-distribution-jobs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,8 @@ summary: 介绍 TiDB 数据库中 SHOW DISTRIBUTION JOBS 的使用概况。

# SHOW DISTRIBUTION JOBS

<!-- New in v9.0.0 -->

`SHOW DISTRIBUTION JOBS` 语句用于显示当前所有的 Region 调度任务。

## 语法图
Expand All @@ -23,14 +25,13 @@ 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 |
+---------+------------+------------+-----------------+------------+-----------+----------+-------------+---------------+
+--------+----------+-------+----------------+--------+----------------+-----------+---------------------+---------------------+---------------------+
| 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 兼容性
Expand All @@ -40,4 +41,5 @@ SHOW DISTRIBUTION JOBS;
## 另请参阅

- [`DISTRIBUTE TABLE`](/sql-statements/sql-statement-distribute-table.md)
- [`SHOW TABLE DISTRIBUTION`](/sql-statements/sql-statement-show-table-distribution.md)
- [`SHOW TABLE DISTRIBUTION`](/sql-statements/sql-statement-show-table-distribution.md)
- [`CANCEL DISTRIBUTION JOB`](/sql-statements/sql-statement-cancel-distribution-job.md)
36 changes: 26 additions & 10 deletions sql-statements/sql-statement-show-table-distribution.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,13 +5,15 @@ summary: 介绍 TiDB 数据库中 SHOW TABLE DISTRIBUTION 的使用概况。

# SHOW TABLE DISTRIBUTION

<!-- New in v9.0.0 -->

`SHOW TABLE DISTRIBUTION` 语句用于显示指定表的 Region 分布情况。

## 语法图

```ebnf+diagram
ShowTableDistributionStmt ::=
"SHOW" "TABLE" "DISTRIBUTION" TableName
"SHOW" "TABLE" TableName "DISTRIBUTIONS"

TableName ::=
(SchemaName ".")? Identifier
Expand All @@ -22,18 +24,32 @@ TableName ::=
显示当前表 `t1` 的 Region 分布情况：

```sql
SHOW TABLE DISTRIBUTION t1;
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;
```

```
+---------+------------+----------------+----------+------------+-------------------+--------------------+-----------------+------------------+
| 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 |
+---------+------------+----------------+----------+------------+-------------------+--------------------+-----------------+------------------+
+----------------+----------+------------+---------------------+-------------------+--------------------+-------------------+--------------------+--------------------------+-------------------------+--------------------------+------------------------+-----------------------+------------------------+
| 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 兼容性
Expand Down
Loading