pingcap · ti-chi-bot · Sep 8, 2025 · Feb 21, 2025 · Feb 21, 2025 · Feb 21, 2025
diff --git 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)
       - [`CANCEL TRAFFIC JOBS`](/sql-statements/sql-statement-cancel-traffic-jobs.md)
       - [`COMMIT`](/sql-statements/sql-statement-commit.md)
@@ -829,6 +830,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)
@@ -893,6 +895,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)
@@ -915,6 +918,7 @@
       - [`SHOW STATS_META`](/sql-statements/sql-statement-show-stats-meta.md)
       - [`SHOW STATS_TOPN`](/sql-statements/sql-statement-show-stats-topn.md)
       - [`SHOW STATUS`](/sql-statements/sql-statement-show-status.md)
+      - [`SHOW TABLE DISTRIBUTION`](/sql-statements/sql-statement-show-table-distribution.md)
       - [`SHOW TABLE NEXT_ROW_ID`](/sql-statements/sql-statement-show-table-next-rowid.md)
       - [`SHOW TABLE REGIONS`](/sql-statements/sql-statement-show-table-regions.md)
       - [`SHOW TABLE STATUS`](/sql-statements/sql-statement-show-table-status.md)

diff --git a/sql-statements/sql-statement-cancel-distribution-job.md b/sql-statements/sql-statement-cancel-distribution-job.md
@@ -0,0 +1,46 @@
+---
+title: CANCEL DISTRIBUTION JOB
+summary: An overview of the usage of CANCEL DISTRIBUTION JOB in TiDB.
+---
+
+# CANCEL DISTRIBUTION JOB <span class="version-mark">New in v9.0.0</span>
+
+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.
+
+<CustomContent platform="tidb-cloud">
+
+> **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.
+
+</CustomContent>
+
+## Synopsis
+
+```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)
diff --git a/sql-statements/sql-statement-distribute-table.md b/sql-statements/sql-statement-distribute-table.md
@@ -0,0 +1,128 @@
+---
+title: DISTRIBUTE TABLE
+summary: An overview of the usage of DISTRIBUTE TABLE for the TiDB database.
+---
+
+# DISTRIBUTE TABLE <span class="version-mark">New in v9.0.0</span>
+
+> **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.
+
+<CustomContent platform="tidb-cloud">
+
+> **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.
+
+</CustomContent>
+
+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.
+
+## Synopsis
+
+```ebnf+diagram
+DistributeTableStmt ::=
+    "DISTRIBUTE" "TABLE" TableName PartitionNameListOpt "RULE" EqOrAssignmentEq Identifier "ENGINE" EqOrAssignmentEq Identifier "TIMEOUT" EqOrAssignmentEq Identifier
+
+TableName ::=
+    (SchemaName ".")? Identifier
+
+PartitionNameList ::=
+    "PARTITION" "(" PartitionName ("," PartitionName)* ")"
+```
+
+## Parameter description
+
+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.
+
+- `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"`.
+
+## Examples
+
+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";
+```
+
+```
++--------+
+| JOB_ID |
++--------+
+|    100 |
++--------+
+```
+
+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";
+```
+
+```
++--------+
+| JOB_ID |
++--------+
+|    101 |
++--------+
+```
+
+Redistribute the Regions of the Peers in the table `t3`'s `p1` and `p2` partitions on TiKV:
+
+```sql
+CREATE TABLE t3 ( a INT, b INT, INDEX idx(b)) PARTITION BY RANGE( a ) (
+    PARTITION p1 VALUES LESS THAN (10000),
+    PARTITION p2 VALUES LESS THAN (20000),
+    PARTITION p3 VALUES LESS THAN (MAXVALUE) );
+...
+DISTRIBUTE TABLE t3 PARTITION (p1, p2) RULE = "peer-scatter" ENGINE = "tikv";
+```
+
+```
++--------+
+| JOB_ID |
++--------+
+|    102 |
++--------+
+```
+
+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 ) (
+    PARTITION p1 VALUES LESS THAN (10000),
+    PARTITION p2 VALUES LESS THAN (20000),
+    PARTITION p3 VALUES LESS THAN (MAXVALUE) );
+...
+DISTRIBUTE TABLE t4 PARTITION (p1, p2) RULE = "learner-scatter" ENGINE="tiflash";
+```
+
+```
++--------+
+| JOB_ID |
++--------+
+|    103 |
++--------+
+```
+
+## 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)
+- [`CANCEL DISTRIBUTION JOB`](/sql-statements/sql-statement-cancel-distribution-job.md)
diff --git a/sql-statements/sql-statement-show-distribution-jobs.md b/sql-statements/sql-statement-show-distribution-jobs.md
@@ -0,0 +1,51 @@
+---
+title: SHOW DISTRIBUTION JOBS
+summary: An overview of the usage of SHOW DISTRIBUTION JOBS for the TiDB database.
+---
+
+# SHOW DISTRIBUTION JOBS <span class="version-mark">New in v9.0.0</span>
+
+The `SHOW DISTRIBUTION JOBS` statement shows all current Region distribution jobs.
+
+<CustomContent platform="tidb-cloud">
+
+> **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.
+
+</CustomContent>
+
+## Syntax
+
+```ebnf+diagram
+ShowDistributionJobsStmt ::=
+    "SHOW" "DISTRIBUTION" "JOBS"
+```
+
+## Examples
+
+Show all current Region distribution jobs:
+
+```sql
+SHOW DISTRIBUTION JOBS;
+```
+
+```
++--------+----------+-------+----------------+--------+----------------+-----------+---------------------+---------------------+---------------------+
+| Job_ID | Database | Table | Partition_List | Engine | Rule           | Status    | Create_Time         | Start_Time          | Finish_Time         |
++--------+----------+-------+----------------+--------+----------------+-----------+---------------------+---------------------+---------------------+
+|    100 | test     | t1    | NULL           | tikv   | leader-scatter | finished  | 2025-04-24 16:09:55 | 2025-04-24 16:09:55 | 2025-04-24 17:09:59 |
+|    101 | test     | t2    | NULL           | tikv   | learner-scatter| cancelled | 2025-05-08 15:33:29 | 2025-05-08 15:33:29 | 2025-05-08 15:33:37 |
+|    102 | test     | t5    | p1,p2          | tikv   | peer-scatter   | cancelled | 2025-05-21 15:32:44 | 2025-05-21 15:32:47 | 2025-05-21 15:32:47 |
++--------+----------+-------+----------------+--------+----------------+-----------+---------------------+---------------------+---------------------+
+```
+
+## MySQL 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)
+- [`CANCEL DISTRIBUTION JOB`](/sql-statements/sql-statement-cancel-distribution-job.md)
diff --git a/sql-statements/sql-statement-show-table-distribution.md b/sql-statements/sql-statement-show-table-distribution.md
@@ -0,0 +1,69 @@
+---
+title: SHOW TABLE DISTRIBUTION
+summary: An overview of the usage of SHOW TABLE DISTRIBUTION for the TiDB database.
+---
+
+# SHOW TABLE DISTRIBUTION <span class="version-mark">New in v9.0.0</span>
+
+The `SHOW TABLE DISTRIBUTION` statement shows the Region distribution information for a specified table.
+
+<CustomContent platform="tidb-cloud">
+
+> **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.
+
+</CustomContent>
+
+## Synopsis
+
+```ebnf+diagram
+ShowTableDistributionStmt ::=
+    "SHOW" "TABLE" TableName "DISTRIBUTIONS"
+
+TableName ::=
+    (SchemaName ".")? Identifier
+```
+
+## Examples
+
+Show the Region distribution of the table `t1`:
+
+```sql
+CREATE TABLE `t` (
+  `a` int DEFAULT NULL,
+  `b` int DEFAULT NULL,
+  KEY `idx` (`b`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin 
+PARTITION BY RANGE (`a`)
+(PARTITION `p1` VALUES LESS THAN (10000),
+ PARTITION `p2` VALUES LESS THAN (MAXVALUE)) |
+SHOW TABLE t1 DISTRIBUTIONS;
+```
+
+```
++----------------+----------+------------+---------------------+-------------------+--------------------+-------------------+--------------------+--------------------------+-------------------------+--------------------------+------------------------+-----------------------+------------------------+
+| PARTITION_NAME | STORE_ID | STORE_TYPE | REGION_LEADER_COUNT | REGION_PEER_COUNT | REGION_WRITE_BYTES | REGION_WRITE_KEYS | REGION_WRITE_QUERY | REGION_LEADER_READ_BYTES | REGION_LEADER_READ_KEYS | REGION_LEADER_READ_QUERY | REGION_PEER_READ_BYTES | REGION_PEER_READ_KEYS | REGION_PEER_READ_QUERY |
++----------------+----------+------------+---------------------+-------------------+--------------------+-------------------+--------------------+--------------------------+-------------------------+--------------------------+------------------------+-----------------------+------------------------+
+| p1             |        1 | tikv       |                   0 |                 0 |                  0 |                 0 |                  0 |                        0 |                       0 |                        0 |                      0 |                     0 |                      0 |
+| p1             |       15 | tikv       |                   0 |                 0 |                  0 |                 0 |                  0 |                        0 |                       0 |                        0 |                      0 |                     0 |                      0 |
+| p1             |        4 | tikv       |                   1 |                 1 |                  0 |                 0 |                  0 |                        0 |                       0 |                        0 |                      0 |                     0 |                      0 |
+| p1             |        5 | tikv       |                   0 |                 1 |                  0 |                 0 |                  0 |                        0 |                       0 |                        0 |                      0 |                     0 |                      0 |
+| p1             |        6 | tikv       |                   0 |                 1 |                  0 |                 0 |                  0 |                        0 |                       0 |                        0 |                      0 |                     0 |                      0 |
+| p2             |        1 | tikv       |                   0 |                 0 |                  0 |                 0 |                  0 |                        0 |                       0 |                        0 |                      0 |                     0 |                      0 |
+| p2             |       15 | tikv       |                   0 |                 0 |                  0 |                 0 |                  0 |                        0 |                       0 |                        0 |                      0 |                     0 |                      0 |
+| p2             |        4 | tikv       |                   0 |                 1 |                  0 |                 0 |                  0 |                        0 |                       0 |                        0 |                      0 |                     0 |                      0 |
+| p2             |        5 | tikv       |                   1 |                 1 |                  0 |                 0 |                  0 |                        0 |                       0 |                        0 |                      0 |                     0 |                      0 |
+| p2             |        6 | tikv       |                   0 |                 1 |                  0 |                 0 |                  0 |                        0 |                       0 |                        0 |                      0 |                     0 |                      0 |
++----------------+----------+------------+---------------------+-------------------+--------------------+-------------------+--------------------+--------------------------+-------------------------+--------------------------+------------------------+-----------------------+------------------------+
+```
+
+## MySQL 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)
+- [`CANCEL DISTRIBUTION JOB`](/sql-statements/sql-statement-cancel-distribution-job.md)