From ba10b7a6fae929f9e1a0363e5ef99c773c83ca75 Mon Sep 17 00:00:00 2001 From: tongjian <1045931706@qq.com> Date: Mon, 8 Sep 2025 16:25:06 +0800 Subject: [PATCH 1/3] distribute-table: support to scatter the region distribution of the given table and engine (#19534) --- TOC.md | 4 + .../sql-statement-cancel-distribution-job.md | 38 ++++++ .../sql-statement-distribute-table.md | 120 ++++++++++++++++++ .../sql-statement-show-distribution-jobs.md | 43 +++++++ .../sql-statement-show-table-distribution.md | 60 +++++++++ 5 files changed, 265 insertions(+) create mode 100644 sql-statements/sql-statement-cancel-distribution-job.md create mode 100644 sql-statements/sql-statement-distribute-table.md create mode 100644 sql-statements/sql-statement-show-distribution-jobs.md create mode 100644 sql-statements/sql-statement-show-table-distribution.md diff --git a/TOC.md b/TOC.md index 465096f0a34b..2bff0b98f3a9 100644 --- a/TOC.md +++ b/TOC.md @@ -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) @@ -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) @@ -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) @@ -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) diff --git a/sql-statements/sql-statement-cancel-distribution-job.md b/sql-statements/sql-statement-cancel-distribution-job.md new file mode 100644 index 000000000000..319e30ba8cfe --- /dev/null +++ b/sql-statements/sql-statement-cancel-distribution-job.md @@ -0,0 +1,38 @@ +--- +title: CANCEL DISTRIBUTION JOB +summary: TiDB 数据库中 CANCEL DISTRIBUTION JOB 的使用情况。 +--- + +# CANCEL DISTRIBUTION JOB 从 v9.0.0 开始引入 + +`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) diff --git a/sql-statements/sql-statement-distribute-table.md b/sql-statements/sql-statement-distribute-table.md new file mode 100644 index 000000000000..9e9bf148d1db --- /dev/null +++ b/sql-statements/sql-statement-distribute-table.md @@ -0,0 +1,120 @@ +--- +title: DISTRIBUTE TABLE +summary: 介绍 TiDB 数据库中 DISTRIBUTE TABLE 的使用概况。 +--- + +# DISTRIBUTE TABLE 从 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 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) \ No newline at end of file diff --git a/sql-statements/sql-statement-show-distribution-jobs.md b/sql-statements/sql-statement-show-distribution-jobs.md new file mode 100644 index 000000000000..6da26fdc6431 --- /dev/null +++ b/sql-statements/sql-statement-show-distribution-jobs.md @@ -0,0 +1,43 @@ +--- +title: SHOW DISTRIBUTION JOBS +summary: 介绍 TiDB 数据库中 SHOW DISTRIBUTION JOBS 的使用概况。 +--- + +# SHOW DISTRIBUTION JOBS 从 v9.0.0 开始引入 + +`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) \ No newline at end of file diff --git a/sql-statements/sql-statement-show-table-distribution.md b/sql-statements/sql-statement-show-table-distribution.md new file mode 100644 index 000000000000..0195d501b3a2 --- /dev/null +++ b/sql-statements/sql-statement-show-table-distribution.md @@ -0,0 +1,60 @@ +--- +title: SHOW TABLE DISTRIBUTION +summary: 介绍 TiDB 数据库中 SHOW TABLE DISTRIBUTION 的使用概况。 +--- + +# SHOW TABLE DISTRIBUTION 从 v9.0.0 开始引入 + +`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) \ No newline at end of file From 5db0582699f5b704faf734fc43dbf9ecd87aab81 Mon Sep 17 00:00:00 2001 From: qiancai Date: Sat, 11 Oct 2025 14:15:58 +0800 Subject: [PATCH 2/3] change the intro version --- sql-statements/sql-statement-cancel-distribution-job.md | 2 +- sql-statements/sql-statement-distribute-table.md | 2 +- sql-statements/sql-statement-show-distribution-jobs.md | 2 +- sql-statements/sql-statement-show-table-distribution.md | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/sql-statements/sql-statement-cancel-distribution-job.md b/sql-statements/sql-statement-cancel-distribution-job.md index 319e30ba8cfe..737935df7b18 100644 --- a/sql-statements/sql-statement-cancel-distribution-job.md +++ b/sql-statements/sql-statement-cancel-distribution-job.md @@ -3,7 +3,7 @@ title: CANCEL DISTRIBUTION JOB summary: TiDB 数据库中 CANCEL DISTRIBUTION JOB 的使用情况。 --- -# CANCEL DISTRIBUTION JOB 从 v9.0.0 开始引入 +# CANCEL DISTRIBUTION JOB 从 v8.5.4 开始引入 `CANCEL DISTRIBUTION JOB` 语句用于取消 TiDB 中通过 [`DISTRIBUTE TABLE`](/sql-statements/sql-statement-distribute-table.md) 语句创建的 Region 调度任务。 diff --git a/sql-statements/sql-statement-distribute-table.md b/sql-statements/sql-statement-distribute-table.md index 9e9bf148d1db..acc926e6de8e 100644 --- a/sql-statements/sql-statement-distribute-table.md +++ b/sql-statements/sql-statement-distribute-table.md @@ -3,7 +3,7 @@ title: DISTRIBUTE TABLE summary: 介绍 TiDB 数据库中 DISTRIBUTE TABLE 的使用概况。 --- -# DISTRIBUTE TABLE 从 v9.0.0 开始引入 +# DISTRIBUTE TABLE 从 v8.5.4 开始引入 > **警告:** > diff --git a/sql-statements/sql-statement-show-distribution-jobs.md b/sql-statements/sql-statement-show-distribution-jobs.md index 6da26fdc6431..76198998c662 100644 --- a/sql-statements/sql-statement-show-distribution-jobs.md +++ b/sql-statements/sql-statement-show-distribution-jobs.md @@ -3,7 +3,7 @@ title: SHOW DISTRIBUTION JOBS summary: 介绍 TiDB 数据库中 SHOW DISTRIBUTION JOBS 的使用概况。 --- -# SHOW DISTRIBUTION JOBS 从 v9.0.0 开始引入 +# SHOW DISTRIBUTION JOBS 从 v8.5.4 开始引入 `SHOW DISTRIBUTION JOBS` 语句用于显示当前所有的 Region 调度任务。 diff --git a/sql-statements/sql-statement-show-table-distribution.md b/sql-statements/sql-statement-show-table-distribution.md index 0195d501b3a2..b94741ac18fe 100644 --- a/sql-statements/sql-statement-show-table-distribution.md +++ b/sql-statements/sql-statement-show-table-distribution.md @@ -3,7 +3,7 @@ title: SHOW TABLE DISTRIBUTION summary: 介绍 TiDB 数据库中 SHOW TABLE DISTRIBUTION 的使用概况。 --- -# SHOW TABLE DISTRIBUTION 从 v9.0.0 开始引入 +# SHOW TABLE DISTRIBUTION 从 v8.5.4 开始引入 `SHOW TABLE DISTRIBUTION` 语句用于显示指定表的 Region 分布情况。 From 74669753cb56edf5e56c1cec83b25508b082ac91 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Sat, 11 Oct 2025 15:41:38 +0800 Subject: [PATCH 3/3] fix the table name and format --- sql-statements/sql-statement-show-table-distribution.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/sql-statements/sql-statement-show-table-distribution.md b/sql-statements/sql-statement-show-table-distribution.md index b94741ac18fe..36ca095aa963 100644 --- a/sql-statements/sql-statement-show-table-distribution.md +++ b/sql-statements/sql-statement-show-table-distribution.md @@ -19,7 +19,7 @@ TableName ::= ## 示例 -显示当前表 `t1` 的 Region 分布情况: +显示当前表 `t` 的 Region 分布情况: ```sql CREATE TABLE `t` ( @@ -29,8 +29,8 @@ CREATE TABLE `t` ( ) 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 `p2` VALUES LESS THAN (MAXVALUE)); +SHOW TABLE t DISTRIBUTIONS; ``` ```