sql statement: refined Synopsis (pingcap#17100)

TOC.md

@@ -850,7 +850,7 @@
       - [`SHOW PUMP STATUS`](/sql-statements/sql-statement-show-pump-status.md)
       - [`SHOW SCHEMAS`](/sql-statements/sql-statement-show-schemas.md)
       - [`SHOW STATS_HEALTHY`](/sql-statements/sql-statement-show-stats-healthy.md)
-      - [`SHOW STATS_HISTOGRAMS`](/sql-statements/sql-statement-show-histograms.md)
+      - [`SHOW STATS_HISTOGRAMS`](/sql-statements/sql-statement-show-stats-histograms.md)
       - [`SHOW STATS_LOCKED`](/sql-statements/sql-statement-show-stats-locked.md)
       - [`SHOW STATS_META`](/sql-statements/sql-statement-show-stats-meta.md)
       - [`SHOW STATUS`](/sql-statements/sql-statement-show-status.md)

sql-statements/sql-statement-set-role.md

@@ -10,24 +10,15 @@ aliases: ['/docs-cn/dev/sql-statements/sql-statement-set-role/']
 
 ## 语法图
 
-**SetRoleStmt:**
-
-![SetRoleStmt](/media/sqlgram/SetRoleStmt.png)
-
-**SetRoleOpt:**
-
-![SetRoleOpt](/media/sqlgram/SetRoleOpt.png)
-
-**SetDefaultRoleOpt:**
-
-![SetDefaultRoleOpt](/media/sqlgram/SetDefaultRoleOpt.png)
+```ebnf+diagram
+SetRoleStmt ::=
+    "SET" "ROLE" ( "DEFAULT" | "ALL" ( "EXCEPT" Rolename ("," Rolename)* )? | "NONE" | Rolename ("," Rolename)* )?
+```
 
 ## 示例
 
 创建一个用户 `'u1'@'%'`，创建三个角色 `'r1'@'%'`、`'r2'@'%'` 和 `'r3'@'%'` 并将这些角色授予给 `'u1'@'%'`。将 `'u1'@'%'` 的默认启用角色设置为 `'r1'@'%'`。
 
-{{< copyable "sql" >}}
-
 ```sql
 CREATE USER 'u1'@'%';
 CREATE ROLE 'r1', 'r2', 'r3';
@@ -37,8 +28,6 @@ SET DEFAULT ROLE 'r1' TO 'u1'@'%';
 
 使用 `'u1'@'%'` 登录，执行 `SET ROLE` 将启用角色设置为 `ALL`。
 
-{{< copyable "sql" >}}
-
 ```sql
 SET ROLE ALL;
 SELECT CURRENT_ROLE();
@@ -55,8 +44,6 @@ SELECT CURRENT_ROLE();
 
 执行 `SET ROLE` 将启用角色设置为 `'r2'` 和 `'r3'`。
 
-{{< copyable "sql" >}}
-
 ```sql
 SET ROLE 'r2', 'r3';
 SELECT CURRENT_ROLE();
@@ -73,8 +60,6 @@ SELECT CURRENT_ROLE();
 
 执行 `SET ROLE` 将启用角色设置为 `DEFAULT`。
 
-{{< copyable "sql" >}}
-
 ```sql
 SET ROLE DEFAULT;
 SELECT CURRENT_ROLE();
@@ -91,8 +76,6 @@ SELECT CURRENT_ROLE();
 
 执行 `SET ROLE` 将启用角色设置为 `NONE`。
 
-{{< copyable "sql" >}}
-
 ```sql
 SET ROLE NONE;
 SELECT CURRENT_ROLE();

sql-statements/sql-statement-set-variable.md

@@ -6,28 +6,31 @@ aliases: ['/docs-cn/dev/sql-statements/sql-statement-set-variable/','/docs-cn/de
 
 # `SET [GLOBAL|SESSION] <variable>`
 
-`SET [GLOBAL|SESSION]` 语句用于在 `SESSION` 或 `GLOBAL` 的范围内，对某个 TiDB 的内置变量进行更改。
+`SET [GLOBAL|SESSION]` 语句用于对某个 TiDB 的内置变量进行更改。这些变量可以是范围为 `SESSION` 或 `GLOBAL` 的[系统变量](/system-variables.md)或是[用户自定义变量](/user-defined-variables.md)。
+
+> **警告：**
+>
+> 用户自定义变量为实验特性，不建议在生产环境中使用。
 
 > **注意：**
 >
 > 与 MySQL 类似，对 `GLOBAL` 变量的更改不适用于已有连接或本地连接，只有新会话才会反映值的变化。
 
 ## 语法图
 
-**SetStmt:**
-
-![SetStmt](/media/sqlgram/SetStmt.png)
+```ebnf+diagram
+SetVariableStmt ::=
+    "SET" Variable "=" Expression ("," Variable "=" Expression )*
 
-**VariableAssignment:**
-
-![VariableAssignment](/media/sqlgram/VariableAssignment.png)
+Variable ::=
+    ("GLOBAL" | "SESSION") SystemVariable
+|   UserVariable
+```
 
 ## 示例
 
 获取 `sql_mode` 的值：
 
-{{< copyable "sql" >}}
-
 ```sql
 SHOW GLOBAL VARIABLES LIKE 'sql_mode';
 ```
@@ -41,8 +44,6 @@ SHOW GLOBAL VARIABLES LIKE 'sql_mode';
 1 row in set (0.00 sec)
 ```
 
-{{< copyable "sql" >}}
-
 ```sql
 SHOW SESSION VARIABLES LIKE 'sql_mode';
 ```
@@ -58,8 +59,6 @@ SHOW SESSION VARIABLES LIKE 'sql_mode';
 
 更新全局的 `sql_mode`：
 
-{{< copyable "sql" >}}
-
 ```sql
 SET GLOBAL sql_mode = 'STRICT_TRANS_TABLES,NO_AUTO_CREATE_USER';
 ```
@@ -70,8 +69,6 @@ Query OK, 0 rows affected (0.03 sec)
 
 检查更新之后的 `sql_mode` 的取值，可以看到 SESSION 级别的值没有更新：
 
-{{< copyable "sql" >}}
-
 ```sql
 SHOW GLOBAL VARIABLES LIKE 'sql_mode';
 ```
@@ -85,8 +82,6 @@ SHOW GLOBAL VARIABLES LIKE 'sql_mode';
 1 row in set (0.00 sec)
 ```
 
-{{< copyable "sql" >}}
-
 ```sql
 SHOW SESSION VARIABLES LIKE 'sql_mode';
 ```
@@ -102,8 +97,6 @@ SHOW SESSION VARIABLES LIKE 'sql_mode';
 
 `SET SESSION` 则可以立即生效：
 
-{{< copyable "sql" >}}
-
 ```sql
 SET SESSION sql_mode = 'STRICT_TRANS_TABLES,NO_AUTO_CREATE_USER';
 ```
@@ -112,8 +105,6 @@ SET SESSION sql_mode = 'STRICT_TRANS_TABLES,NO_AUTO_CREATE_USER';
 Query OK, 0 rows affected (0.01 sec)
 ```
 
-{{< copyable "sql" >}}
-
 ```sql
 SHOW SESSION VARIABLES LIKE 'sql_mode';
 ```
@@ -127,13 +118,29 @@ SHOW SESSION VARIABLES LIKE 'sql_mode';
 1 row in set (0.00 sec)
 ```
 
+以 `@` 开头的用户变量：
+
+```sql
+SET @myvar := 5;
+Query OK, 0 rows affected (0.00 sec)
+
+SELECT @myvar, @myvar + 1;
++--------+------------+
+| @myvar | @myvar + 1 |
++--------+------------+
+|      5 |          6 |
++--------+------------+
+1 row in set (0.00 sec)
+```
+
 ## MySQL 兼容性
 
 使用 `SET [GLOBAL|SESSION] <variable>` 更改系统变量上，TiDB 与 MySQL 存在以下差异
 
 * 与 MySQL 不同，TiDB 中使用 `SET GLOBAL` 所作的修改会应用于集群中的全部 TiDB 实例。而在 MySQL 中，修改不会应用于副本。
 * TiDB 中的若干变量可读又可设置，这是与 MySQL 相兼容的要求，因为应用程序和连接器常读取 MySQL 变量。例如：JDBC 连接器同时读取和设置缓存查询的参数，尽管并不依赖这一行为。
 * 即使在 TiDB 服务器重启后，`SET GLOBAL` 的更改也仍然有效。这样，TiDB 中的 `SET GLOBAL` 更类似于 MySQL 8.0 及更高版本中的 `SET PERSIST`。
+* TiDB 会持久化全局变量，因此 TiDB 不支持 `SET PERSIST` 和 `SET PERSIST_ONLY`。
 
 ## 另请参阅
 

sql-statements/sql-statement-show-create-sequence.md

@@ -10,18 +10,13 @@ aliases: ['/docs-cn/dev/sql-statements/sql-statement-show-create-sequence/','/do
 
 ## 语法图
 
-**ShowCreateSequenceStmt:**
-
-![ShowCreateSequenceStmt](/media/sqlgram/ShowCreateSequenceStmt.png)
-
-**TableName:**
-
-![TableName](/media/sqlgram/TableName.png)
+```ebnf+diagram
+ShowCreateSequenceStmt ::=
+    "SHOW" "CREATE" "SEQUENCE" ( SchemaName "." )? TableName
+```
 
 ## 示例
 
-{{< copyable "sql" >}}
-
 ```sql
 CREATE SEQUENCE seq;
 ```
@@ -30,8 +25,6 @@ CREATE SEQUENCE seq;
 Query OK, 0 rows affected (0.03 sec)
 ```
 
-{{< copyable "sql" >}}
-
 ```sql
 SHOW CREATE SEQUENCE seq;
 ```

sql-statements/sql-statement-show-placement-for.md

@@ -17,7 +17,7 @@ summary: TiDB 数据库中 SHOW PLACEMENT FOR 的使用概况。
 
 ```ebnf+diagram
 ShowStmt ::=
-    "PLACEMENT" "FOR" ShowPlacementTarget
+    "SHOW" "PLACEMENT" "FOR" ShowPlacementTarget
 
 ShowPlacementTarget ::=
     DatabaseSym DBName
@@ -27,8 +27,6 @@ ShowPlacementTarget ::=
 
 ## 示例
 
-{{< copyable "sql" >}}
-
 ```sql
 CREATE PLACEMENT POLICY p1 PRIMARY_REGION="us-east-1" REGIONS="us-east-1,us-west-1" FOLLOWERS=4;
 use test;

sql-statements/sql-statement-show-placement-labels.md

@@ -11,13 +11,11 @@ summary: TiDB 数据库中 SHOW PLACEMENT LABELS 的使用概况。
 
 ```ebnf+diagram
 ShowStmt ::=
-    "PLACEMENT" "LABELS"
+    "SHOW" "PLACEMENT" "LABELS" ShowLikeOrWhere?
 ```
 
 ## 示例
 
-{{< copyable "sql" >}}
-
 ```sql
 SHOW PLACEMENT LABELS;
 ```

sql-statements/sql-statement-show-placement.md

@@ -17,13 +17,11 @@ summary: TiDB 数据库中 SHOW PLACEMENT 的使用概况。
 
 ```ebnf+diagram
 ShowStmt ::=
-    "PLACEMENT"
+    "SHOW" "PLACEMENT" ShowLikeOrWhere?
 ```
 
 ## 示例
 
-{{< copyable "sql" >}}
-
 ```sql
 CREATE PLACEMENT POLICY p1 PRIMARY_REGION="us-east-1" REGIONS="us-east-1,us-west-1" FOLLOWERS=4;
 CREATE TABLE t1 (a INT) PLACEMENT POLICY=p1;

sql-statements/sql-statement-show-histograms.md → sql-statements/sql-statement-show-stats-histograms.md

@@ -1,33 +1,28 @@
 ---
 title: SHOW STATS_HISTOGRAMS
 summary: TiDB 数据库中 SHOW HISTOGRAMS 语句的简单说明。
-aliases: ['/docs-cn/dev/sql-statements/sql-statement-show-histograms/']
+aliases: ['/docs-cn/dev/sql-statements/sql-statement-show-histograms/','/zh/tidb/dev/sql-statement-show-histograms']
 ---
 
 # SHOW STATS_HISTOGRAMS
 
-你可以使用 `SHOW STATS_HISTOGRAMS` 语句查看统计信息中直方图的相关信息。
+你可以使用 `SHOW STATS_HISTOGRAMS` 语句查看通过 [`ANALYZE` 语句](/sql-statements/sql-statement-analyze-table.md) 收集的直方图信息，该内容是数据库 [统计信息](/statistics.md) 的一部分。
 
 ## 语法图
 
-**ShowStmt**
+```ebnf+diagram
+ShowStatsHistogramsStmt ::=
+    "SHOW" "STATS_HISTOGRAMS" ShowLikeOrWhere?
 
-![ShowStmt](/media/sqlgram/ShowStmt.png)
-
-**ShowTargetFiltertable**
-
-![ShowTargetFilterable](/media/sqlgram/ShowTargetFilterable.png)
-
-**ShowLikeOrWhereOpt**
-
-![ShowLikeOrWhereOpt](/media/sqlgram/ShowLikeOrWhereOpt.png)
+ShowLikeOrWhere ::=
+    "LIKE" SimpleExpr
+|   "WHERE" Expression
+```
 
 ## 示例
 
-{{< copyable "sql" >}}
-
 ```sql
-show stats_histograms;
+SHOW STATS_HISTOGRAMS;
 ```
 
 ```sql
@@ -41,10 +36,8 @@ show stats_histograms;
 3 rows in set (0.00 sec)
 ```
 
-{{< copyable "sql" >}}
-
 ```sql
-show stats_histograms where table_name = 't2';
+SHOW STATS_HISTOGRAMS WHERE table_name = 't2';
 ```
 
 ```sql