From ca62ac690728edd48dd3e46657f60dfe5bfa570f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=AB=A5=E5=89=91?= <1045931706@qq.com> Date: Mon, 13 Jan 2025 16:43:39 +0800 Subject: [PATCH 01/24] add distribute table fd MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: 童剑 <1045931706@qq.com> --- .../sql_statement_distribute_table.md | 84 +++++++++++++++++++ 1 file changed, 84 insertions(+) create mode 100644 sql-statements/sql_statement_distribute_table.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..6b867332dee6 --- /dev/null +++ b/sql-statements/sql_statement_distribute_table.md @@ -0,0 +1,84 @@ +--- +title: distribute table 使用文档 +aliases: ['/docs-cn/dev/sql-statements/sql-statement-distribute-table/','/docs-cn/dev/reference/sql/statements/distribute-table/'] +summary: TiDB 中的 distribute table 功能可以解决表中 region 分布不均衡问题。通过重新调整 table 中的 region 的分布，可以让指定 table 下的 region 按照一定的策略进行均衡。重新分配可以指定不同的存储引擎，比如 TIFLASH 和 TIKV。同时也可以指定不同的 raft role，比如 learner，leader，voter。 +--- + +# Distribute Table 使用文档 + +## 语法图 + +```ebnf+diagram +DistributeTableStmt ::= + "DISTRIBUTE" "TABLE" TableName PartitionNameList? EngineOption? RoleOption? + +TableName ::= + (SchemaName ".")? Identifier + +PartitionNameList ::= + "PARTITION" "(" PartitionName ("," PartitionName)* ")" + +EngineOption ::= + "ENGINE" Expression + +RoleOption ::= + "Role" Expression + +``` + +## 示例 + +对表A 上的 tikv 上的 leader 重新进行均衡调度 +```sql +CREATE TABLE t1 (a INT)； +... +DISTRIBUTE TABLE table_name engine tikv role leader +``` ++---------+ +| JOB_ID | +100 ++---------+ + + + +显示当前所有的调度任务 +```sql +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 | ++---------+------------+------------+-----------------+------------+-----------+----------+-------------+---------------+ + + +显示当前表 t1 的 region 分布情况 +```sql +SHOW TABLE DISTRIBUTION t1; +``` + ++---------+------------+----------------+----------+------------+-------------------+--------------------+-----------------+------------------+ +| 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 | ++---------+------------+----------------+----------+------------+-------------------+--------------------+-----------------+------------------+ + +### Distribute Table Region + + +## 注意事项 + +Distribute Table 语句重新调度 table 下的 region 也会受到 PD 中热点调度器的影响。 同时该任务会在均衡后退出，退出后该表的分布可能会 +被被破坏。 + +## MySQL 兼容性 +该语句是 TiDB 对 MySQL 语法的扩展。 + +## 另请参阅 From a4fc306ecd717593fe59b7c22d858ba53dc7e59d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=AB=A5=E5=89=91?= <1045931706@qq.com> Date: Thu, 6 Feb 2025 15:31:11 +0800 Subject: [PATCH 02/24] address comment MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: 童剑 <1045931706@qq.com> --- sql-statements/sql_statement_distribute_table.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/sql-statements/sql_statement_distribute_table.md b/sql-statements/sql_statement_distribute_table.md index 6b867332dee6..0e0c120dac85 100644 --- a/sql-statements/sql_statement_distribute_table.md +++ b/sql-statements/sql_statement_distribute_table.md @@ -1,10 +1,10 @@ --- title: distribute table 使用文档 -aliases: ['/docs-cn/dev/sql-statements/sql-statement-distribute-table/','/docs-cn/dev/reference/sql/statements/distribute-table/'] summary: TiDB 中的 distribute table 功能可以解决表中 region 分布不均衡问题。通过重新调整 table 中的 region 的分布，可以让指定 table 下的 region 按照一定的策略进行均衡。重新分配可以指定不同的存储引擎，比如 TIFLASH 和 TIKV。同时也可以指定不同的 raft role，比如 learner，leader，voter。 --- -# Distribute Table 使用文档 +# DISTRIBUTE TABLE 使用文档 +`DISTRIBUTE TABLE` 用于对指定表范围内的 region 进行重新打散调度， 使其按照表纬度进行均衡分布，防止个别 region 集中在少数的 TIFLASH 和 TIKV。 ## 语法图 @@ -70,8 +70,6 @@ SHOW TABLE DISTRIBUTION t1; | db_1 | t1 | | 4 | TiKV | 503 | 41039587625 | 1101 | 90482317797 | +---------+------------+----------------+----------+------------+-------------------+--------------------+-----------------+------------------+ -### Distribute Table Region - ## 注意事项 From c0b9415acb3ca539395e2694c501641628c8c301 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=AB=A5=E5=89=91?= <1045931706@qq.com> Date: Thu, 13 Feb 2025 15:05:53 +0800 Subject: [PATCH 03/24] address comment MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: 童剑 <1045931706@qq.com> --- .../sql_statement_distribute_table.md | 43 ++++++++++++++----- 1 file changed, 33 insertions(+), 10 deletions(-) diff --git a/sql-statements/sql_statement_distribute_table.md b/sql-statements/sql_statement_distribute_table.md index 0e0c120dac85..d4655cf5d399 100644 --- a/sql-statements/sql_statement_distribute_table.md +++ b/sql-statements/sql_statement_distribute_table.md @@ -1,10 +1,10 @@ --- -title: distribute table 使用文档 -summary: TiDB 中的 distribute table 功能可以解决表中 region 分布不均衡问题。通过重新调整 table 中的 region 的分布，可以让指定 table 下的 region 按照一定的策略进行均衡。重新分配可以指定不同的存储引擎，比如 TIFLASH 和 TIKV。同时也可以指定不同的 raft role，比如 learner，leader，voter。 +title: DISTRIBUTE TABLE +summary: 介绍 TiDB 数据库中 DISTRIBUTE TABLE 的使用概况。 --- # DISTRIBUTE TABLE 使用文档 -`DISTRIBUTE TABLE` 用于对指定表范围内的 region 进行重新打散调度， 使其按照表纬度进行均衡分布，防止个别 region 集中在少数的 TIFLASH 和 TIKV。 +`DISTRIBUTE TABLE` 语句用于对指定表的 Region 进行重新打散和调度，以实现表维度的均衡分布。执行该语句可以防止个别 Region 集中在少数 TiFlash 或 TiKV 节点上，从而解决表中 Region 分布不均衡的问题。 ## 语法图 @@ -27,10 +27,12 @@ RoleOption ::= ``` ## 示例 +通过 `DISTRIBUTE TABLE` 语句重新调度表中的 Region 时，你可以根据需求指定存储引擎（如 TiFlash 或 TiKV）以及不同的 Raft 角色（如 learner、leader、voter） 进行打散均衡操作。 + +对表 `t1` 在 TiKV 上的 leader 所在的 Region 重新进行均衡调度： -对表A 上的 tikv 上的 leader 重新进行均衡调度 ```sql -CREATE TABLE t1 (a INT)； +CREATE TABLE t1 (a INT); ... DISTRIBUTE TABLE table_name engine tikv role leader ``` @@ -39,9 +41,31 @@ DISTRIBUTE TABLE table_name engine tikv role leader 100 +---------+ +对表 `t2` 在 TiFlash 上的 learner 所在的 Region 重新进行均衡调度： +```sql +CREATE TABLE t2 (a INT); +... +DISTRIBUTE TABLE t2 ENGINE tiflash role learner; +``` ++---------+ +| JOB_ID | +101 ++---------+ + +对分区表 `t5` 的 `p1` 和 `p2` 分区在 TiKV 上的 leader 所在的 Region 重新进行均衡调度： + +```sql +CREATE TABLE t5 (a INT); +... +DISTRIBUTE TABLE t5 PARTITION (p1, p2) ENGINE tikv role leader; +``` ++---------+ +| JOB_ID | +102 ++---------+ -显示当前所有的调度任务 +显示当前所有的调度任务： ```sql SHOW DISTRIBUTION JOBS; ``` @@ -49,14 +73,14 @@ 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 | +| 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 | +---------+------------+------------+-----------------+------------+-----------+----------+-------------+---------------+ -显示当前表 t1 的 region 分布情况 +显示当前表 `t1` 的 region 分布情况: ```sql SHOW TABLE DISTRIBUTION t1; ``` @@ -73,8 +97,7 @@ SHOW TABLE DISTRIBUTION t1; ## 注意事项 -Distribute Table 语句重新调度 table 下的 region 也会受到 PD 中热点调度器的影响。 同时该任务会在均衡后退出，退出后该表的分布可能会 -被被破坏。 +`DISTRIBUTE TABLE` 语句在重新调度表中的 Region 时，可能会受到 PD 热点调度器的影响。调度完成后，随着时间推移，表的 Region 分布可能再次失衡。 ## MySQL 兼容性 该语句是 TiDB 对 MySQL 语法的扩展。 From e80d3346a43d6551cee8a8c92e262ee4813c1308 Mon Sep 17 00:00:00 2001 From: qiancai Date: Thu, 20 Feb 2025 15:55:40 +0800 Subject: [PATCH 04/24] add toc changes and anther two sql docs --- TOC.md | 3 ++ .../sql-statement-show-distribution-jobs.md | 43 +++++++++++++++++ .../sql_statement-show-table-distribution.md | 46 ++++++++++++++++++ .../sql_statement_distribute_table.md | 48 +++++++++++++------ 4 files changed, 125 insertions(+), 15 deletions(-) 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 853182eeccaa..edeb53eb3fce 100644 --- a/TOC.md +++ b/TOC.md @@ -788,6 +788,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) @@ -852,6 +853,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) @@ -874,6 +876,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-show-distribution-jobs.md b/sql-statements/sql-statement-show-distribution-jobs.md new file mode 100644 index 000000000000..f075735272f6 --- /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 + +`SHOW DISTRIBUTION JOBS` 语句用于显示当前所有的 Region 调度任务。 + +## 语法图 + +```ebnf+diagram +ShowDistributionJobsStmt ::= + "SHOW" "DISTRIBUTION" "JOBS" +``` + +## 示例 + +显示当前所有的 Region 调度任务： + +```sql +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 | ++---------+------------+------------+-----------------+------------+-----------+----------+-------------+---------------+ +``` + +## MySQL 兼容性 + +该语句是 TiDB 对 MySQL 语法的扩展。 + +## 另请参阅 + +- [`DISTRIBUTE TABLE`](/sql-statements/sql_statement-distribute-table.md) +- [`SHOW TABLE DISTRIBUTION`](/sql-statements/sql_statement-show-table-distribution.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..18f78b0fbf80 --- /dev/null +++ b/sql-statements/sql_statement-show-table-distribution.md @@ -0,0 +1,46 @@ +--- +title: SHOW TABLE DISTRIBUTION +summary: 介绍 TiDB 数据库中 SHOW TABLE DISTRIBUTION 的使用概况。 +--- + +# SHOW TABLE DISTRIBUTION + +`SHOW TABLE DISTRIBUTION` 语句用于显示指定表的 Region 分布情况。 + +## 语法图 + +```ebnf+diagram +ShowTableDistributionStmt ::= + "SHOW" "TABLE" "DISTRIBUTION" TableName + +TableName ::= + (SchemaName ".")? Identifier +``` + +## 示例 + +显示当前表 `t1` 的 Region 分布情况: + +```sql +SHOW TABLE DISTRIBUTION t1; +``` + +``` ++---------+------------+----------------+----------+------------+-------------------+--------------------+-----------------+------------------+ +| 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 | ++---------+------------+----------------+----------+------------+-------------------+--------------------+-----------------+------------------+ +``` + +## 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 diff --git a/sql-statements/sql_statement_distribute_table.md b/sql-statements/sql_statement_distribute_table.md index d4655cf5d399..74045c955451 100644 --- a/sql-statements/sql_statement_distribute_table.md +++ b/sql-statements/sql_statement_distribute_table.md @@ -3,7 +3,8 @@ title: DISTRIBUTE TABLE summary: 介绍 TiDB 数据库中 DISTRIBUTE TABLE 的使用概况。 --- -# DISTRIBUTE TABLE 使用文档 +# DISTRIBUTE TABLE + `DISTRIBUTE TABLE` 语句用于对指定表的 Region 进行重新打散和调度，以实现表维度的均衡分布。执行该语句可以防止个别 Region 集中在少数 TiFlash 或 TiKV 节点上，从而解决表中 Region 分布不均衡的问题。 ## 语法图 @@ -23,53 +24,64 @@ EngineOption ::= RoleOption ::= "Role" Expression - ``` ## 示例 -通过 `DISTRIBUTE TABLE` 语句重新调度表中的 Region 时，你可以根据需求指定存储引擎（如 TiFlash 或 TiKV）以及不同的 Raft 角色（如 learner、leader、voter） 进行打散均衡操作。 -对表 `t1` 在 TiKV 上的 leader 所在的 Region 重新进行均衡调度： +通过 `DISTRIBUTE TABLE` 语句重新调度表中的 Region 时，你可以根据需求指定存储引擎（如 TiFlash 或 TiKV）以及不同的 Raft 角色（如 Leader、Learner、Voter）进行均衡打散操作。 + +对表 `t1` 在 TiKV 上的 Leader 所在的 Region 重新进行均衡调度： ```sql CREATE TABLE t1 (a INT); ... -DISTRIBUTE TABLE table_name engine tikv role leader +DISTRIBUTE TABLE t1 engine tikv role leader +``` + ``` +---------+ -| JOB_ID | +| JOB_ID | 100 +---------+ +``` + +对表 `t2` 在 TiFlash 上的 Learner 所在的 Region 重新进行均衡调度： -对表 `t2` 在 TiFlash 上的 learner 所在的 Region 重新进行均衡调度： ```sql CREATE TABLE t2 (a INT); ... DISTRIBUTE TABLE t2 ENGINE tiflash role learner; +``` + ``` +---------+ -| JOB_ID | +| JOB_ID | 101 +---------+ +``` -对分区表 `t5` 的 `p1` 和 `p2` 分区在 TiKV 上的 leader 所在的 Region 重新进行均衡调度： +对分区表 `t3` 的 `p1` 和 `p2` 分区在 TiKV 上的 Leader 所在的 Region 重新进行均衡调度： ```sql -CREATE TABLE t5 (a INT); +CREATE TABLE t3 (a INT); ... -DISTRIBUTE TABLE t5 PARTITION (p1, p2) ENGINE tikv role leader; +DISTRIBUTE TABLE t3 PARTITION (p1, p2) ENGINE tikv role leader; +``` + ``` +---------+ -| JOB_ID | +| JOB_ID | 102 +---------+ +``` +执行 [`SHOW DISTRIBUTION JOBS`](/sql-statements/sql-statement-show-distribution-jobs.md) 语句查看当前所有的调度任务： -显示当前所有的调度任务： ```sql SHOW DISTRIBUTION JOBS; ``` +``` +---------+------------+------------+-----------------+------------+-----------+----------+-------------+---------------+ | JOB_ID | DB_NAME | TABLE_NAME | PARTITION_NAMES | ENGINE_TYPE | ROLE_TYPE | STATUS | CREATE_USER | CREATE_TIME | +---------+------------+------------+-----------------+------------+-----------+--------+---------------+---------------+ @@ -78,13 +90,15 @@ SHOW DISTRIBUTION JOBS; | 3 | db_1 | t3 | | TiKV | VOTER | STOPPED | ADMIN | 20240713 | | 4 | db_1 | t4 | | TIFLASH | LEARNER | FINISHED | ADMIN | 20240713 | +---------+------------+------------+-----------------+------------+-----------+----------+-------------+---------------+ +``` +执行 [`SHOW TABLE DISTRIBUTION`](/sql-statements/sql_statement-show-table-distribution.md) 语句查看表 `t1` 的 Region 分布情况： -显示当前表 `t1` 的 region 分布情况: ```sql SHOW TABLE DISTRIBUTION t1; ``` +``` +---------+------------+----------------+----------+------------+-------------------+--------------------+-----------------+------------------+ | DB_NAME | TABLE_NAME | PARTITION_NAME | STORE_ID | STORE_TYPE | REGION_LEADER_NUM | REGION_LEADER_BYTE | REGION_PEER_NUM | REGION_PEER_BYTE | +---------+------------+----------------+----------+------------+-------------------+--------------------+-----------------+------------------+ @@ -93,13 +107,17 @@ SHOW TABLE DISTRIBUTION t1; | db_1 | t1 | | 3 | TiKV | 319 | 25986274812 | 1091 | 89405367423 | | db_1 | t1 | | 4 | TiKV | 503 | 41039587625 | 1101 | 90482317797 | +---------+------------+----------------+----------+------------+-------------------+--------------------+-----------------+------------------+ - +``` ## 注意事项 `DISTRIBUTE TABLE` 语句在重新调度表中的 Region 时，可能会受到 PD 热点调度器的影响。调度完成后，随着时间推移，表的 Region 分布可能再次失衡。 ## MySQL 兼容性 + 该语句是 TiDB 对 MySQL 语法的扩展。 ## 另请参阅 + +- [`SHOW TABLE DISTRIBUTION`](/sql-statements/sql_statement-show-table-distribution.md) +- [`SHOW TABLE REGIONS`](/sql-statements/sql-statement-show-table-regions.md) \ No newline at end of file From 1bdc893ceea4db4c83f664a2bfadaf4a8323f584 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Thu, 20 Feb 2025 16:02:34 +0800 Subject: [PATCH 05/24] Apply suggestions from code review --- sql-statements/sql_statement-show-table-distribution.md | 2 +- sql-statements/sql_statement_distribute_table.md | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/sql-statements/sql_statement-show-table-distribution.md b/sql-statements/sql_statement-show-table-distribution.md index 18f78b0fbf80..91069ba20692 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 分布情况: +显示当前表 `t1` 的 Region 分布情况： ```sql SHOW TABLE DISTRIBUTION t1; diff --git a/sql-statements/sql_statement_distribute_table.md b/sql-statements/sql_statement_distribute_table.md index 74045c955451..308d7f004d97 100644 --- a/sql-statements/sql_statement_distribute_table.md +++ b/sql-statements/sql_statement_distribute_table.md @@ -119,5 +119,6 @@ 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) \ No newline at end of file From 2bfb0e101d5549e0cff0aa60e812ef37fb59d523 Mon Sep 17 00:00:00 2001 From: qiancai Date: Fri, 21 Feb 2025 09:56:23 +0800 Subject: [PATCH 06/24] update the file naming style to use hyphen --- TOC.md | 4 ++-- ..._distribute_table.md => sql-statement-distribute-table.md} | 4 ++-- sql-statements/sql-statement-show-distribution-jobs.md | 4 ++-- ...stribution.md => sql-statement-show-table-distribution.md} | 2 +- 4 files changed, 7 insertions(+), 7 deletions(-) rename sql-statements/{sql_statement_distribute_table.md => sql-statement-distribute-table.md} (97%) rename sql-statements/{sql_statement-show-table-distribution.md => sql-statement-show-table-distribution.md} (96%) diff --git a/TOC.md b/TOC.md index edeb53eb3fce..65f70b908d47 100644 --- a/TOC.md +++ b/TOC.md @@ -788,7 +788,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) + - [`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) @@ -876,7 +876,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 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_distribute_table.md b/sql-statements/sql-statement-distribute-table.md similarity index 97% rename from sql-statements/sql_statement_distribute_table.md rename to sql-statements/sql-statement-distribute-table.md index 308d7f004d97..fa6823009705 100644 --- a/sql-statements/sql_statement_distribute_table.md +++ b/sql-statements/sql-statement-distribute-table.md @@ -92,7 +92,7 @@ SHOW DISTRIBUTION JOBS; +---------+------------+------------+-----------------+------------+-----------+----------+-------------+---------------+ ``` -执行 [`SHOW TABLE DISTRIBUTION`](/sql-statements/sql_statement-show-table-distribution.md) 语句查看表 `t1` 的 Region 分布情况： +执行 [`SHOW TABLE DISTRIBUTION`](/sql-statements/sql-statement-show-table-distribution.md) 语句查看表 `t1` 的 Region 分布情况： ```sql SHOW TABLE DISTRIBUTION t1; @@ -120,5 +120,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 DISTRIBUTION`](/sql-statements/sql-statement-show-table-distribution.md) - [`SHOW TABLE REGIONS`](/sql-statements/sql-statement-show-table-regions.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 index f075735272f6..3a814626518c 100644 --- a/sql-statements/sql-statement-show-distribution-jobs.md +++ b/sql-statements/sql-statement-show-distribution-jobs.md @@ -39,5 +39,5 @@ SHOW DISTRIBUTION JOBS; ## 另请参阅 -- [`DISTRIBUTE TABLE`](/sql-statements/sql_statement-distribute-table.md) -- [`SHOW TABLE DISTRIBUTION`](/sql-statements/sql_statement-show-table-distribution.md) \ No newline at end of file +- [`DISTRIBUTE TABLE`](/sql-statements/sql-statement-distribute-table.md) +- [`SHOW TABLE DISTRIBUTION`](/sql-statements/sql-statement-show-table-distribution.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 similarity index 96% rename from sql-statements/sql_statement-show-table-distribution.md rename to sql-statements/sql-statement-show-table-distribution.md index 91069ba20692..bd0f0250ce7b 100644 --- a/sql-statements/sql_statement-show-table-distribution.md +++ b/sql-statements/sql-statement-show-table-distribution.md @@ -42,5 +42,5 @@ SHOW TABLE DISTRIBUTION t1; ## 另请参阅 -- [`DISTRIBUTE TABLE`](/sql-statements/sql_statement-distribute-table.md) +- [`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 acd05fa11ec4b02faf085f08737c349c0e07f2a5 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Mon, 17 Mar 2025 17:22:47 +0800 Subject: [PATCH 07/24] Apply suggestions from code review Co-authored-by: Aolin --- sql-statements/sql-statement-distribute-table.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sql-statements/sql-statement-distribute-table.md b/sql-statements/sql-statement-distribute-table.md index fa6823009705..38ede2264327 100644 --- a/sql-statements/sql-statement-distribute-table.md +++ b/sql-statements/sql-statement-distribute-table.md @@ -5,7 +5,7 @@ summary: 介绍 TiDB 数据库中 DISTRIBUTE TABLE 的使用概况。 # DISTRIBUTE TABLE -`DISTRIBUTE TABLE` 语句用于对指定表的 Region 进行重新打散和调度，以实现表维度的均衡分布。执行该语句可以防止个别 Region 集中在少数 TiFlash 或 TiKV 节点上，从而解决表中 Region 分布不均衡的问题。 +`DISTRIBUTE TABLE` 语句用于对指定表的 Region 进行重新打散和调度，以实现表级别的均衡分布。执行该语句可以防止个别 Region 集中在少数 TiFlash 或 TiKV 节点上，从而解决表中 Region 分布不均衡的问题。 ## 语法图 From 92d3a9c9612b1c5f7042d369737e2b3f216ada80 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=AB=A5=E5=89=91?= <1045931706@qq.com> Date: Wed, 21 May 2025 15:55:29 +0800 Subject: [PATCH 08/24] add cancel job sql MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: 童剑 <1045931706@qq.com> --- .../sql_statement_distribute_table.md | 75 +++++++++---------- 1 file changed, 36 insertions(+), 39 deletions(-) diff --git a/sql-statements/sql_statement_distribute_table.md b/sql-statements/sql_statement_distribute_table.md index d4655cf5d399..27d376bc5462 100644 --- a/sql-statements/sql_statement_distribute_table.md +++ b/sql-statements/sql_statement_distribute_table.md @@ -10,90 +10,87 @@ summary: 介绍 TiDB 数据库中 DISTRIBUTE TABLE 的使用概况。 ```ebnf+diagram DistributeTableStmt ::= - "DISTRIBUTE" "TABLE" TableName PartitionNameList? EngineOption? RoleOption? + "DISTRIBUTE" "TABLE" TableName PartitionNameListOpt "RULE" EqOrAssignmentEq Identifier "ENGINE" EqOrAssignmentEq Identifier TableName ::= (SchemaName ".")? Identifier PartitionNameList ::= "PARTITION" "(" PartitionName ("," PartitionName)* ")" - -EngineOption ::= - "ENGINE" Expression - -RoleOption ::= - "Role" Expression - ``` ## 示例 -通过 `DISTRIBUTE TABLE` 语句重新调度表中的 Region 时，你可以根据需求指定存储引擎（如 TiFlash 或 TiKV）以及不同的 Raft 角色（如 learner、leader、voter） 进行打散均衡操作。 +通过 `DISTRIBUTE TABLE` 语句重新调度表中的 Region 时，你可以根据需求指定存储引擎（如 TiFlash 或 TiKV）以及不同的 Raft 角色（如 learner、leader、peer） 进行打散均衡操作。 对表 `t1` 在 TiKV 上的 leader 所在的 Region 重新进行均衡调度： ```sql CREATE TABLE t1 (a INT); ... -DISTRIBUTE TABLE table_name engine tikv role leader -``` +DISTRIBUTE TABLE t1 RULE= `leader-scatter` ENGINE = tikv +---------+ | 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 +---------+ +``` -对分区表 `t5` 的 `p1` 和 `p2` 分区在 TiKV 上的 leader 所在的 Region 重新进行均衡调度： +对分区表 `t5` 的 `p1` 和 `p2` 分区在 TiKV 上的 peer 所在的 Region 重新进行均衡调度： ```sql -CREATE TABLE t5 (a INT); +CREATE TABLE t ( 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 t5 PARTITION (p1, p2) ENGINE tikv role leader; -``` +DISTRIBUTE TABLE t5 PARTITION (p1, p2) RULE= `peer-scatter` ENGINE =tikv; + +---------+ | JOB_ID | 102 +---------+ - +``` 显示当前所有的调度任务： ```sql 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 | ++--------+----------+-------+----------------+--------+----------------+-----------+---------------------+---------------------+---------------------+ +``` -显示当前表 `t1` 的 region 分布情况: +取消指定的调度任务 ```sql -SHOW TABLE DISTRIBUTION t1; +CANCEL DISTRIBUTION JOB 1; ``` -+---------+------------+----------------+----------+------------+-------------------+--------------------+-----------------+------------------+ -| 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 | -+---------+------------+----------------+----------+------------+-------------------+--------------------+-----------------+------------------+ - +显示当前表 `t5` 的 region 分布情况: +```sql +SHOW TABLE t5 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 | 4 | 11 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | +| p2 | 4 | tikv | 3 | 11 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | +| p3 | 5 | tikv | 1 | 1 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | ++----------------+----------+------------+---------------------+-------------------+--------------------+-------------------+--------------------+--------------------------+-------------------------+--------------------------+------------------------+-----------------------+------------------------+ +``` ## 注意事项 From 20a6312bdbdeb7029d48762d40310f0c33e7bfe8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=AB=A5=E5=89=91?= <1045931706@qq.com> Date: Wed, 21 May 2025 16:05:44 +0800 Subject: [PATCH 09/24] split MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: 童剑 <1045931706@qq.com> --- .../sql-statement-distribute-table.md | 25 ------------------- .../sql-statement-show-distribution-jobs.md | 15 ++++++----- .../sql-statement-show-table-distribution.md | 15 ++++++----- 3 files changed, 14 insertions(+), 41 deletions(-) diff --git a/sql-statements/sql-statement-distribute-table.md b/sql-statements/sql-statement-distribute-table.md index d046b03f2659..511f51f71dfe 100644 --- a/sql-statements/sql-statement-distribute-table.md +++ b/sql-statements/sql-statement-distribute-table.md @@ -78,36 +78,11 @@ DISTRIBUTE TABLE t3 PARTITION (p1, p2) ENGINE tikv role leader; +---------+ ``` -```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 | -+--------+----------+-------+----------------+--------+----------------+-----------+---------------------+---------------------+---------------------+ -``` - 取消指定的调度任务 ```sql CANCEL DISTRIBUTION JOB 1; ``` -显示当前表 `t5` 的 region 分布情况: -```sql -SHOW TABLE t5 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 | 4 | 11 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | -| p2 | 4 | tikv | 3 | 11 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | -| p3 | 5 | tikv | 1 | 1 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | -+----------------+----------+------------+---------------------+-------------------+--------------------+-------------------+--------------------+--------------------------+-------------------------+--------------------------+------------------------+-----------------------+------------------------+ -``` - ## 注意事项 `DISTRIBUTE TABLE` 语句在重新调度表中的 Region 时，可能会受到 PD 热点调度器的影响。调度完成后，随着时间推移，表的 Region 分布可能再次失衡。 diff --git a/sql-statements/sql-statement-show-distribution-jobs.md b/sql-statements/sql-statement-show-distribution-jobs.md index 3a814626518c..fb1db4a43dd0 100644 --- a/sql-statements/sql-statement-show-distribution-jobs.md +++ b/sql-statements/sql-statement-show-distribution-jobs.md @@ -23,14 +23,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 兼容性 diff --git a/sql-statements/sql-statement-show-table-distribution.md b/sql-statements/sql-statement-show-table-distribution.md index bd0f0250ce7b..50d8a28c4e27 100644 --- a/sql-statements/sql-statement-show-table-distribution.md +++ b/sql-statements/sql-statement-show-table-distribution.md @@ -26,14 +26,13 @@ SHOW TABLE DISTRIBUTION t1; ``` ``` -+---------+------------+----------------+----------+------------+-------------------+--------------------+-----------------+------------------+ -| 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 | 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 兼容性 From a4ccf2cadc66e356d7dc234f29240f983efcf42e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=AB=A5=E5=89=91?= <1045931706@qq.com> Date: Thu, 29 May 2025 10:43:39 +0800 Subject: [PATCH 10/24] address comment MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: 童剑 <1045931706@qq.com> --- .../sql-statement-distribute-table.md | 39 ++++++++++++------- 1 file changed, 26 insertions(+), 13 deletions(-) diff --git a/sql-statements/sql-statement-distribute-table.md b/sql-statements/sql-statement-distribute-table.md index 511f51f71dfe..5af9963fe03c 100644 --- a/sql-statements/sql-statement-distribute-table.md +++ b/sql-statements/sql-statement-distribute-table.md @@ -11,7 +11,7 @@ summary: 介绍 TiDB 数据库中 DISTRIBUTE TABLE 的使用概况。 ```ebnf+diagram DistributeTableStmt ::= - "DISTRIBUTE" "TABLE" TableName PartitionNameListOpt "RULE" EqOrAssignmentEq Identifier "ENGINE" EqOrAssignmentEq Identifier + "DISTRIBUTE" "TABLE" TableName PartitionNameListOpt "RULE" EqOrAssignmentEq Identifier "ENGINE" EqOrAssignmentEq Identifier "TIMEOUT" EqOrAssignmentEq Identifier TableName ::= (SchemaName ".")? Identifier @@ -24,63 +24,76 @@ PartitionNameList ::= ## 示例 通过 `DISTRIBUTE TABLE` 语句重新调度表中的 Region 时，你可以根据需求指定存储引擎（如 TiFlash 或 TiKV）以及不同的 Raft 角色（如 Leader、Learner、Voter）进行均衡打散操作。 +timeout: 如果 PD 在改指定时间内没有打散时会退出该任务，默认值为 30m。 对表 `t1` 在 TiKV 上的 Leader 所在的 Region 重新进行均衡调度： ```sql CREATE TABLE t1 (a INT); ... -DISTRIBUTE TABLE t1 RULE= `leader-scatter` ENGINE = tikv +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; +DISTRIBUTE table t2 RULE = `learner-scatter` ENGINE = tiflash; +``` + +``` +---------+ | JOB_ID | 101 +---------+ ``` -对分区表 `t5` 的 `p1` 和 `p2` 分区在 TiKV 上的 peer 所在的 Region 重新进行均衡调度： +对分区表 `t3· 的 `p1` 和 `p2` 分区在 TiKV 上的 peer 所在的 Region 重新进行均衡调度： ```sql -CREATE TABLE t ( a INT, b INT, INDEX idx(b)) PARTITION BY RANGE( a ) ( +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 t5 PARTITION (p1, p2) RULE= `peer-scatter` ENGINE =tikv; +DISTRIBUTE TABLE t3 PARTITION (p1, p2) RULE = `peer-scatter` ENGINE = tikv; +``` +``` +---------+ | JOB_ID | -101 +102 +---------+ ``` -对分区表 `t3` 的 `p1` 和 `p2` 分区在 TiKV 上的 Leader 所在的 Region 重新进行均衡调度： +对分区表 `t4` 的 `p1` 和 `p2` 分区在 TiKV 上的 Leader 所在的 Region 重新进行均衡调度： ```sql -CREATE TABLE t3 (a INT); -... -DISTRIBUTE TABLE t3 PARTITION (p1, p2) ENGINE tikv role leader; +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 = `leader-scatter` ENGINE=tiflash; ``` ``` +---------+ | JOB_ID | -102 +103 +---------+ ``` 取消指定的调度任务 + ```sql -CANCEL DISTRIBUTION JOB 1; +CANCEL DISTRIBUTION JOB 100; ``` ## 注意事项 From 1e9b393a0101476c7cd33177fe8fdf0a93cb3eb3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=AB=A5=E5=89=91?= <1045931706@qq.com> Date: Fri, 30 May 2025 14:38:09 +0800 Subject: [PATCH 11/24] cancel distribution job MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: 童剑 <1045931706@qq.com> --- .../sql-statement-cancel-distribution-job.md | 39 +++++++++++++++++++ .../sql-statement-distribute-table.md | 9 +---- 2 files changed, 41 insertions(+), 7 deletions(-) create mode 100644 sql-statements/sql-statement-cancel-distribution-job.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..01e24503e39b --- /dev/null +++ b/sql-statements/sql-statement-cancel-distribution-job.md @@ -0,0 +1,39 @@ +--- +title: CANCEL DISTRIBUTION +summary: TiDB 数据库中 CANCEL DISTRIBUTION 的使用情况。 +--- + +# CANCEL IMPORT + +`CANCEL DISTRIBUTION` 语句用于取消 TiDB 中创建的 region 调度任务。 +。 + +## 语法图 + +```ebnf+diagram +CancelImportJobsStmt ::= + '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) diff --git a/sql-statements/sql-statement-distribute-table.md b/sql-statements/sql-statement-distribute-table.md index 5af9963fe03c..af98a2c8a581 100644 --- a/sql-statements/sql-statement-distribute-table.md +++ b/sql-statements/sql-statement-distribute-table.md @@ -90,12 +90,6 @@ DISTRIBUTE TABLE t4 PARTITION (p1, p2) RULE = `leader-scatter` ENGINE=tiflash; +---------+ ``` -取消指定的调度任务 - -```sql -CANCEL DISTRIBUTION JOB 100; -``` - ## 注意事项 `DISTRIBUTE TABLE` 语句在重新调度表中的 Region 时，可能会受到 PD 热点调度器的影响。调度完成后，随着时间推移，表的 Region 分布可能再次失衡。 @@ -108,4 +102,5 @@ CANCEL DISTRIBUTION JOB 100; - [`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) \ No newline at end of file +- [`SHOW TABLE REGIONS`](/sql-statements/sql-statement-show-table-regions.md) +- [`CANCEL DISTRIBUTION JOBS`] (/sql-statements/sql-statement-cancel-distribution-job.md) \ No newline at end of file From 51c781b97e914a4794a4e2205b28ee7dfafa2aaa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=AB=A5=E5=89=91?= <1045931706@qq.com> Date: Wed, 4 Jun 2025 16:34:01 +0800 Subject: [PATCH 12/24] toc add cancel distribution job link MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: 童剑 <1045931706@qq.com> --- TOC.md | 1 + sql-statements/sql-statement-show-distribution-jobs.md | 3 ++- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/TOC.md b/TOC.md index 65f70b908d47..a5b208fc65fa 100644 --- a/TOC.md +++ b/TOC.md @@ -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) diff --git a/sql-statements/sql-statement-show-distribution-jobs.md b/sql-statements/sql-statement-show-distribution-jobs.md index fb1db4a43dd0..59ccf1a3939f 100644 --- a/sql-statements/sql-statement-show-distribution-jobs.md +++ b/sql-statements/sql-statement-show-distribution-jobs.md @@ -39,4 +39,5 @@ SHOW DISTRIBUTION JOBS; ## 另请参阅 - [`DISTRIBUTE TABLE`](/sql-statements/sql-statement-distribute-table.md) -- [`SHOW TABLE DISTRIBUTION`](/sql-statements/sql-statement-show-table-distribution.md) \ No newline at end of file +- [`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 From 8f08f706a826d2e258011b9741de2636963c2b56 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Mon, 9 Jun 2025 14:16:04 +0800 Subject: [PATCH 13/24] add a section for parameter descriptions --- .../sql-statement-cancel-distribution-job.md | 3 +-- .../sql-statement-distribute-table.md | 17 ++++++++++++----- 2 files changed, 13 insertions(+), 7 deletions(-) diff --git a/sql-statements/sql-statement-cancel-distribution-job.md b/sql-statements/sql-statement-cancel-distribution-job.md index 01e24503e39b..be5156eb7f77 100644 --- a/sql-statements/sql-statement-cancel-distribution-job.md +++ b/sql-statements/sql-statement-cancel-distribution-job.md @@ -5,8 +5,7 @@ summary: TiDB 数据库中 CANCEL DISTRIBUTION 的使用情况。 # CANCEL IMPORT -`CANCEL DISTRIBUTION` 语句用于取消 TiDB 中创建的 region 调度任务。 -。 +`CANCEL DISTRIBUTION` 语句用于取消 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 af98a2c8a581..ede35559326d 100644 --- a/sql-statements/sql-statement-distribute-table.md +++ b/sql-statements/sql-statement-distribute-table.md @@ -21,10 +21,16 @@ PartitionNameList ::= ``` -## 示例 +## 参数说明 + +通过 `DISTRIBUTE TABLE` 语句重新调度表中的 Region 时，你可以根据需求指定存储引擎（如 TiFlash 或 TiKV）以及不同的 Raft 角色（如 Leader、Learner、Voter）进行均衡。 + +- `RULE`：指定针对哪个 Raft 角色所在的 Region 进行均衡调度，可选值为 `leader-scatter`、`learner-scatter` 和 `learner-scatter`。 +- `ENGINE`：指定存储引擎，可选值为 `tikv` 和 `tiflash`。 +- `TIMEOUT`：指定打散操作的超时限制。 如果 PD 未在该时间内进行打散，打散任务将会自动退出。当未指定该参数时，默认值为 `30m`。 -通过 `DISTRIBUTE TABLE` 语句重新调度表中的 Region 时，你可以根据需求指定存储引擎（如 TiFlash 或 TiKV）以及不同的 Raft 角色（如 Leader、Learner、Voter）进行均衡打散操作。 -timeout: 如果 PD 在改指定时间内没有打散时会退出该任务，默认值为 30m。 + +## 示例 对表 `t1` 在 TiKV 上的 Leader 所在的 Region 重新进行均衡调度： @@ -41,7 +47,8 @@ DISTRIBUTE TABLE t1 RULE= `leader-scatter` ENGINE = tikv TIMEOUT=`1h` +---------+ ``` -对表 `t2` 在 Tiflash 上的 learner 所在的 Region 重新进行均衡调度 +对表 `t2` 在 Tiflash 上的 Learner 所在的 Region 重新进行均衡调度： + ```sql CREATE TABLE t2 (a INT); ... @@ -55,7 +62,7 @@ DISTRIBUTE table t2 RULE = `learner-scatter` ENGINE = tiflash; +---------+ ``` -对分区表 `t3· 的 `p1` 和 `p2` 分区在 TiKV 上的 peer 所在的 Region 重新进行均衡调度： +对分区表 `t3` 的 `p1` 和 `p2` 分区在 TiKV 上的 Peer 所在的 Region 重新进行均衡调度： ```sql CREATE TABLE t3 ( a INT, b INT, INDEX idx(b)) PARTITION BY RANGE( a ) ( From 418934e5f6e7fab07f2fffba7301dcc7fc097bd6 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Thu, 19 Jun 2025 09:48:18 +0800 Subject: [PATCH 14/24] Update sql-statements/sql-statement-cancel-distribution-job.md Co-authored-by: joey-yez <104608045+joey-yez@users.noreply.github.com> --- sql-statements/sql-statement-cancel-distribution-job.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sql-statements/sql-statement-cancel-distribution-job.md b/sql-statements/sql-statement-cancel-distribution-job.md index be5156eb7f77..b64bc0b5bbb4 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 summary: TiDB 数据库中 CANCEL DISTRIBUTION 的使用情况。 --- -# CANCEL IMPORT +# CANCEL DISTRIBUTION `CANCEL DISTRIBUTION` 语句用于取消 TiDB 中通过 [`DISTRIBUTE TABLE`](sql-statements/sql-statement-distribute-table.md) 语句创建的 Region 调度任务。 From 17547f506ccff25d3a8304d2e5559943f7e51e2f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=AB=A5=E5=89=91?= <1045931706@qq.com> Date: Thu, 19 Jun 2025 10:22:31 +0800 Subject: [PATCH 15/24] scatter MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: 童剑 <1045931706@qq.com> --- sql-statements/sql-statement-cancel-distribution-job.md | 2 +- sql-statements/sql-statement-cancel-import-job.md | 2 +- sql-statements/sql-statement-distribute-table.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/sql-statements/sql-statement-cancel-distribution-job.md b/sql-statements/sql-statement-cancel-distribution-job.md index b64bc0b5bbb4..de8e56e16af3 100644 --- a/sql-statements/sql-statement-cancel-distribution-job.md +++ b/sql-statements/sql-statement-cancel-distribution-job.md @@ -10,7 +10,7 @@ summary: TiDB 数据库中 CANCEL DISTRIBUTION 的使用情况。 ## 语法图 ```ebnf+diagram -CancelImportJobsStmt ::= +CancelDistributionJobsStmt ::= 'CANCEL' 'DISTRIBUTION' 'JOB' JobID ``` diff --git a/sql-statements/sql-statement-cancel-import-job.md b/sql-statements/sql-statement-cancel-import-job.md index c92efcad38a4..bf408bce81cc 100644 --- a/sql-statements/sql-statement-cancel-import-job.md +++ b/sql-statements/sql-statement-cancel-import-job.md @@ -14,7 +14,7 @@ summary: TiDB 数据库中 CANCEL IMPORT 的使用概况。 ## 语法图 ```ebnf+diagram -CancelImportJobsStmt ::= +CancelJobsStmt ::= 'CANCEL' 'IMPORT' 'JOB' JobID ``` diff --git a/sql-statements/sql-statement-distribute-table.md b/sql-statements/sql-statement-distribute-table.md index ede35559326d..65680543350c 100644 --- a/sql-statements/sql-statement-distribute-table.md +++ b/sql-statements/sql-statement-distribute-table.md @@ -25,7 +25,7 @@ PartitionNameList ::= 通过 `DISTRIBUTE TABLE` 语句重新调度表中的 Region 时，你可以根据需求指定存储引擎（如 TiFlash 或 TiKV）以及不同的 Raft 角色（如 Leader、Learner、Voter）进行均衡。 -- `RULE`：指定针对哪个 Raft 角色所在的 Region 进行均衡调度，可选值为 `leader-scatter`、`learner-scatter` 和 `learner-scatter`。 +- `RULE`：指定针对哪个 Raft 角色所在的 Region 进行均衡调度，可选值为 `leader-scatter`、`peer-scatter` 和 `learner-scatter`。 - `ENGINE`：指定存储引擎，可选值为 `tikv` 和 `tiflash`。 - `TIMEOUT`：指定打散操作的超时限制。 如果 PD 未在该时间内进行打散，打散任务将会自动退出。当未指定该参数时，默认值为 `30m`。 From e2f16f473e88cd179aa852035a89a71862c29ff8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=AB=A5=E5=89=91?= <1045931706@qq.com> Date: Fri, 20 Jun 2025 14:29:22 +0800 Subject: [PATCH 16/24] optimize parser MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: 童剑 <1045931706@qq.com> --- sql-statements/sql-statement-distribute-table.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/sql-statements/sql-statement-distribute-table.md b/sql-statements/sql-statement-distribute-table.md index 65680543350c..fe816b20ab77 100644 --- a/sql-statements/sql-statement-distribute-table.md +++ b/sql-statements/sql-statement-distribute-table.md @@ -37,7 +37,7 @@ PartitionNameList ::= ```sql CREATE TABLE t1 (a INT); ... -DISTRIBUTE TABLE t1 RULE= `leader-scatter` ENGINE = tikv TIMEOUT=`1h` +DISTRIBUTE TABLE t1 RULE= "leader-scatter" ENGINE = "tikv" TIMEOUT="1h" ``` ``` @@ -52,7 +52,7 @@ DISTRIBUTE TABLE t1 RULE= `leader-scatter` ENGINE = tikv TIMEOUT=`1h` ```sql CREATE TABLE t2 (a INT); ... -DISTRIBUTE table t2 RULE = `learner-scatter` ENGINE = tiflash; +DISTRIBUTE table t2 RULE = "learner-scatter" ENGINE = "tiflash"; ``` ``` @@ -70,7 +70,7 @@ CREATE TABLE t3 ( a INT, b INT, INDEX idx(b)) PARTITION BY RANGE( a ) ( PARTITION p2 VALUES LESS THAN (20000), PARTITION p3 VALUES LESS THAN (MAXVALUE) ); ... -DISTRIBUTE TABLE t3 PARTITION (p1, p2) RULE = `peer-scatter` ENGINE = tikv; +DISTRIBUTE TABLE t3 PARTITION (p1, p2) RULE = "peer-scatter" ENGINE = "tikv"; ``` ``` @@ -87,7 +87,7 @@ 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 = `leader-scatter` ENGINE=tiflash; +DISTRIBUTE TABLE t4 PARTITION (p1, p2) RULE = "leader-scatter" ENGINE="tiflash"; ``` ``` From 3ce509930dc1320258de9338d289ee8461a2a355 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Mon, 23 Jun 2025 10:12:45 +0800 Subject: [PATCH 17/24] add " " to wrap argument values --- sql-statements/sql-statement-distribute-table.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/sql-statements/sql-statement-distribute-table.md b/sql-statements/sql-statement-distribute-table.md index fe816b20ab77..c0ea6d38769a 100644 --- a/sql-statements/sql-statement-distribute-table.md +++ b/sql-statements/sql-statement-distribute-table.md @@ -25,9 +25,9 @@ PartitionNameList ::= 通过 `DISTRIBUTE TABLE` 语句重新调度表中的 Region 时，你可以根据需求指定存储引擎（如 TiFlash 或 TiKV）以及不同的 Raft 角色（如 Leader、Learner、Voter）进行均衡。 -- `RULE`：指定针对哪个 Raft 角色所在的 Region 进行均衡调度，可选值为 `leader-scatter`、`peer-scatter` 和 `learner-scatter`。 -- `ENGINE`：指定存储引擎，可选值为 `tikv` 和 `tiflash`。 -- `TIMEOUT`：指定打散操作的超时限制。 如果 PD 未在该时间内进行打散，打散任务将会自动退出。当未指定该参数时，默认值为 `30m`。 +- `RULE`：指定针对哪个 Raft 角色所在的 Region 进行均衡调度，可选值为 `"leader-scatter"`、`"peer-scatter"` 和 `"learner-scatter"`。 +- `ENGINE`：指定存储引擎，可选值为 `"tikv"` 和 `"tiflash"`。 +- `TIMEOUT`：指定打散操作的超时限制。 如果 PD 未在该时间内进行打散，打散任务将会自动退出。当未指定该参数时，默认值为 `"30m"`。 ## 示例 From 4e1386fb96d5efcfbb54f45b63e21a638b301e47 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Mon, 23 Jun 2025 11:34:17 +0800 Subject: [PATCH 18/24] minor format updates --- sql-statements/sql-statement-distribute-table.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sql-statements/sql-statement-distribute-table.md b/sql-statements/sql-statement-distribute-table.md index c0ea6d38769a..231a99b4f3d6 100644 --- a/sql-statements/sql-statement-distribute-table.md +++ b/sql-statements/sql-statement-distribute-table.md @@ -47,12 +47,12 @@ DISTRIBUTE TABLE t1 RULE= "leader-scatter" ENGINE = "tikv" TIMEOUT="1h" +---------+ ``` -对表 `t2` 在 Tiflash 上的 Learner 所在的 Region 重新进行均衡调度： +对表 `t2` 在 TiFlash 上的 Learner 所在的 Region 重新进行均衡调度： ```sql CREATE TABLE t2 (a INT); ... -DISTRIBUTE table t2 RULE = "learner-scatter" ENGINE = "tiflash"; +DISTRIBUTE TABLE t2 RULE = "learner-scatter" ENGINE = "tiflash"; ``` ``` From 0ae5d5cfe987bf837c1e5a02951742aad5f56d5d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=AB=A5=E5=89=91?= <1045931706@qq.com> Date: Wed, 25 Jun 2025 16:04:12 +0800 Subject: [PATCH 19/24] ---- MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: 童剑 <1045931706@qq.com> --- .../sql-statement-distribute-table.md | 36 ++++++++++--------- 1 file changed, 20 insertions(+), 16 deletions(-) diff --git a/sql-statements/sql-statement-distribute-table.md b/sql-statements/sql-statement-distribute-table.md index fe816b20ab77..4523a4efbb7a 100644 --- a/sql-statements/sql-statement-distribute-table.md +++ b/sql-statements/sql-statement-distribute-table.md @@ -41,10 +41,11 @@ DISTRIBUTE TABLE t1 RULE= "leader-scatter" ENGINE = "tikv" TIMEOUT="1h" ``` ``` -+---------+ -| JOB_ID | -100 -+---------+ ++--------+ +| JOB_ID | ++--------+ +| 100 | ++--------+ ``` 对表 `t2` 在 Tiflash 上的 Learner 所在的 Region 重新进行均衡调度： @@ -56,10 +57,11 @@ DISTRIBUTE table t2 RULE = "learner-scatter" ENGINE = "tiflash"; ``` ``` -+---------+ -| JOB_ID | -101 -+---------+ ++--------+ +| JOB_ID | ++--------+ +| 101 | ++--------+ ``` 对分区表 `t3` 的 `p1` 和 `p2` 分区在 TiKV 上的 Peer 所在的 Region 重新进行均衡调度： @@ -74,10 +76,11 @@ DISTRIBUTE TABLE t3 PARTITION (p1, p2) RULE = "peer-scatter" ENGINE = "tikv"; ``` ``` -+---------+ -| JOB_ID | -102 -+---------+ ++--------+ +| JOB_ID | ++--------+ +| 102 | ++--------+ ``` 对分区表 `t4` 的 `p1` 和 `p2` 分区在 TiKV 上的 Leader 所在的 Region 重新进行均衡调度： @@ -91,10 +94,11 @@ DISTRIBUTE TABLE t4 PARTITION (p1, p2) RULE = "leader-scatter" ENGINE="tiflash"; ``` ``` -+---------+ -| JOB_ID | -103 -+---------+ ++--------+ +| JOB_ID | ++--------+ +| 103 | ++--------+ ``` ## 注意事项 From f0545bec6d9527ae6a073cc3a1a0666477b2c7fd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=AB=A5=E5=89=91?= <1045931706@qq.com> Date: Fri, 27 Jun 2025 11:54:59 +0800 Subject: [PATCH 20/24] address comment MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: 童剑 <1045931706@qq.com> --- sql-statements/sql-statement-distribute-table.md | 7 +++++-- sql-statements/sql-statement-show-table-distribution.md | 4 ++-- 2 files changed, 7 insertions(+), 4 deletions(-) diff --git a/sql-statements/sql-statement-distribute-table.md b/sql-statements/sql-statement-distribute-table.md index 84f349c681fa..2395cdb7209b 100644 --- a/sql-statements/sql-statement-distribute-table.md +++ b/sql-statements/sql-statement-distribute-table.md @@ -4,6 +4,9 @@ summary: 介绍 TiDB 数据库中 DISTRIBUTE TABLE 的使用概况。 --- # DISTRIBUTE TABLE +> **警告：** +> +> 该功能目前为实验特性，不建议在生产环境中使用。该功能可能会在未事先通知的情况下发生变化或删除。如果发现 bug，请在 GitHub 上提 [issue](https://github.com/pingcap/tidb/issues) 反馈。 `DISTRIBUTE TABLE` 语句用于对指定表的 Region 进行重新打散和调度，以实现表级别的均衡分布。执行该语句可以防止个别 Region 集中在少数 TiFlash 或 TiKV 节点上，从而解决表中 Region 分布不均衡的问题。 @@ -83,14 +86,14 @@ DISTRIBUTE TABLE t3 PARTITION (p1, p2) RULE = "peer-scatter" ENGINE = "tikv"; +--------+ ``` -对分区表 `t4` 的 `p1` 和 `p2` 分区在 TiKV 上的 Leader 所在的 Region 重新进行均衡调度： +对分区表 `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 = "leader-scatter" ENGINE="tiflash"; +DISTRIBUTE TABLE t4 PARTITION (p1, p2) RULE = "learner-scatter" ENGINE="tiflash"; ``` ``` diff --git a/sql-statements/sql-statement-show-table-distribution.md b/sql-statements/sql-statement-show-table-distribution.md index 50d8a28c4e27..9fcec747b861 100644 --- a/sql-statements/sql-statement-show-table-distribution.md +++ b/sql-statements/sql-statement-show-table-distribution.md @@ -11,7 +11,7 @@ summary: 介绍 TiDB 数据库中 SHOW TABLE DISTRIBUTION 的使用概况。 ```ebnf+diagram ShowTableDistributionStmt ::= - "SHOW" "TABLE" "DISTRIBUTION" TableName + "SHOW" "TABLE" TableName "DISTRIBUTIONS" TableName ::= (SchemaName ".")? Identifier @@ -22,7 +22,7 @@ TableName ::= 显示当前表 `t1` 的 Region 分布情况： ```sql -SHOW TABLE DISTRIBUTION t1; +SHOW TABLE t1 DISTRIBUTIONS; ``` ``` From 7140d09933e7b958e3a0ab2df80a524ea53323db Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Fri, 27 Jun 2025 17:30:54 +0800 Subject: [PATCH 21/24] minor format updates --- sql-statements/sql-statement-distribute-table.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/sql-statements/sql-statement-distribute-table.md b/sql-statements/sql-statement-distribute-table.md index 2395cdb7209b..026ab97af1a6 100644 --- a/sql-statements/sql-statement-distribute-table.md +++ b/sql-statements/sql-statement-distribute-table.md @@ -3,6 +3,7 @@ title: DISTRIBUTE TABLE summary: 介绍 TiDB 数据库中 DISTRIBUTE TABLE 的使用概况。 --- + # DISTRIBUTE TABLE > **警告：** > @@ -86,7 +87,7 @@ DISTRIBUTE TABLE t3 PARTITION (p1, p2) RULE = "peer-scatter" ENGINE = "tikv"; +--------+ ``` -对分区表 `t4` 的 `p1` 和 `p2` 分区在 Tiflash 上的 Learner 所在的 Region 重新进行均衡调度： +对分区表 `t4` 的 `p1` 和 `p2` 分区在 TiFlash 上的 Learner 所在的 Region 重新进行均衡调度： ```sql CREATE TABLE t4 ( a INT, b INT, INDEX idx(b)) PARTITION BY RANGE( a ) ( From 1bfac7312193894d048ca3c14e3a8607dcfbc47a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=AB=A5=E5=89=91?= <1045931706@qq.com> Date: Mon, 30 Jun 2025 14:34:02 +0800 Subject: [PATCH 22/24] show distribution MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: 童剑 <1045931706@qq.com> --- .../sql-statement-show-table-distribution.md | 29 ++++++++++++++----- 1 file changed, 22 insertions(+), 7 deletions(-) diff --git a/sql-statements/sql-statement-show-table-distribution.md b/sql-statements/sql-statement-show-table-distribution.md index 9fcec747b861..3637b79fae2d 100644 --- a/sql-statements/sql-statement-show-table-distribution.md +++ b/sql-statements/sql-statement-show-table-distribution.md @@ -22,17 +22,32 @@ TableName ::= 显示当前表 `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; ``` ``` -+--------+----------+-------+----------------+--------+----------------+-----------+---------------------+---------------------+---------------------+ -| 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 | -+--------+----------+-------+----------------+--------+----------------+-----------+---------------------+---------------------+---------------------+ ++----------------+----------+------------+---------------------+-------------------+--------------------+-------------------+--------------------+--------------------------+-------------------------+--------------------------+------------------------+-----------------------+------------------------+ +| 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 兼容性 From 745d235932a8fcc8d62ba578206cecd02cf04081 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Mon, 30 Jun 2025 15:50:47 +0800 Subject: [PATCH 23/24] remove an empty line --- sql-statements/sql-statement-distribute-table.md | 1 - 1 file changed, 1 deletion(-) diff --git a/sql-statements/sql-statement-distribute-table.md b/sql-statements/sql-statement-distribute-table.md index 026ab97af1a6..2598eb771fe0 100644 --- a/sql-statements/sql-statement-distribute-table.md +++ b/sql-statements/sql-statement-distribute-table.md @@ -22,7 +22,6 @@ TableName ::= PartitionNameList ::= "PARTITION" "(" PartitionName ("," PartitionName)* ")" - ``` ## 参数说明 From 4bcab8ef2b1e66265b4699675558b2f7ce43d62c Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Mon, 30 Jun 2025 15:56:17 +0800 Subject: [PATCH 24/24] remove an empty line --- sql-statements/sql-statement-distribute-table.md | 1 - 1 file changed, 1 deletion(-) diff --git a/sql-statements/sql-statement-distribute-table.md b/sql-statements/sql-statement-distribute-table.md index 2598eb771fe0..23ce13abf0eb 100644 --- a/sql-statements/sql-statement-distribute-table.md +++ b/sql-statements/sql-statement-distribute-table.md @@ -3,7 +3,6 @@ title: DISTRIBUTE TABLE summary: 介绍 TiDB 数据库中 DISTRIBUTE TABLE 的使用概况。 --- - # DISTRIBUTE TABLE > **警告：** >