From 11978fb43756e140530fd838cb3d8b3e0431bd69 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Fri, 21 Feb 2025 09:26:52 +0800 Subject: [PATCH 01/16] Add temp.md --- temp.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 temp.md diff --git a/temp.md b/temp.md new file mode 100644 index 0000000000000..af27ff4986a7b --- /dev/null +++ b/temp.md @@ -0,0 +1 @@ +This is a test file. \ No newline at end of file From 302169d9324239ddff6fed277f856af42a734f8d Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Fri, 21 Feb 2025 09:26:56 +0800 Subject: [PATCH 02/16] Delete temp.md --- temp.md | 1 - 1 file changed, 1 deletion(-) delete mode 100644 temp.md diff --git a/temp.md b/temp.md deleted file mode 100644 index af27ff4986a7b..0000000000000 --- a/temp.md +++ /dev/null @@ -1 +0,0 @@ -This is a test file. \ No newline at end of file From 359ab111bfe2e2a62637e06d73413fc38886aeb9 Mon Sep 17 00:00:00 2001 From: qiancai Date: Fri, 21 Feb 2025 10:48:59 +0800 Subject: [PATCH 03/16] add translation --- TOC.md | 3 + .../sql-statement-distribute-table.md | 124 ++++++++++++++++++ .../sql-statement-show-distribution-jobs.md | 43 ++++++ .../sql-statement-show-table-distribution.md | 46 +++++++ 4 files changed, 216 insertions(+) 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 d7641e79c4ab4..2a08e0037c8d9 100644 --- a/TOC.md +++ b/TOC.md @@ -828,6 +828,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) @@ -892,6 +893,7 @@ - [`SHOW CREATE TABLE`](/sql-statements/sql-statement-show-create-table.md) - [`SHOW CREATE USER`](/sql-statements/sql-statement-show-create-user.md) - [`SHOW DATABASES`](/sql-statements/sql-statement-show-databases.md) + - [`SHOW DISTRIBUTION JOBS`](/sql-statements/sql-statement-show-distribution-jobs.md) - [`SHOW ENGINES`](/sql-statements/sql-statement-show-engines.md) - [`SHOW ERRORS`](/sql-statements/sql-statement-show-errors.md) - [`SHOW FIELDS FROM`](/sql-statements/sql-statement-show-fields-from.md) @@ -914,6 +916,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-distribute-table.md b/sql-statements/sql-statement-distribute-table.md new file mode 100644 index 0000000000000..5d461b064f244 --- /dev/null +++ b/sql-statements/sql-statement-distribute-table.md @@ -0,0 +1,124 @@ +--- +title: DISTRIBUTE TABLE +summary: An overview of the usage of DISTRIBUTE TABLE for the TiDB database. +--- + +# DISTRIBUTE TABLE + +The `DISTRIBUTE TABLE` statement redistributes and reschedules Regions of a specified table to achieve a balanced distribution at the table level. Executing this statement helps prevent Regions from being concentrated on a few TiFlash or TiKV nodes, addressing the issue of uneven region distribution in the table. + +## Syntax + +```ebnf+diagram +DistributeTableStmt ::= + "DISTRIBUTE" "TABLE" TableName PartitionNameList? EngineOption? RoleOption? + +TableName ::= + (SchemaName ".")? Identifier + +PartitionNameList ::= + "PARTITION" "(" PartitionName ("," PartitionName)* ")" + +EngineOption ::= + "ENGINE" Expression + +RoleOption ::= + "Role" Expression +``` + +## Examples + +When redistributing Regions using the `DISTRIBUTE TABLE` statement, you can specify the storage engine (such as TiFlash or TiKV) and different Raft roles (such as Leader, Learner, or Voter) for balanced distribution. + +Redistribute the Regions of the Leaders in the table `t1` on TiKV: + +```sql +CREATE TABLE t1 (a INT); +... +DISTRIBUTE TABLE t1 engine tikv role leader +``` + +``` ++---------+ +| JOB_ID | +100 ++---------+ +``` + +Redistribute the Regions of the Learners in the table `t2` on TiFlash: + +```sql +CREATE TABLE t2 (a INT); +... +DISTRIBUTE TABLE t2 ENGINE tiflash role learner; +``` + +``` ++---------+ +| JOB_ID | +101 ++---------+ +``` + +Redistribute the Regions of the Leaders in the table `t3`'s `p1` and `p2` partitions on TiKV: + +```sql +CREATE TABLE t3 (a INT); +... +DISTRIBUTE TABLE t3 PARTITION (p1, p2) ENGINE tikv role leader; +``` + +``` ++---------+ +| JOB_ID | +102 ++---------+ +``` + +Execute the [`SHOW DISTRIBUTION JOBS`](/sql-statements/sql-statement-show-distribution-jobs.md) statement to view all distribution jobs: + +```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 | ++---------+------------+------------+-----------------+------------+-----------+----------+-------------+---------------+ +``` + +Execute the [`SHOW TABLE DISTRIBUTION`](/sql-statements/sql-statement-show-table-distribution.md) statement to view the Region distribution of the table `t1`: + +```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 | ++---------+------------+----------------+----------+------------+-------------------+--------------------+-----------------+------------------+ +``` + +## Notes + +When you execute the `DISTRIBUTE TABLE` statement to redistribute Regions of a table, the Region distribution result might be affected by the PD hotspot scheduler. After the redistribution, the Region distribution of this table might become imbalanced again over time. + +## MySQL compatibility + +This statement is a TiDB extension to MySQL syntax. + +## See also + +- [`SHOW DISTRIBUTION JOBS`](/sql-statements/sql-statement-show-distribution-jobs.md) +- [`SHOW TABLE DISTRIBUTION`](/sql-statements/sql-statement-show-table-distribution.md) +- [`SHOW TABLE REGIONS`](/sql-statements/sql-statement-show-table-regions.md) \ 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 0000000000000..c4e888dd11e1a --- /dev/null +++ b/sql-statements/sql-statement-show-distribution-jobs.md @@ -0,0 +1,43 @@ +--- +title: SHOW DISTRIBUTION JOBS +summary: An overview of the usage of SHOW DISTRIBUTION JOBS for the TiDB database. +--- + +# SHOW DISTRIBUTION JOBS + +The `SHOW DISTRIBUTION JOBS` statement shows all current Region distribution jobs. + +## Syntax + +```ebnf+diagram +ShowDistributionJobsStmt ::= + "SHOW" "DISTRIBUTION" "JOBS" +``` + +## Examples + +Show all current Region distribution jobs: + +```sql +SHOW DISTRIBUTION JOBS; +``` + +``` ++---------+------------+------------+-----------------+------------+-----------+----------+-------------+---------------+ +| JOB_ID | 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 compatibility + +This statement is a TiDB extension to MySQL syntax. + +## See Also + +- [`DISTRIBUTE TABLE`](/sql-statements/sql-statement-distribute-table.md) +- [`SHOW TABLE DISTRIBUTION`](/sql-statements/sql-statement-show-table-distribution.md) \ 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 0000000000000..377042b8863a3 --- /dev/null +++ b/sql-statements/sql-statement-show-table-distribution.md @@ -0,0 +1,46 @@ +--- +title: SHOW TABLE DISTRIBUTION +summary: An overview of the usage of SHOW TABLE DISTRIBUTION for the TiDB database. +--- + +# SHOW TABLE DISTRIBUTION + +The `SHOW TABLE DISTRIBUTION` statement shows the Region distribution information for a specified table. + +## Syntax + +```ebnf+diagram +ShowTableDistributionStmt ::= + "SHOW" "TABLE" "DISTRIBUTION" TableName + +TableName ::= + (SchemaName ".")? Identifier +``` + +## Examples + +Show the Region distribution of the table `t1`: + +```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 compatibility + +This statement is a TiDB extension to MySQL syntax. + +## See Also + +- [`DISTRIBUTE TABLE`](/sql-statements/sql-statement-distribute-table.md) +- [`SHOW DISTRIBUTION JOBS`](/sql-statements/sql-statement-show-distribution-jobs.md) \ No newline at end of file From c0cbcf60aa39d332377c103bfac28fe7fa1d0b92 Mon Sep 17 00:00:00 2001 From: qiancai Date: Fri, 21 Feb 2025 13:47:25 +0800 Subject: [PATCH 04/16] minor case updates --- sql-statements/sql-statement-show-distribution-jobs.md | 2 +- sql-statements/sql-statement-show-table-distribution.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/sql-statements/sql-statement-show-distribution-jobs.md b/sql-statements/sql-statement-show-distribution-jobs.md index c4e888dd11e1a..5d6ee6612cf27 100644 --- a/sql-statements/sql-statement-show-distribution-jobs.md +++ b/sql-statements/sql-statement-show-distribution-jobs.md @@ -37,7 +37,7 @@ SHOW DISTRIBUTION JOBS; This statement is a TiDB extension to MySQL syntax. -## See Also +## See also - [`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 index 377042b8863a3..374264572848e 100644 --- a/sql-statements/sql-statement-show-table-distribution.md +++ b/sql-statements/sql-statement-show-table-distribution.md @@ -40,7 +40,7 @@ SHOW TABLE DISTRIBUTION t1; This statement is a TiDB extension to MySQL syntax. -## See Also +## See also - [`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 cf8e21039a02bdccdb913ace527c0e4b0217402f Mon Sep 17 00:00:00 2001 From: Test User Date: Mon, 23 Jun 2025 11:30:43 +0800 Subject: [PATCH 05/16] sync changes from the zh PR --- TOC.md | 1 + .../sql-statement-cancel-distribution-job.md | 38 +++++++++ .../sql-statement-distribute-table.md | 80 +++++++++---------- .../sql-statement-show-distribution-jobs.md | 18 ++--- .../sql-statement-show-table-distribution.md | 18 ++--- 5 files changed, 93 insertions(+), 62 deletions(-) create mode 100644 sql-statements/sql-statement-cancel-distribution-job.md diff --git a/TOC.md b/TOC.md index 2a08e0037c8d9..be0140b7f8051 100644 --- a/TOC.md +++ b/TOC.md @@ -811,6 +811,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-cancel-distribution-job.md b/sql-statements/sql-statement-cancel-distribution-job.md new file mode 100644 index 0000000000000..28643170bd3c7 --- /dev/null +++ b/sql-statements/sql-statement-cancel-distribution-job.md @@ -0,0 +1,38 @@ +--- +title: CANCEL DISTRIBUTION JOB +summary: An overview of the usage of CANCEL DISTRIBUTION JOB in TiDB. +--- + +# CANCEL DISTRIBUTION JOB + +The `CANCEL DISTRIBUTION JOB` statement is used to cancel a Region scheduling task created using the [`DISTRIBUTE TABLE`](/sql-statements/sql-statement-distribute-table.md) statement in TiDB. + +## Syntax diagram + +```ebnf+diagram +CancelDistributionJobsStmt ::= + 'CANCEL' 'DISTRIBUTION' 'JOB' JobID +``` + +## Examples + +The following example cancels the distribution job with ID `1`: + +```sql +CANCEL DISTRIBUTION JOB 1; +``` + +The output is as follows: + +``` +Query OK, 0 rows affected (0.01 sec) +``` + +## MySQL compatibility + +This statement is a TiDB extension to MySQL syntax. + +## See also + +* [`DISTRIBUTE TABLE`](/sql-statements/sql-statement-distribute-table.md) +* [`SHOW DISTRIBUTION JOBS`](/sql-statements/sql-statement-show-distribution-jobs.md) \ 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 5d461b064f244..2340c768e59f2 100644 --- a/sql-statements/sql-statement-distribute-table.md +++ b/sql-statements/sql-statement-distribute-table.md @@ -11,37 +11,38 @@ The `DISTRIBUTE TABLE` statement redistributes and reschedules Regions of a spec ```ebnf+diagram DistributeTableStmt ::= - "DISTRIBUTE" "TABLE" TableName PartitionNameList? EngineOption? RoleOption? + "DISTRIBUTE" "TABLE" TableName PartitionNameListOpt "RULE" EqOrAssignmentEq Identifier "ENGINE" EqOrAssignmentEq Identifier "TIMEOUT" EqOrAssignmentEq Identifier TableName ::= (SchemaName ".")? Identifier PartitionNameList ::= "PARTITION" "(" PartitionName ("," PartitionName)* ")" +``` -EngineOption ::= - "ENGINE" Expression +## Parameter description -RoleOption ::= - "Role" Expression -``` +When redistributing Regions in a table using the `DISTRIBUTE TABLE` statement, you can specify the storage engine (such as TiFlash or TiKV) and different Raft roles (such as Leader, Learner, or Voter) for balanced distribution. -## Examples +- `RULE`: specifies which Raft role's Region to balance and schedule. Optional values are `"leader-scatter"`, `"peer-scatter"`, and `"learner-scatter"`. +- `ENGINE`: specifies the storage engine. Optional values are `"tikv"` and `"tiflash"`. +- `TIMEOUT`: specifies the timeout limit for the scatter operation. If PD does not complete the scatter within this time, the scatter task will automatically exit. When this parameter is not specified, the default value is `"30m"`. -When redistributing Regions using the `DISTRIBUTE TABLE` statement, you can specify the storage engine (such as TiFlash or TiKV) and different Raft roles (such as Leader, Learner, or Voter) for balanced distribution. +## Examples Redistribute the Regions of the Leaders in the table `t1` on TiKV: ```sql CREATE TABLE t1 (a INT); ... -DISTRIBUTE TABLE t1 engine tikv role leader +DISTRIBUTE TABLE t1 RULE="leader-scatter" ENGINE="tikv" TIMEOUT="1h"; ``` ``` +---------+ | JOB_ID | -100 ++---------+ +| 100 | +---------+ ``` @@ -50,63 +51,53 @@ Redistribute the Regions of the Learners in the table `t2` on TiFlash: ```sql CREATE TABLE t2 (a INT); ... -DISTRIBUTE TABLE t2 ENGINE tiflash role learner; +DISTRIBUTE TABLE t2 RULE="learner-scatter" ENGINE="tiflash"; ``` ``` +---------+ | JOB_ID | -101 ++---------+ +| 101 | +---------+ ``` -Redistribute the Regions of the Leaders in the table `t3`'s `p1` and `p2` partitions on TiKV: +Redistribute the Regions of the Peers in the table `t3`'s `p1` and `p2` partitions on TiKV: ```sql -CREATE TABLE t3 (a INT); +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) ENGINE tikv role leader; +DISTRIBUTE TABLE t3 PARTITION (p1, p2) RULE="peer-scatter" ENGINE="tikv"; ``` ``` +---------+ | JOB_ID | -102 ++---------+ +| 102 | +---------+ ``` -Execute the [`SHOW DISTRIBUTION JOBS`](/sql-statements/sql-statement-show-distribution-jobs.md) statement to view all distribution jobs: - -```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 | -+---------+------------+------------+-----------------+------------+-----------+----------+-------------+---------------+ -``` - -Execute the [`SHOW TABLE DISTRIBUTION`](/sql-statements/sql-statement-show-table-distribution.md) statement to view the Region distribution of the table `t1`: +Redistribute the Regions of the Leaders in the table `t4`'s `p1` and `p2` partitions on TiFlash: ```sql -SHOW TABLE DISTRIBUTION t1; +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"; ``` ``` -+---------+------------+----------------+----------+------------+-------------------+--------------------+-----------------+------------------+ -| 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 | ++---------+ +| 103 | ++---------+ ``` ## Notes @@ -121,4 +112,5 @@ This statement is a TiDB extension to MySQL syntax. - [`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 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 index 5d6ee6612cf27..ba19872b3b6b9 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 compatibility @@ -40,4 +39,5 @@ This statement is a TiDB extension to MySQL syntax. ## See also - [`DISTRIBUTE TABLE`](/sql-statements/sql-statement-distribute-table.md) -- [`SHOW TABLE DISTRIBUTION`](/sql-statements/sql-statement-show-table-distribution.md) \ 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 diff --git a/sql-statements/sql-statement-show-table-distribution.md b/sql-statements/sql-statement-show-table-distribution.md index 374264572848e..fdf762f25faf3 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 compatibility @@ -43,4 +42,5 @@ This statement is a TiDB extension to MySQL syntax. ## See also - [`DISTRIBUTE TABLE`](/sql-statements/sql-statement-distribute-table.md) -- [`SHOW DISTRIBUTION JOBS`](/sql-statements/sql-statement-show-distribution-jobs.md) \ No newline at end of file +- [`SHOW DISTRIBUTION JOBS`](/sql-statements/sql-statement-show-distribution-jobs.md) +- [`CANCEL DISTRIBUTION JOB`](/sql-statements/sql-statement-cancel-distribution-job.md) \ No newline at end of file From 41eada7dee4a41f9389ed82d499039e0f61611aa Mon Sep 17 00:00:00 2001 From: Test User Date: Mon, 30 Jun 2025 15:50:19 +0800 Subject: [PATCH 06/16] sync latest changes from the zh PR --- .../sql-statement-distribute-table.md | 49 ++++++++++--------- .../sql-statement-show-table-distribution.md | 33 +++++++++---- 2 files changed, 51 insertions(+), 31 deletions(-) diff --git a/sql-statements/sql-statement-distribute-table.md b/sql-statements/sql-statement-distribute-table.md index 2340c768e59f2..80cfc0a9e670d 100644 --- a/sql-statements/sql-statement-distribute-table.md +++ b/sql-statements/sql-statement-distribute-table.md @@ -5,6 +5,11 @@ summary: An overview of the usage of DISTRIBUTE TABLE for the TiDB database. # DISTRIBUTE TABLE +> **Warning:** +> +> - This feature is experimental. It is not recommended that you use it in the production environment. This feature might be changed or removed without prior notice. If you find a bug, you can report an [issue](https://github.com/pingcap/tidb/issues) on GitHub. +> - This feature is not available on [TiDB Cloud Serverless](https://docs.pingcap.com/tidbcloud/select-cluster-tier#tidb-cloud-serverless) clusters. + The `DISTRIBUTE TABLE` statement redistributes and reschedules Regions of a specified table to achieve a balanced distribution at the table level. Executing this statement helps prevent Regions from being concentrated on a few TiFlash or TiKV nodes, addressing the issue of uneven region distribution in the table. ## Syntax @@ -39,11 +44,11 @@ DISTRIBUTE TABLE t1 RULE="leader-scatter" ENGINE="tikv" TIMEOUT="1h"; ``` ``` -+---------+ -| JOB_ID | -+---------+ -| 100 | -+---------+ ++--------+ +| JOB_ID | ++--------+ +| 100 | ++--------+ ``` Redistribute the Regions of the Learners in the table `t2` on TiFlash: @@ -55,11 +60,11 @@ DISTRIBUTE TABLE t2 RULE="learner-scatter" ENGINE="tiflash"; ``` ``` -+---------+ -| JOB_ID | -+---------+ -| 101 | -+---------+ ++--------+ +| JOB_ID | ++--------+ +| 101 | ++--------+ ``` Redistribute the Regions of the Peers in the table `t3`'s `p1` and `p2` partitions on TiKV: @@ -74,14 +79,14 @@ DISTRIBUTE TABLE t3 PARTITION (p1, p2) RULE="peer-scatter" ENGINE="tikv"; ``` ``` -+---------+ -| JOB_ID | -+---------+ -| 102 | -+---------+ ++--------+ +| JOB_ID | ++--------+ +| 102 | ++--------+ ``` -Redistribute the Regions of the Leaders in the table `t4`'s `p1` and `p2` partitions on TiFlash: +Redistribute the Regions of the Learner in the table `t4`'s `p1` and `p2` partitions on TiFlash: ```sql CREATE TABLE t4 ( a INT, b INT, INDEX idx(b)) PARTITION BY RANGE( a ) ( @@ -89,15 +94,15 @@ CREATE TABLE t4 ( 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 t4 PARTITION (p1, p2) RULE="leader-scatter" ENGINE="tiflash"; +DISTRIBUTE TABLE t4 PARTITION (p1, p2) RULE="learner-scatter" ENGINE="tiflash"; ``` ``` -+---------+ -| JOB_ID | -+---------+ -| 103 | -+---------+ ++--------+ +| JOB_ID | ++--------+ +| 103 | ++--------+ ``` ## Notes diff --git a/sql-statements/sql-statement-show-table-distribution.md b/sql-statements/sql-statement-show-table-distribution.md index fdf762f25faf3..0fa23591d0f7b 100644 --- a/sql-statements/sql-statement-show-table-distribution.md +++ b/sql-statements/sql-statement-show-table-distribution.md @@ -11,7 +11,7 @@ The `SHOW TABLE DISTRIBUTION` statement shows the Region distribution informatio ```ebnf+diagram ShowTableDistributionStmt ::= - "SHOW" "TABLE" "DISTRIBUTION" TableName + "SHOW" "TABLE" TableName "DISTRIBUTIONS" TableName ::= (SchemaName ".")? Identifier @@ -22,17 +22,32 @@ TableName ::= Show the Region distribution of the table `t1`: ```sql -SHOW TABLE DISTRIBUTION t1; +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 compatibility From 2f74d485505d64e350f729d7e16f121d4f9d6319 Mon Sep 17 00:00:00 2001 From: Test User Date: Mon, 21 Jul 2025 15:51:27 +0800 Subject: [PATCH 07/16] add four comments about the support 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, 8 insertions(+) diff --git a/sql-statements/sql-statement-cancel-distribution-job.md b/sql-statements/sql-statement-cancel-distribution-job.md index 28643170bd3c7..b4d40e98a4f31 100644 --- a/sql-statements/sql-statement-cancel-distribution-job.md +++ b/sql-statements/sql-statement-cancel-distribution-job.md @@ -5,6 +5,8 @@ summary: An overview of the usage of CANCEL DISTRIBUTION JOB in TiDB. # CANCEL DISTRIBUTION JOB + + The `CANCEL DISTRIBUTION JOB` statement is used to cancel a Region scheduling task created using the [`DISTRIBUTE TABLE`](/sql-statements/sql-statement-distribute-table.md) statement in TiDB. ## Syntax diagram diff --git a/sql-statements/sql-statement-distribute-table.md b/sql-statements/sql-statement-distribute-table.md index 80cfc0a9e670d..40cd8cdd40243 100644 --- a/sql-statements/sql-statement-distribute-table.md +++ b/sql-statements/sql-statement-distribute-table.md @@ -5,6 +5,8 @@ summary: An overview of the usage of DISTRIBUTE TABLE for the TiDB database. # DISTRIBUTE TABLE + + > **Warning:** > > - This feature is experimental. It is not recommended that you use it in the production environment. This feature might be changed or removed without prior notice. If you find a bug, you can report an [issue](https://github.com/pingcap/tidb/issues) on GitHub. diff --git a/sql-statements/sql-statement-show-distribution-jobs.md b/sql-statements/sql-statement-show-distribution-jobs.md index ba19872b3b6b9..a5cf575eef99e 100644 --- a/sql-statements/sql-statement-show-distribution-jobs.md +++ b/sql-statements/sql-statement-show-distribution-jobs.md @@ -5,6 +5,8 @@ summary: An overview of the usage of SHOW DISTRIBUTION JOBS for the TiDB databas # SHOW DISTRIBUTION JOBS + + The `SHOW DISTRIBUTION JOBS` statement shows all current Region distribution jobs. ## Syntax diff --git a/sql-statements/sql-statement-show-table-distribution.md b/sql-statements/sql-statement-show-table-distribution.md index 0fa23591d0f7b..6973aef576a2a 100644 --- a/sql-statements/sql-statement-show-table-distribution.md +++ b/sql-statements/sql-statement-show-table-distribution.md @@ -5,6 +5,8 @@ summary: An overview of the usage of SHOW TABLE DISTRIBUTION for the TiDB databa # SHOW TABLE DISTRIBUTION + + The `SHOW TABLE DISTRIBUTION` statement shows the Region distribution information for a specified table. ## Syntax From 40cae4661b7052dd0b2bf6f9f040c9031522526d Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Tue, 12 Aug 2025 14:27:17 +0800 Subject: [PATCH 08/16] Apply suggestions from code review Co-authored-by: Aolin --- .../sql-statement-cancel-distribution-job.md | 2 +- sql-statements/sql-statement-distribute-table.md | 12 ++++++------ .../sql-statement-show-table-distribution.md | 2 +- 3 files changed, 8 insertions(+), 8 deletions(-) diff --git a/sql-statements/sql-statement-cancel-distribution-job.md b/sql-statements/sql-statement-cancel-distribution-job.md index b4d40e98a4f31..939878c1bb9a6 100644 --- a/sql-statements/sql-statement-cancel-distribution-job.md +++ b/sql-statements/sql-statement-cancel-distribution-job.md @@ -9,7 +9,7 @@ summary: An overview of the usage of CANCEL DISTRIBUTION JOB in TiDB. The `CANCEL DISTRIBUTION JOB` statement is used to cancel a Region scheduling task created using the [`DISTRIBUTE TABLE`](/sql-statements/sql-statement-distribute-table.md) statement in TiDB. -## Syntax diagram +## Synopsis ```ebnf+diagram CancelDistributionJobsStmt ::= diff --git a/sql-statements/sql-statement-distribute-table.md b/sql-statements/sql-statement-distribute-table.md index 40cd8cdd40243..eee7491235448 100644 --- a/sql-statements/sql-statement-distribute-table.md +++ b/sql-statements/sql-statement-distribute-table.md @@ -10,11 +10,11 @@ summary: An overview of the usage of DISTRIBUTE TABLE for the TiDB database. > **Warning:** > > - This feature is experimental. It is not recommended that you use it in the production environment. This feature might be changed or removed without prior notice. If you find a bug, you can report an [issue](https://github.com/pingcap/tidb/issues) on GitHub. -> - This feature is not available on [TiDB Cloud Serverless](https://docs.pingcap.com/tidbcloud/select-cluster-tier#tidb-cloud-serverless) clusters. +> - This feature is not available on [{{{ .starter }}}](https://docs.pingcap.com/tidbcloud/select-cluster-tier#tidb-cloud-serverless) clusters. The `DISTRIBUTE TABLE` statement redistributes and reschedules Regions of a specified table to achieve a balanced distribution at the table level. Executing this statement helps prevent Regions from being concentrated on a few TiFlash or TiKV nodes, addressing the issue of uneven region distribution in the table. -## Syntax +## Synopsis ```ebnf+diagram DistributeTableStmt ::= @@ -42,7 +42,7 @@ Redistribute the Regions of the Leaders in the table `t1` on TiKV: ```sql CREATE TABLE t1 (a INT); ... -DISTRIBUTE TABLE t1 RULE="leader-scatter" ENGINE="tikv" TIMEOUT="1h"; +DISTRIBUTE TABLE t1 RULE = "leader-scatter" ENGINE = "tikv" TIMEOUT = "1h"; ``` ``` @@ -58,7 +58,7 @@ Redistribute the Regions of the Learners in the table `t2` on TiFlash: ```sql CREATE TABLE t2 (a INT); ... -DISTRIBUTE TABLE t2 RULE="learner-scatter" ENGINE="tiflash"; +DISTRIBUTE TABLE t2 RULE = "learner-scatter" ENGINE = "tiflash"; ``` ``` @@ -77,7 +77,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"; ``` ``` @@ -96,7 +96,7 @@ CREATE TABLE t4 ( 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 t4 PARTITION (p1, p2) RULE="learner-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 6973aef576a2a..096cd5a5b9e2f 100644 --- a/sql-statements/sql-statement-show-table-distribution.md +++ b/sql-statements/sql-statement-show-table-distribution.md @@ -9,7 +9,7 @@ summary: An overview of the usage of SHOW TABLE DISTRIBUTION for the TiDB databa The `SHOW TABLE DISTRIBUTION` statement shows the Region distribution information for a specified table. -## Syntax +## Synopsis ```ebnf+diagram ShowTableDistributionStmt ::= From 2b0d76296a799e74bc3acd9bd4302987252d2783 Mon Sep 17 00:00:00 2001 From: Test User Date: Tue, 12 Aug 2025 16:04:40 +0800 Subject: [PATCH 09/16] use to wrap the version support info --- sql-statements/sql-statement-cancel-distribution-job.md | 6 +++++- sql-statements/sql-statement-distribute-table.md | 2 +- sql-statements/sql-statement-show-distribution-jobs.md | 6 +++++- sql-statements/sql-statement-show-table-distribution.md | 6 +++++- 4 files changed, 16 insertions(+), 4 deletions(-) diff --git a/sql-statements/sql-statement-cancel-distribution-job.md b/sql-statements/sql-statement-cancel-distribution-job.md index 939878c1bb9a6..6fdda3041889b 100644 --- a/sql-statements/sql-statement-cancel-distribution-job.md +++ b/sql-statements/sql-statement-cancel-distribution-job.md @@ -5,10 +5,14 @@ summary: An overview of the usage of CANCEL DISTRIBUTION JOB in TiDB. # CANCEL DISTRIBUTION JOB - +New in v9.0.0 The `CANCEL DISTRIBUTION JOB` statement is used to cancel a Region scheduling task created using the [`DISTRIBUTE TABLE`](/sql-statements/sql-statement-distribute-table.md) statement in TiDB. +> **Note:** +> +> This feature is not available on [{{{ .starter }}}](https://docs.pingcap.com/tidbcloud/select-cluster-tier#tidb-cloud-serverless) clusters. + ## Synopsis ```ebnf+diagram diff --git a/sql-statements/sql-statement-distribute-table.md b/sql-statements/sql-statement-distribute-table.md index eee7491235448..928293f9c7bf3 100644 --- a/sql-statements/sql-statement-distribute-table.md +++ b/sql-statements/sql-statement-distribute-table.md @@ -5,7 +5,7 @@ summary: An overview of the usage of DISTRIBUTE TABLE for the TiDB database. # DISTRIBUTE TABLE - +New in v9.0.0 > **Warning:** > diff --git a/sql-statements/sql-statement-show-distribution-jobs.md b/sql-statements/sql-statement-show-distribution-jobs.md index a5cf575eef99e..b6d7c648415da 100644 --- a/sql-statements/sql-statement-show-distribution-jobs.md +++ b/sql-statements/sql-statement-show-distribution-jobs.md @@ -5,10 +5,14 @@ summary: An overview of the usage of SHOW DISTRIBUTION JOBS for the TiDB databas # SHOW DISTRIBUTION JOBS - +New in v9.0.0 The `SHOW DISTRIBUTION JOBS` statement shows all current Region distribution jobs. +> **Note:** +> +> This feature is not available on [{{{ .starter }}}](https://docs.pingcap.com/tidbcloud/select-cluster-tier#tidb-cloud-serverless) clusters. + ## Syntax ```ebnf+diagram diff --git a/sql-statements/sql-statement-show-table-distribution.md b/sql-statements/sql-statement-show-table-distribution.md index 096cd5a5b9e2f..836ce6bf5a476 100644 --- a/sql-statements/sql-statement-show-table-distribution.md +++ b/sql-statements/sql-statement-show-table-distribution.md @@ -5,10 +5,14 @@ summary: An overview of the usage of SHOW TABLE DISTRIBUTION for the TiDB databa # SHOW TABLE DISTRIBUTION - +New in v9.0.0 The `SHOW TABLE DISTRIBUTION` statement shows the Region distribution information for a specified table. +> **Note:** +> +> This feature is not available on [{{{ .starter }}}](https://docs.pingcap.com/tidbcloud/select-cluster-tier#tidb-cloud-serverless) clusters. + ## Synopsis ```ebnf+diagram From d48f7bc57ee32243a8024ea7a26c8c35375f3ec5 Mon Sep 17 00:00:00 2001 From: Test User Date: Wed, 20 Aug 2025 14:45:26 +0800 Subject: [PATCH 10/16] show the version span in the doc title --- sql-statements/sql-statement-cancel-distribution-job.md | 4 +--- sql-statements/sql-statement-distribute-table.md | 4 +--- sql-statements/sql-statement-show-distribution-jobs.md | 4 +--- sql-statements/sql-statement-show-table-distribution.md | 4 +--- 4 files changed, 4 insertions(+), 12 deletions(-) diff --git a/sql-statements/sql-statement-cancel-distribution-job.md b/sql-statements/sql-statement-cancel-distribution-job.md index 6fdda3041889b..411af510140a4 100644 --- a/sql-statements/sql-statement-cancel-distribution-job.md +++ b/sql-statements/sql-statement-cancel-distribution-job.md @@ -3,9 +3,7 @@ title: CANCEL DISTRIBUTION JOB summary: An overview of the usage of CANCEL DISTRIBUTION JOB in TiDB. --- -# CANCEL DISTRIBUTION JOB - -New in v9.0.0 +# CANCEL DISTRIBUTION JOB New in v9.0.0 The `CANCEL DISTRIBUTION JOB` statement is used to cancel a Region scheduling task created using the [`DISTRIBUTE TABLE`](/sql-statements/sql-statement-distribute-table.md) statement in TiDB. diff --git a/sql-statements/sql-statement-distribute-table.md b/sql-statements/sql-statement-distribute-table.md index 928293f9c7bf3..f5dcab9d33d31 100644 --- a/sql-statements/sql-statement-distribute-table.md +++ b/sql-statements/sql-statement-distribute-table.md @@ -3,9 +3,7 @@ title: DISTRIBUTE TABLE summary: An overview of the usage of DISTRIBUTE TABLE for the TiDB database. --- -# DISTRIBUTE TABLE - -New in v9.0.0 +# DISTRIBUTE TABLE New in v9.0.0 > **Warning:** > diff --git a/sql-statements/sql-statement-show-distribution-jobs.md b/sql-statements/sql-statement-show-distribution-jobs.md index b6d7c648415da..8a6809248bd32 100644 --- a/sql-statements/sql-statement-show-distribution-jobs.md +++ b/sql-statements/sql-statement-show-distribution-jobs.md @@ -3,9 +3,7 @@ title: SHOW DISTRIBUTION JOBS summary: An overview of the usage of SHOW DISTRIBUTION JOBS for the TiDB database. --- -# SHOW DISTRIBUTION JOBS - -New in v9.0.0 +# SHOW DISTRIBUTION JOBS New in v9.0.0 The `SHOW DISTRIBUTION JOBS` statement shows all current Region distribution jobs. diff --git a/sql-statements/sql-statement-show-table-distribution.md b/sql-statements/sql-statement-show-table-distribution.md index 836ce6bf5a476..7bbd8e3ed70fd 100644 --- a/sql-statements/sql-statement-show-table-distribution.md +++ b/sql-statements/sql-statement-show-table-distribution.md @@ -3,9 +3,7 @@ title: SHOW TABLE DISTRIBUTION summary: An overview of the usage of SHOW TABLE DISTRIBUTION for the TiDB database. --- -# SHOW TABLE DISTRIBUTION - -New in v9.0.0 +# SHOW TABLE DISTRIBUTION New in v9.0.0 The `SHOW TABLE DISTRIBUTION` statement shows the Region distribution information for a specified table. From 5875a3c1d71affffc321ac1be7462620b70ba0c3 Mon Sep 17 00:00:00 2001 From: Test User Date: Wed, 20 Aug 2025 15:13:19 +0800 Subject: [PATCH 11/16] add essential info --- 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 411af510140a4..52a6c4b143568 100644 --- a/sql-statements/sql-statement-cancel-distribution-job.md +++ b/sql-statements/sql-statement-cancel-distribution-job.md @@ -9,7 +9,7 @@ The `CANCEL DISTRIBUTION JOB` statement is used to cancel a Region scheduling ta > **Note:** > -> This feature is not available on [{{{ .starter }}}](https://docs.pingcap.com/tidbcloud/select-cluster-tier#tidb-cloud-serverless) clusters. +> This feature is not available on [{{{ .starter }}}](https://docs.pingcap.com/tidbcloud/select-cluster-tier#tidb-cloud-serverless) and [{{{ .essential }}}](https://docs.pingcap.com/tidbcloud/select-cluster-tier#essential) clusters. ## Synopsis diff --git a/sql-statements/sql-statement-distribute-table.md b/sql-statements/sql-statement-distribute-table.md index f5dcab9d33d31..2edc47dae745a 100644 --- a/sql-statements/sql-statement-distribute-table.md +++ b/sql-statements/sql-statement-distribute-table.md @@ -8,7 +8,7 @@ summary: An overview of the usage of DISTRIBUTE TABLE for the TiDB database. > **Warning:** > > - This feature is experimental. It is not recommended that you use it in the production environment. This feature might be changed or removed without prior notice. If you find a bug, you can report an [issue](https://github.com/pingcap/tidb/issues) on GitHub. -> - This feature is not available on [{{{ .starter }}}](https://docs.pingcap.com/tidbcloud/select-cluster-tier#tidb-cloud-serverless) clusters. +> - This feature is not available on [{{{ .starter }}}](https://docs.pingcap.com/tidbcloud/select-cluster-tier#tidb-cloud-serverless) and [{{{ .essential }}}](https://docs.pingcap.com/tidbcloud/select-cluster-tier#essential) clusters. The `DISTRIBUTE TABLE` statement redistributes and reschedules Regions of a specified table to achieve a balanced distribution at the table level. Executing this statement helps prevent Regions from being concentrated on a few TiFlash or TiKV nodes, addressing the issue of uneven region distribution in the table. diff --git a/sql-statements/sql-statement-show-distribution-jobs.md b/sql-statements/sql-statement-show-distribution-jobs.md index 8a6809248bd32..912b433893e30 100644 --- a/sql-statements/sql-statement-show-distribution-jobs.md +++ b/sql-statements/sql-statement-show-distribution-jobs.md @@ -9,7 +9,7 @@ The `SHOW DISTRIBUTION JOBS` statement shows all current Region distribution job > **Note:** > -> This feature is not available on [{{{ .starter }}}](https://docs.pingcap.com/tidbcloud/select-cluster-tier#tidb-cloud-serverless) clusters. +> This feature is not available on [{{{ .starter }}}](https://docs.pingcap.com/tidbcloud/select-cluster-tier#tidb-cloud-serverless) and [{{{ .essential }}}](https://docs.pingcap.com/tidbcloud/select-cluster-tier#essential) clusters. ## Syntax diff --git a/sql-statements/sql-statement-show-table-distribution.md b/sql-statements/sql-statement-show-table-distribution.md index 7bbd8e3ed70fd..d603b821cc684 100644 --- a/sql-statements/sql-statement-show-table-distribution.md +++ b/sql-statements/sql-statement-show-table-distribution.md @@ -9,7 +9,7 @@ The `SHOW TABLE DISTRIBUTION` statement shows the Region distribution informatio > **Note:** > -> This feature is not available on [{{{ .starter }}}](https://docs.pingcap.com/tidbcloud/select-cluster-tier#tidb-cloud-serverless) clusters. +> This feature is not available on [{{{ .starter }}}](https://docs.pingcap.com/tidbcloud/select-cluster-tier#tidb-cloud-serverless) and [{{{ .essential }}}](https://docs.pingcap.com/tidbcloud/select-cluster-tier#essential) clusters. ## Synopsis From c6efef73dfeb1acfdfee80e60273ec413eb16a79 Mon Sep 17 00:00:00 2001 From: Test User Date: Wed, 20 Aug 2025 15:20:08 +0800 Subject: [PATCH 12/16] add starter/essential support info to custom content as starter and essential are still at 7.5.x --- .../sql-statement-cancel-distribution-job.md | 4 ++++ sql-statements/sql-statement-distribute-table.md | 11 +++++++++-- .../sql-statement-show-distribution-jobs.md | 4 ++++ .../sql-statement-show-table-distribution.md | 4 ++++ 4 files changed, 21 insertions(+), 2 deletions(-) diff --git a/sql-statements/sql-statement-cancel-distribution-job.md b/sql-statements/sql-statement-cancel-distribution-job.md index 52a6c4b143568..b9c2666dfeb6f 100644 --- a/sql-statements/sql-statement-cancel-distribution-job.md +++ b/sql-statements/sql-statement-cancel-distribution-job.md @@ -7,10 +7,14 @@ summary: An overview of the usage of CANCEL DISTRIBUTION JOB in TiDB. The `CANCEL DISTRIBUTION JOB` statement is used to cancel a Region scheduling task created using the [`DISTRIBUTE TABLE`](/sql-statements/sql-statement-distribute-table.md) statement in TiDB. + + > **Note:** > > This feature is not available on [{{{ .starter }}}](https://docs.pingcap.com/tidbcloud/select-cluster-tier#tidb-cloud-serverless) and [{{{ .essential }}}](https://docs.pingcap.com/tidbcloud/select-cluster-tier#essential) clusters. + + ## Synopsis ```ebnf+diagram diff --git a/sql-statements/sql-statement-distribute-table.md b/sql-statements/sql-statement-distribute-table.md index 2edc47dae745a..14697fcef4b47 100644 --- a/sql-statements/sql-statement-distribute-table.md +++ b/sql-statements/sql-statement-distribute-table.md @@ -7,8 +7,15 @@ summary: An overview of the usage of DISTRIBUTE TABLE for the TiDB database. > **Warning:** > -> - This feature is experimental. It is not recommended that you use it in the production environment. This feature might be changed or removed without prior notice. If you find a bug, you can report an [issue](https://github.com/pingcap/tidb/issues) on GitHub. -> - This feature is not available on [{{{ .starter }}}](https://docs.pingcap.com/tidbcloud/select-cluster-tier#tidb-cloud-serverless) and [{{{ .essential }}}](https://docs.pingcap.com/tidbcloud/select-cluster-tier#essential) clusters. +> This feature is experimental. It is not recommended that you use it in the production environment. This feature might be changed or removed without prior notice. If you find a bug, you can report an [issue](https://github.com/pingcap/tidb/issues) on GitHub. + + + +> **Note:** +> +> This feature is not available on [{{{ .starter }}}](https://docs.pingcap.com/tidbcloud/select-cluster-tier#tidb-cloud-serverless) and [{{{ .essential }}}](https://docs.pingcap.com/tidbcloud/select-cluster-tier#essential) clusters. + + The `DISTRIBUTE TABLE` statement redistributes and reschedules Regions of a specified table to achieve a balanced distribution at the table level. Executing this statement helps prevent Regions from being concentrated on a few TiFlash or TiKV nodes, addressing the issue of uneven region distribution in the table. diff --git a/sql-statements/sql-statement-show-distribution-jobs.md b/sql-statements/sql-statement-show-distribution-jobs.md index 912b433893e30..e9529a7e783f0 100644 --- a/sql-statements/sql-statement-show-distribution-jobs.md +++ b/sql-statements/sql-statement-show-distribution-jobs.md @@ -7,10 +7,14 @@ summary: An overview of the usage of SHOW DISTRIBUTION JOBS for the TiDB databas The `SHOW DISTRIBUTION JOBS` statement shows all current Region distribution jobs. + + > **Note:** > > This feature is not available on [{{{ .starter }}}](https://docs.pingcap.com/tidbcloud/select-cluster-tier#tidb-cloud-serverless) and [{{{ .essential }}}](https://docs.pingcap.com/tidbcloud/select-cluster-tier#essential) clusters. + + ## Syntax ```ebnf+diagram diff --git a/sql-statements/sql-statement-show-table-distribution.md b/sql-statements/sql-statement-show-table-distribution.md index d603b821cc684..ae60521af7760 100644 --- a/sql-statements/sql-statement-show-table-distribution.md +++ b/sql-statements/sql-statement-show-table-distribution.md @@ -7,10 +7,14 @@ summary: An overview of the usage of SHOW TABLE DISTRIBUTION for the TiDB databa The `SHOW TABLE DISTRIBUTION` statement shows the Region distribution information for a specified table. + + > **Note:** > > This feature is not available on [{{{ .starter }}}](https://docs.pingcap.com/tidbcloud/select-cluster-tier#tidb-cloud-serverless) and [{{{ .essential }}}](https://docs.pingcap.com/tidbcloud/select-cluster-tier#essential) clusters. + + ## Synopsis ```ebnf+diagram From 6ffdecef4c043f36352273f9f199216efced1842 Mon Sep 17 00:00:00 2001 From: qiancai Date: Sat, 11 Oct 2025 14:18:10 +0800 Subject: [PATCH 13/16] update 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 b9c2666dfeb6f..5cc3f28161b77 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: An overview of the usage of CANCEL DISTRIBUTION JOB in TiDB. --- -# CANCEL DISTRIBUTION JOB New in v9.0.0 +# CANCEL DISTRIBUTION JOB New in v8.5.4 The `CANCEL DISTRIBUTION JOB` statement is used to cancel a Region scheduling task created using the [`DISTRIBUTE TABLE`](/sql-statements/sql-statement-distribute-table.md) statement in TiDB. diff --git a/sql-statements/sql-statement-distribute-table.md b/sql-statements/sql-statement-distribute-table.md index 14697fcef4b47..89ff8803eb34a 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: An overview of the usage of DISTRIBUTE TABLE for the TiDB database. --- -# DISTRIBUTE TABLE New in v9.0.0 +# DISTRIBUTE TABLE New in v8.5.4 > **Warning:** > diff --git a/sql-statements/sql-statement-show-distribution-jobs.md b/sql-statements/sql-statement-show-distribution-jobs.md index e9529a7e783f0..a3580908026cf 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: An overview of the usage of SHOW DISTRIBUTION JOBS for the TiDB database. --- -# SHOW DISTRIBUTION JOBS New in v9.0.0 +# SHOW DISTRIBUTION JOBS New in v8.5.4 The `SHOW DISTRIBUTION JOBS` statement shows all current Region distribution jobs. diff --git a/sql-statements/sql-statement-show-table-distribution.md b/sql-statements/sql-statement-show-table-distribution.md index ae60521af7760..9e83ca36c12b8 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: An overview of the usage of SHOW TABLE DISTRIBUTION for the TiDB database. --- -# SHOW TABLE DISTRIBUTION New in v9.0.0 +# SHOW TABLE DISTRIBUTION New in v8.5.4 The `SHOW TABLE DISTRIBUTION` statement shows the Region distribution information for a specified table. From a0e12fcb284da1841e9e2b0544f0e7635a5652be Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Sat, 11 Oct 2025 15:12:33 +0800 Subject: [PATCH 14/16] Apply suggestions from code review Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> --- sql-statements/sql-statement-show-distribution-jobs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sql-statements/sql-statement-show-distribution-jobs.md b/sql-statements/sql-statement-show-distribution-jobs.md index a3580908026cf..f7d1ec48f0ad0 100644 --- a/sql-statements/sql-statement-show-distribution-jobs.md +++ b/sql-statements/sql-statement-show-distribution-jobs.md @@ -15,7 +15,7 @@ The `SHOW DISTRIBUTION JOBS` statement shows all current Region distribution job -## Syntax +## Synopsis ```ebnf+diagram ShowDistributionJobsStmt ::= From 61af83345ff40d3e370bb9d8481f39b1c8a07e5e Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Sat, 11 Oct 2025 15:28:55 +0800 Subject: [PATCH 15/16] Apply suggestions from code review Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> --- 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 9e83ca36c12b8..489a2194b71f2 100644 --- a/sql-statements/sql-statement-show-table-distribution.md +++ b/sql-statements/sql-statement-show-table-distribution.md @@ -27,7 +27,7 @@ TableName ::= ## Examples -Show the Region distribution of the table `t1`: +Show the Region distribution of the table `t`: ```sql CREATE TABLE `t` ( @@ -37,8 +37,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; ``` ``` From a38d1259b620d6bc86d67e230243a8c0250f3251 Mon Sep 17 00:00:00 2001 From: qiancai Date: Sat, 11 Oct 2025 15:46:10 +0800 Subject: [PATCH 16/16] add the distribution related docs to the toc file for dedicated clusters --- TOC-tidb-cloud.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/TOC-tidb-cloud.md b/TOC-tidb-cloud.md index 97b29b3dbc0ce..6bb640a12b9c1 100644 --- a/TOC-tidb-cloud.md +++ b/TOC-tidb-cloud.md @@ -428,6 +428,7 @@ - [`BACKUP`](/sql-statements/sql-statement-backup.md) - [`BATCH`](/sql-statements/sql-statement-batch.md) - [`BEGIN`](/sql-statements/sql-statement-begin.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 [GLOBAL|SESSION] BINDING`](/sql-statements/sql-statement-create-binding.md) @@ -445,6 +446,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 [GLOBAL|SESSION] BINDING`](/sql-statements/sql-statement-drop-binding.md) - [`DROP DATABASE`](/sql-statements/sql-statement-drop-database.md) @@ -508,6 +510,7 @@ - [`SHOW CREATE TABLE`](/sql-statements/sql-statement-show-create-table.md) - [`SHOW CREATE USER`](/sql-statements/sql-statement-show-create-user.md) - [`SHOW DATABASES`](/sql-statements/sql-statement-show-databases.md) + - [`SHOW DISTRIBUTION JOBS`](/sql-statements/sql-statement-show-distribution-jobs.md) - [`SHOW ENGINES`](/sql-statements/sql-statement-show-engines.md) - [`SHOW ERRORS`](/sql-statements/sql-statement-show-errors.md) - [`SHOW FIELDS FROM`](/sql-statements/sql-statement-show-fields-from.md) @@ -530,6 +533,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)