Skip to content

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

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 6 commits into
base: master
Choose a base branch
from
+267 −0
Open

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
5c3d484
Add temp.md
qiancai Feb 21, 2025
bbcbf92
Delete temp.md
qiancai Feb 21, 2025
daac87b
add translation
qiancai Feb 21, 2025
cd201ed
minor case updates
qiancai Feb 21, 2025
b2b20a6
sync changes from the zh PR
qiancai Jun 23, 2025
fe45c76
sync latest changes from the zh PR
qiancai Jun 30, 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 @@ -772,6 +772,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 @@ -789,6 +790,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 @@ -853,6 +855,7 @@
- [`SHOW CREATE TABLE`](/sql-statements/sql-statement-show-create-table.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 @@ -875,6 +878,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: An overview of the usage of CANCEL DISTRIBUTION JOB in TiDB.
---

# CANCEL DISTRIBUTION JOB

The `CANCEL DISTRIBUTION JOB` statement is used to cancel a Region scheduling task created using the [`DISTRIBUTE TABLE`](/sql-statements/sql-statement-distribute-table.md) statement in TiDB.

## Syntax diagram

```ebnf+diagram
CancelDistributionJobsStmt ::=
'CANCEL' 'DISTRIBUTION' 'JOB' JobID
```

## Examples

The following example cancels the distribution job with ID `1`:

```sql
CANCEL DISTRIBUTION JOB 1;
```

The output is as follows:

```
Query OK, 0 rows affected (0.01 sec)
```

## MySQL compatibility

This statement is a TiDB extension to MySQL syntax.

## See also

* [`DISTRIBUTE TABLE`](/sql-statements/sql-statement-distribute-table.md)
* [`SHOW DISTRIBUTION JOBS`](/sql-statements/sql-statement-show-distribution-jobs.md)
121 changes: 121 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,121 @@
---
title: DISTRIBUTE TABLE
summary: An overview of the usage of DISTRIBUTE TABLE for the TiDB database.
---

# DISTRIBUTE TABLE

> **Warning:**
>
> - This feature is experimental. It is not recommended that you use it in the production environment. This feature might be changed or removed without prior notice. If you find a bug, you can report an [issue](https://github.com/pingcap/tidb/issues) on GitHub.
> - This feature is not available on [TiDB Cloud Serverless](https://docs.pingcap.com/tidbcloud/select-cluster-tier#tidb-cloud-serverless) clusters.

The `DISTRIBUTE TABLE` statement redistributes and reschedules Regions of a specified table to achieve a balanced distribution at the table level. Executing this statement helps prevent Regions from being concentrated on a few TiFlash or TiKV nodes, addressing the issue of uneven region distribution in the table.

## Syntax

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

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

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

## Parameter description

When redistributing Regions in a table using the `DISTRIBUTE TABLE` statement, you can specify the storage engine (such as TiFlash or TiKV) and different Raft roles (such as Leader, Learner, or Voter) for balanced distribution.

- `RULE`: specifies which Raft role's Region to balance and schedule. Optional values are `"leader-scatter"`, `"peer-scatter"`, and `"learner-scatter"`.
- `ENGINE`: specifies the storage engine. Optional values are `"tikv"` and `"tiflash"`.
- `TIMEOUT`: specifies the timeout limit for the scatter operation. If PD does not complete the scatter within this time, the scatter task will automatically exit. When this parameter is not specified, the default value is `"30m"`.

## Examples

Redistribute the Regions of the Leaders in the table `t1` on TiKV:

```sql
CREATE TABLE t1 (a INT);
...
DISTRIBUTE TABLE t1 RULE="leader-scatter" ENGINE="tikv" TIMEOUT="1h";
```

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

Redistribute the Regions of the Learners in the table `t2` on TiFlash:

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

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

Redistribute the Regions of the Peers in the table `t3`'s `p1` and `p2` partitions on TiKV:

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

Redistribute the Regions of the Learner in the table `t4`'s `p1` and `p2` partitions on TiFlash:

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

## Notes

When you execute the `DISTRIBUTE TABLE` statement to redistribute Regions of a table, the Region distribution result might be affected by the PD hotspot scheduler. After the redistribution, the Region distribution of this table might become imbalanced again over time.

## MySQL compatibility

This statement is a TiDB extension to MySQL syntax.

## See also

- [`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: An overview of the usage of SHOW DISTRIBUTION JOBS for the TiDB database.
---

# SHOW DISTRIBUTION JOBS

The `SHOW DISTRIBUTION JOBS` statement shows all current Region distribution jobs.

## Syntax

```ebnf+diagram
ShowDistributionJobsStmt ::=
"SHOW" "DISTRIBUTION" "JOBS"
```

## Examples

Show all current Region distribution jobs:

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

This statement is a TiDB extension to MySQL syntax.

## See also

- [`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)
61 changes: 61 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,61 @@
---
title: SHOW TABLE DISTRIBUTION
summary: An overview of the usage of SHOW TABLE DISTRIBUTION for the TiDB database.
---

# SHOW TABLE DISTRIBUTION

The `SHOW TABLE DISTRIBUTION` statement shows the Region distribution information for a specified table.

## Syntax

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

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

## Examples

Show the Region distribution of the table `t1`:

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

This statement is a TiDB extension to MySQL syntax.

## See also

- [`DISTRIBUTE TABLE`](/sql-statements/sql-statement-distribute-table.md)
- [`SHOW DISTRIBUTION JOBS`](/sql-statements/sql-statement-show-distribution-jobs.md)
- [`CANCEL DISTRIBUTION JOB`](/sql-statements/sql-statement-cancel-distribution-job.md)