Skip to content

Do not merge until v8.5.4: distribute-table: support to scatter the region distribution of the given table and engine (#19534) #20985

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

Open
wants to merge 3 commits into
base: release-8.5
Choose a base branch
from
+265 −0
Open

Do not merge until v8.5.4: distribute-table: support to scatter the region distribution of the given table and engine (#19534) #20985

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
ba10b7a
distribute-table: support to scatter the region distribution of the g…
bufferflies Sep 8, 2025
5db0582
change the intro version
qiancai Oct 11, 2025
7466975
fix the table name and format
qiancai Oct 11, 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
4 changes: 4 additions & 0 deletions TOC.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -813,6 +813,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 All @@ -830,6 +831,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)
Expand Down Expand Up @@ -894,6 +896,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)
Expand All @@ -916,6 +919,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)
Expand Down
38 changes: 38 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,38 @@
---
title: CANCEL DISTRIBUTION JOB
summary: TiDB 数据库中 CANCEL DISTRIBUTION JOB 的使用情况。
---

# CANCEL DISTRIBUTION JOB <span class="version-mark">从 v8.5.4 开始引入</span>

`CANCEL DISTRIBUTION JOB` 语句用于取消 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 JOBS`](/sql-statements/sql-statement-show-distribution-jobs.md)
120 changes: 120 additions & 0 deletions sql-statements/sql-statement-distribute-table.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,120 @@
---
title: DISTRIBUTE TABLE
summary: 介绍 TiDB 数据库中 DISTRIBUTE TABLE 的使用概况。
---

# DISTRIBUTE TABLE <span class="version-mark">从 v8.5.4 开始引入</span>

> **警告：**
>
> 该功能目前为实验特性，不建议在生产环境中使用。该功能可能会在未事先通知的情况下发生变化或删除。如果发现 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 JOB`](/sql-statements/sql-statement-cancel-distribution-job.md)
43 changes: 43 additions & 0 deletions sql-statements/sql-statement-show-distribution-jobs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
---
title: SHOW DISTRIBUTION JOBS
summary: 介绍 TiDB 数据库中 SHOW DISTRIBUTION JOBS 的使用概况。
---

# SHOW DISTRIBUTION JOBS <span class="version-mark">从 v8.5.4 开始引入</span>

`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)
60 changes: 60 additions & 0 deletions sql-statements/sql-statement-show-table-distribution.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
---
title: SHOW TABLE DISTRIBUTION
summary: 介绍 TiDB 数据库中 SHOW TABLE DISTRIBUTION 的使用概况。
---

# SHOW TABLE DISTRIBUTION <span class="version-mark">从 v8.5.4 开始引入</span>

`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)