diff --git a/TOC.md b/TOC.md index 853182eeccaa..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) @@ -788,6 +789,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 +854,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 +877,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..de8e56e16af3 --- /dev/null +++ b/sql-statements/sql-statement-cancel-distribution-job.md @@ -0,0 +1,38 @@ +--- +title: CANCEL DISTRIBUTION +summary: TiDB 数据库中 CANCEL DISTRIBUTION 的使用情况。 +--- + +# CANCEL DISTRIBUTION + +`CANCEL DISTRIBUTION` 语句用于取消 TiDB 中通过 [`DISTRIBUTE TABLE`](sql-statements/sql-statement-distribute-table.md) 语句创建的 Region 调度任务。 + +## 语法图 + +```ebnf+diagram +CancelDistributionJobsStmt ::= + 'CANCEL' 'DISTRIBUTION' 'JOB' JobID +``` + +## 示例 + +下面示例取消 ID 为 1 的导入任务： + +```sql +CANCEL DISTRIBUTION JOB 1; +``` + +输出结果如下： + +``` +Query OK, 0 rows affected (0.01 sec) +``` + +## MySQL 兼容性 + +该语句是 TiDB 对 MySQL 语法的扩展。 + +## 另请参阅 + +* [`DISTRIBUTE TABLE`](/sql-statements/sql-statement-distribute-table.md) +* [`SHOW DISTRIBUTION JOB`](/sql-statements/sql-statement-show-distribution-jobs.md) diff --git a/sql-statements/sql-statement-distribute-table.md b/sql-statements/sql-statement-distribute-table.md new file mode 100644 index 000000000000..23ce13abf0eb --- /dev/null +++ b/sql-statements/sql-statement-distribute-table.md @@ -0,0 +1,119 @@ +--- +title: DISTRIBUTE TABLE +summary: 介绍 TiDB 数据库中 DISTRIBUTE TABLE 的使用概况。 +--- + +# DISTRIBUTE TABLE +> **警告：** +> +> 该功能目前为实验特性，不建议在生产环境中使用。该功能可能会在未事先通知的情况下发生变化或删除。如果发现 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 JOBS`] (/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..59ccf1a3939f --- /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 | 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..3637b79fae2d --- /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 + +`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