cherry pick pingcap#4311 to release-4.0

Signed-off-by: ti-srebot <ti-srebot@pingcap.com>
ti-srebot · Aug 26, 2020 · 530d2bd · 530d2bd
1 parent 9e9ad66
commit 530d2bd
Showing 1 changed file with 58 additions and 28 deletions.
diff --git a/sql-statements/sql-statement-show-table-regions.md b/sql-statements/sql-statement-show-table-regions.md
@@ -58,61 +58,87 @@ SHOW TABLE [table_name] INDEX [index_name] REGIONS [WhereClauseOptional];
 
 ## 示例
 
+创建一个示例表，并在若干 Region 中填充足够的数据量：
+
 {{< copyable "sql" >}}
 
 ```sql
-create table t (id int key,name varchar(50), index (name));
-```
-
-```
-Query OK, 0 rows affected
-```
-
-默认新建表后会单独 split 出一个 Region 来存放该表的数据，开始时行数据和索引数据都会写到这个 Region。
+CREATE TABLE t1 (
+ id INT NOT NULL PRIMARY KEY auto_increment,
+ b INT NOT NULL,
+ pad1 VARBINARY(1024),
+ pad2 VARBINARY(1024),
+ pad3 VARBINARY(1024)
+);
+INSERT INTO t1 SELECT NULL, FLOOR(RAND()*1000), RANDOM_BYTES(1024), RANDOM_BYTES(1024), RANDOM_BYTES(1024) FROM dual;
+INSERT INTO t1 SELECT NULL, FLOOR(RAND()*1000), RANDOM_BYTES(1024), RANDOM_BYTES(1024), RANDOM_BYTES(1024) FROM t1 a JOIN t1 b JOIN t1 c LIMIT 10000;
+INSERT INTO t1 SELECT NULL, FLOOR(RAND()*1000), RANDOM_BYTES(1024), RANDOM_BYTES(1024), RANDOM_BYTES(1024) FROM t1 a JOIN t1 b JOIN t1 c LIMIT 10000;
+INSERT INTO t1 SELECT NULL, FLOOR(RAND()*1000), RANDOM_BYTES(1024), RANDOM_BYTES(1024), RANDOM_BYTES(1024) FROM t1 a JOIN t1 b JOIN t1 c LIMIT 10000;
+INSERT INTO t1 SELECT NULL, FLOOR(RAND()*1000), RANDOM_BYTES(1024), RANDOM_BYTES(1024), RANDOM_BYTES(1024) FROM t1 a JOIN t1 b JOIN t1 c LIMIT 10000;
+INSERT INTO t1 SELECT NULL, FLOOR(RAND()*1000), RANDOM_BYTES(1024), RANDOM_BYTES(1024), RANDOM_BYTES(1024) FROM t1 a JOIN t1 b JOIN t1 c LIMIT 10000;
+INSERT INTO t1 SELECT NULL, FLOOR(RAND()*1000), RANDOM_BYTES(1024), RANDOM_BYTES(1024), RANDOM_BYTES(1024) FROM t1 a JOIN t1 b JOIN t1 c LIMIT 10000;
+INSERT INTO t1 SELECT NULL, FLOOR(RAND()*1000), RANDOM_BYTES(1024), RANDOM_BYTES(1024), RANDOM_BYTES(1024) FROM t1 a JOIN t1 b JOIN t1 c LIMIT 10000;
+INSERT INTO t1 SELECT NULL, FLOOR(RAND()*1000), RANDOM_BYTES(1024), RANDOM_BYTES(1024), RANDOM_BYTES(1024) FROM t1 a JOIN t1 b JOIN t1 c LIMIT 10000;
+INSERT INTO t1 SELECT NULL, FLOOR(RAND()*1000), RANDOM_BYTES(1024), RANDOM_BYTES(1024), RANDOM_BYTES(1024) FROM t1 a JOIN t1 b JOIN t1 c LIMIT 10000;
+INSERT INTO t1 SELECT NULL, FLOOR(RAND()*1000), RANDOM_BYTES(1024), RANDOM_BYTES(1024), RANDOM_BYTES(1024) FROM t1 a JOIN t1 b JOIN t1 c LIMIT 10000;
+INSERT INTO t1 SELECT NULL, FLOOR(RAND()*1000), RANDOM_BYTES(1024), RANDOM_BYTES(1024), RANDOM_BYTES(1024) FROM t1 a JOIN t1 b JOIN t1 c LIMIT 10000;
+SELECT SLEEP(5);
+SHOW TABLE t1 REGIONS;
+```
+
+结果显示示例表被切分成多个 Regions。`REGION_ID`、`START_KEY` 和 `END_KEY` 可能不完全匹配：
 
 {{< copyable "sql" >}}
 
 ```sql
