From 5c3d4845deaa0818b597e862afe0e68e551dcaf5 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Fri, 21 Feb 2025 09:26:52 +0800 Subject: [PATCH 01/12] 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 bbcbf928e27fedafa2b4864ed5a8b106aa5b9863 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Fri, 21 Feb 2025 09:26:56 +0800 Subject: [PATCH 02/12] 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 daac87b81f4ee1dea417a2e16acf7b0ea0e18dc2 Mon Sep 17 00:00:00 2001 From: qiancai Date: Fri, 21 Feb 2025 10:48:59 +0800 Subject: [PATCH 03/12] 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 4d83edad7447c..b52ea08a96671 100644 --- a/TOC.md +++ b/TOC.md @@ -789,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) @@ -853,6 +854,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) @@ -875,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-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 cd201ede6e291ee6b62228bf6dd77a0f68b75878 Mon Sep 17 00:00:00 2001 From: qiancai Date: Fri, 21 Feb 2025 13:47:25 +0800 Subject: [PATCH 04/12] 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 b2b20a67dd81435661b3544694ab1b1094211cb7 Mon Sep 17 00:00:00 2001 From: Test User Date: Mon, 23 Jun 2025 11:30:43 +0800 Subject: [PATCH 05/12] 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 b52ea08a96671..a737083dcc684 100644 --- a/TOC.md +++ b/TOC.md @@ -772,6 +772,7 @@ - [`BATCH`](/sql-statements/sql-statement-batch.md) - [`BEGIN`](/sql-statements/sql-statement-begin.md) - [`CALIBRATE RESOURCE`](/sql-statements/sql-statement-calibrate-resource.md) + - [`CANCEL DISTRIBUTION JOB`](/sql-statements/sql-statement-cancel-distribution-job.md) - [`CANCEL IMPORT JOB`](/sql-statements/sql-statement-cancel-import-job.md) - [`COMMIT`](/sql-statements/sql-statement-commit.md) - [`CREATE BINDING`](/sql-statements/sql-statement-create-binding.md) 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 fe45c768d40c6ca17e232202dbecf42b6340104c Mon Sep 17 00:00:00 2001 From: Test User Date: Mon, 30 Jun 2025 15:50:19 +0800 Subject: [PATCH 06/12] 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 c07da5b61c989db7008cf32b832ebc47718912f9 Mon Sep 17 00:00:00 2001 From: Test User Date: Mon, 21 Jul 2025 15:51:27 +0800 Subject: [PATCH 07/12] 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 e2eaefbde05cca1ed31f21fdcd572dad602dfde0 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Tue, 12 Aug 2025 14:27:17 +0800 Subject: [PATCH 08/12] 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 ef108a36c7ee3b03067f2159e3e23214a48b8be4 Mon Sep 17 00:00:00 2001 From: Test User Date: Tue, 12 Aug 2025 16:04:40 +0800 Subject: [PATCH 09/12] 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 cede814c584b78a08a285477eb90a2dbc40656ae Mon Sep 17 00:00:00 2001 From: Test User Date: Wed, 20 Aug 2025 14:45:26 +0800 Subject: [PATCH 10/12] 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 53d5450ea843439e6b3f179acdcf349ad57d817d Mon Sep 17 00:00:00 2001 From: Test User Date: Wed, 20 Aug 2025 15:13:19 +0800 Subject: [PATCH 11/12] 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 5fa5203672ee98ca24b64ff62e0fc71b1cf7a34a Mon Sep 17 00:00:00 2001 From: Test User Date: Wed, 20 Aug 2025 15:20:08 +0800 Subject: [PATCH 12/12] 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