-show table t regions;
-```
-
-```
-+-----------+-----------+---------+-----------+-----------------+-----------+------------+---------------+------------+----------------------+------------------+
-| REGION_ID | START_KEY | END_KEY | LEADER_ID | LEADER_STORE_ID | PEERS     | SCATTERING | WRITTEN_BYTES | READ_BYTES | APPROXIMATE_SIZE(MB) | APPROXIMATE_KEYS |
-+-----------+-----------+---------+-----------+-----------------+-----------+------------+---------------+------------+----------------------+------------------+
-| 3         | t_43_     |         | 73        | 9               | 5, 73, 93 | 0          | 35            | 0          | 1                    | 0                |
-+-----------+-----------+---------+-----------+-----------------+-----------+------------+---------------+------------+----------------------+------------------+
-1 row in set
+SHOW TABLE t1 REGIONS;
++-----------+--------------+--------------+-----------+-----------------+-------+------------+---------------+------------+----------------------+------------------+
+| REGION_ID | START_KEY    | END_KEY      | LEADER_ID | LEADER_STORE_ID | PEERS | SCATTERING | WRITTEN_BYTES | READ_BYTES | APPROXIMATE_SIZE(MB) | APPROXIMATE_KEYS |
++-----------+--------------+--------------+-----------+-----------------+-------+------------+---------------+------------+----------------------+------------------+
+|        94 | t_75_        | t_75_r_31717 |        95 |               1 | 95    |          0 |             0 |          0 |                  112 |           207465 |
+|        96 | t_75_r_31717 | t_75_r_63434 |        97 |               1 | 97    |          0 |             0 |          0 |                   97 |                0 |
+|         2 | t_75_r_63434 |              |         3 |               1 | 3     |          0 |     269323514 |   66346110 |                  245 |           162020 |
++-----------+--------------+--------------+-----------+-----------------+-------+------------+---------------+------------+----------------------+------------------+
+3 rows in set (0.00 sec)
 ```
 
 解释：
 
-- 上面 START_KEY 列的值 t_43_ 中，t 是表数据的前缀，43 是表 t 的 table ID。
-- END_KEY 列的值为空（""）表示无穷大。
+上面 START_KEY 列的值 `t_75_r_31717` 和 END_KEY 列的值 `t_75_r_63434` 表示主键在 `31717` 和 `63434` 之间的数据存储在该 Region 中。`t_75_` 是前缀，表示这是表格 (`t`) 的 Region，`75` 是表格的内部 ID。若 `START_KEY` 或 `END_KEY` 的一对键值为空，分别表示负无穷大或正无穷大。
 
-用 `SPLIT TABLE REGION` 语法切分行数据的 Region，下面语法把表 t 的行数据切分成 5 个 Region。
+TiDB 会根据需要自动重新平衡 Regions。建议使用 `SPLIT TABLE REGION` 语句手动进行平衡：
 
 {{< copyable "sql" >}}
 
 ```sql
-split table t between (0) and (100000) regions 5;
+SPLIT TABLE t1 BETWEEN (31717) AND (63434) REGIONS 2;
 ```
 
 ```
 +--------------------+----------------------+
 | TOTAL_SPLIT_REGION | SCATTER_FINISH_RATIO |
 +--------------------+----------------------+
-| 5                  | 1.0                  |
+|                  1 |                    1 |
 +--------------------+----------------------+
-1 row in set
+1 row in set (42.34 sec)
+SHOW TABLE t1 REGIONS;
++-----------+--------------+--------------+-----------+-----------------+-------+------------+---------------+------------+----------------------+------------------+
+| REGION_ID | START_KEY    | END_KEY      | LEADER_ID | LEADER_STORE_ID | PEERS | SCATTERING | WRITTEN_BYTES | READ_BYTES | APPROXIMATE_SIZE(MB) | APPROXIMATE_KEYS |
++-----------+--------------+--------------+-----------+-----------------+-------+------------+---------------+------------+----------------------+------------------+
+|        94 | t_75_        | t_75_r_31717 |        95 |               1 | 95    |          0 |             0 |          0 |                  112 |           207465 |
+|        98 | t_75_r_31717 | t_75_r_47575 |        99 |               1 | 99    |          0 |          1325 |          0 |                   53 |            12052 |
+|        96 | t_75_r_47575 | t_75_r_63434 |        97 |               1 | 97    |          0 |          1526 |          0 |                   48 |                0 |
+|         2 | t_75_r_63434 |              |         3 |               1 | 3     |          0 |             0 |   55752049 |                   60 |                0 |
++-----------+--------------+--------------+-----------+-----------------+-------+------------+---------------+------------+----------------------+------------------+
+4 rows in set (0.00 sec)
 ```
 
-解释：
+上面的输出结果显示 Region 96 被切分，并创建一个新的 Region 98。切分操作不会影响表中的其他 Region。输出结果同样证实：
 
-- TOTAL_SPLIT_REGION 表示新切的 region 数量，这是新切了 5 个 region.
-- SCATTER_FINISH_RATIO 表示新切的 region 的打散成功率，1.0 表示都已经打散了。
+- TOTAL_SPLIT_REGION 表示新切的 Region 数量。以上示例新切了 1 个 Region。
+- SCATTER_FINISH_RATIO 表示新切的 Region 的打散成功率，1.0 表示都已经打散了。
 
-表 t 现在一共有 6 个 Region，其中 102、106、110、114、3 用来存行数据，Region 98 用来存索引数据。
+更详细的示例如下：
 
 {{< copyable "sql" >}}
 
@@ -195,6 +221,10 @@ show table t regions;
 7 rows in set
 ```
 
+## MySQL 兼容性
+
+`SHOW TABLE REGIONS` 语句是 TiDB 对 MySQL 语法的扩展。
+
 ## 另请参阅
 
 * [SPLIT REGION](/sql-statements/sql-statement-split-region.md)