Update EBNF for admin statements and add checksum details (#17879)

Author: qiancai

sql-statements/sql-statement-admin-cancel-ddl.md

@@ -12,8 +12,8 @@ summary: TiDB 数据库中 ADMIN CANCEL DDL 的使用概况。
 ## 语法图
 
 ```ebnf+diagram
-AdminStmt ::=
-    'ADMIN' ( 'SHOW' ( 'DDL' ( 'JOBS' Int64Num? WhereClauseOptional | 'JOB' 'QUERIES' NumList )? | TableName 'NEXT_ROW_ID' | 'SLOW' AdminShowSlow ) | 'CHECK' ( 'TABLE' TableNameList | 'INDEX' TableName Identifier ( HandleRange ( ',' HandleRange )* )? ) | 'RECOVER' 'INDEX' TableName Identifier | 'CLEANUP' ( 'INDEX' TableName Identifier | 'TABLE' 'LOCK' TableNameList ) | 'CHECKSUM' 'TABLE' TableNameList | 'CANCEL' 'DDL' 'JOBS' NumList | 'RELOAD' ( 'EXPR_PUSHDOWN_BLACKLIST' | 'OPT_RULE_BLACKLIST' | 'BINDINGS' ) | 'PLUGINS' ( 'ENABLE' | 'DISABLE' ) PluginNameList | 'REPAIR' 'TABLE' TableName CreateTableStmt | ( 'FLUSH' | 'CAPTURE' | 'EVOLVE' ) 'BINDINGS' )
+AdminCancelDDLStmt ::=
+    'ADMIN' 'CANCEL' 'DDL' 'JOBS' NumList
 
 NumList ::=
     Int64Num ( ',' Int64Num )*
@@ -23,8 +23,6 @@ NumList ::=
 
 可以通过 `ADMIN CANCEL DDL JOBS` 语句取消当前正在运行的 DDL 作业，并返回对应作业是否取消成功：
 
-{{< copyable "sql" >}}
-
 ```sql
 ADMIN CANCEL DDL JOBS job_id [, job_id] ...;
 ```

sql-statements/sql-statement-admin-check-table-index.md

@@ -26,35 +26,31 @@ summary: TiDB 数据库中 ADMIN CHECK [TABLE|INDEX] 的使用概况。
 ## 语法图
 
 ```ebnf+diagram
-AdminStmt ::=
-    'ADMIN' ( 'SHOW' ( 'DDL' ( 'JOBS' Int64Num? WhereClauseOptional | 'JOB' 'QUERIES' NumList )? | TableName 'NEXT_ROW_ID' | 'SLOW' AdminShowSlow ) | 'CHECK' ( 'TABLE' TableNameList | 'INDEX' TableName Identifier ( HandleRange ( ',' HandleRange )* )? ) | 'RECOVER' 'INDEX' TableName Identifier | 'CLEANUP' ( 'INDEX' TableName Identifier | 'TABLE' 'LOCK' TableNameList ) | 'CHECKSUM' 'TABLE' TableNameList | 'CANCEL' 'DDL' 'JOBS' NumList | 'RELOAD' ( 'EXPR_PUSHDOWN_BLACKLIST' | 'OPT_RULE_BLACKLIST' | 'BINDINGS' ) | 'PLUGINS' ( 'ENABLE' | 'DISABLE' ) PluginNameList | 'REPAIR' 'TABLE' TableName CreateTableStmt | ( 'FLUSH' | 'CAPTURE' | 'EVOLVE' ) 'BINDINGS' )
+AdminCheckStmt ::=
+    'ADMIN' 'CHECK' ( 'TABLE' TableNameList | 'INDEX' TableName Identifier ( HandleRange ( ',' HandleRange )* )? )
 
 TableNameList ::=
     TableName ( ',' TableName )*
+
+HandleRange ::= '(' Int64Num ',' Int64Num ')'
 ```
 
 ## 示例
 
 可以通过 `ADMIN CHECK TABLE` 语句校验 `tbl_name` 表中所有数据和对应索引的一致性：
 
-{{< copyable "sql" >}}
-
 ```sql
 ADMIN CHECK TABLE tbl_name [, tbl_name] ...;
 ```
 
 若通过一致性校验，则返回空的查询结果；否则返回数据不一致的错误信息。
 
-{{< copyable "sql" >}}
-
 ```sql
 ADMIN CHECK INDEX tbl_name idx_name;
 ```
 
 以上语句用于对 `tbl_name` 表中 `idx_name` 索引对应列数据和索引数据进行一致性校验。若通过校验，则返回空的查询结果；否则返回数据不一致的错误信息。
 
-{{< copyable "sql" >}}
-
 ```sql
 ADMIN CHECK INDEX tbl_name idx_name (lower_val, upper_val) [, (lower_val, upper_val)] ...;
 ```

sql-statements/sql-statement-admin-checksum-table.md

@@ -5,13 +5,17 @@ summary: TiDB 数据库中 ADMIN CHECKSUM TABLE 的使用概况。
 
 # ADMIN CHECKSUM TABLE
 
-`ADMIN CHECKSUM TABLE` 语句用于计算表中所有行和索引的 CRC64 校验和。在 TiDB Lightning 等程序中，可通过此语句来确保导入操作成功。
+`ADMIN CHECKSUM TABLE` 语句用于计算表中所有数据和索引的 CRC64 校验和。
+
+[校验和](/tidb-lightning/tidb-lightning-glossary.md#checksum)是通过表数据和 `table_id` 等属性进行计算得出的。这意味着两张 `table_id` 不同的表即使数据相同，校验和也不相同。
+
+当使用 [TiDB Lightning](/tidb-lightning/tidb-lightning-overview.md) 物理模式、[TiDB Data Migration](/dm/dm-overview.md) 或 [`IMPORT INTO`](/sql-statements/sql-statement-import-into.md) 导入完成一张表后，`ADMIN CHECKSUM TABLE <table>` 语句会默认执行以验证数据完整性。
 
 ## 语法图
 
 ```ebnf+diagram
-AdminStmt ::=
-    'ADMIN' ( 'SHOW' ( 'DDL' ( 'JOBS' Int64Num? WhereClauseOptional | 'JOB' 'QUERIES' NumList )? | TableName 'NEXT_ROW_ID' | 'SLOW' AdminShowSlow ) | 'CHECK' ( 'TABLE' TableNameList | 'INDEX' TableName Identifier ( HandleRange ( ',' HandleRange )* )? ) | 'RECOVER' 'INDEX' TableName Identifier | 'CLEANUP' ( 'INDEX' TableName Identifier | 'TABLE' 'LOCK' TableNameList ) | 'CHECKSUM' 'TABLE' TableNameList | 'CANCEL' 'DDL' 'JOBS' NumList | 'RELOAD' ( 'EXPR_PUSHDOWN_BLACKLIST' | 'OPT_RULE_BLACKLIST' | 'BINDINGS' ) | 'PLUGINS' ( 'ENABLE' | 'DISABLE' ) PluginNameList | 'REPAIR' 'TABLE' TableName CreateTableStmt | ( 'FLUSH' | 'CAPTURE' | 'EVOLVE' ) 'BINDINGS' )
+AdminChecksumTableStmt ::=
+    'ADMIN' 'CHECKSUM' 'TABLE' TableNameList
 
 TableNameList ::=
     TableName ( ',' TableName )*

sql-statements/sql-statement-admin-pause-ddl.md

@@ -18,8 +18,8 @@ summary: TiDB 数据库中 ADMIN PAUSE DDL JOBS 的使用概况。
 ## 语法图
 
 ```ebnf+diagram
-AdminStmt ::=
-    'ADMIN' ( 'SHOW' ( 'DDL' ( 'JOBS' Int64Num? WhereClauseOptional | 'JOB' 'QUERIES' NumList )? | TableName 'NEXT_ROW_ID' | 'SLOW' AdminShowSlow ) | 'CHECK' ( 'TABLE' TableNameList | 'INDEX' TableName Identifier ( HandleRange ( ',' HandleRange )* )? ) | 'RECOVER' 'INDEX' TableName Identifier | 'CLEANUP' ( 'INDEX' TableName Identifier | 'TABLE' 'LOCK' TableNameList ) | 'CHECKSUM' 'TABLE' TableNameList | 'CANCEL' 'DDL' 'JOBS' NumList | 'PAUSE' 'DDL' 'JOBS' NumList | 'RESUME' 'DDL' 'JOBS' NumList | 'RELOAD' ( 'EXPR_PUSHDOWN_BLACKLIST' | 'OPT_RULE_BLACKLIST' | 'BINDINGS' ) | 'PLUGINS' ( 'ENABLE' | 'DISABLE' ) PluginNameList | 'REPAIR' 'TABLE' TableName CreateTableStmt | ( 'FLUSH' | 'CAPTURE' | 'EVOLVE' ) 'BINDINGS' )
+AdminPauseDDLStmt ::=
+    'ADMIN' 'PAUSE' 'DDL' 'JOBS' NumList
 
 NumList ::=
     Int64Num ( ',' Int64Num )*

sql-statements/sql-statement-admin-recover.md

@@ -10,7 +10,7 @@ summary: TiDB 数据库中 ADMIN RECOVER INDEX 的使用概况。
 ## 语法图
 
 ```ebnf+diagram
-AdminCleanupStmt ::=
+AdminRecoverStmt ::=
     'ADMIN' 'RECOVER' 'INDEX' TableName IndexName
 ```
 

sql-statements/sql-statement-admin-resume-ddl.md

@@ -20,8 +20,8 @@ summary: TiDB 数据库中 ADMIN RESUME DDL 的使用概况。
 ## 语法图
 
 ```ebnf+diagram
-AdminStmt ::=
-    'ADMIN' ( 'SHOW' ( 'DDL' ( 'JOBS' Int64Num? WhereClauseOptional | 'JOB' 'QUERIES' NumList )? | TableName 'NEXT_ROW_ID' | 'SLOW' AdminShowSlow ) | 'CHECK' ( 'TABLE' TableNameList | 'INDEX' TableName Identifier ( HandleRange ( ',' HandleRange )* )? ) | 'RECOVER' 'INDEX' TableName Identifier | 'CLEANUP' ( 'INDEX' TableName Identifier | 'TABLE' 'LOCK' TableNameList ) | 'CHECKSUM' 'TABLE' TableNameList | 'CANCEL' 'DDL' 'JOBS' NumList | 'PAUSE' 'DDL' 'JOBS' NumList | 'RESUME' 'DDL' 'JOBS' NumList | 'RELOAD' ( 'EXPR_PUSHDOWN_BLACKLIST' | 'OPT_RULE_BLACKLIST' | 'BINDINGS' ) | 'PLUGINS' ( 'ENABLE' | 'DISABLE' ) PluginNameList | 'REPAIR' 'TABLE' TableName CreateTableStmt | ( 'FLUSH' | 'CAPTURE' | 'EVOLVE' ) 'BINDINGS' )
+AdminResumeDDLStmt ::=
+    'ADMIN' 'RESUME' 'DDL' 'JOBS' NumList
 
 NumList ::=
     Int64Num ( ',' Int64Num )*

sql-statements/sql-statement-admin-show-ddl.md

@@ -10,7 +10,7 @@ summary: TiDB 数据库中 ADMIN SHOW DDL [JOBS|JOB QUERIES] 的使用概况。
 ## 语法图
 
 ```ebnf+diagram
-AdminStmt ::=
+AdminShowDDLStmt ::=
     'ADMIN' 'SHOW' 'DDL'
     ( 
         'JOBS' Int64Num? WhereClauseOptional 

sql-statements/sql-statement-admin.md

@@ -29,16 +29,12 @@ summary: TiDB的 `ADMIN` 语句是用于查看TiDB状态和对表数据进行校
 
 ## `ADMIN RELOAD` 语句
 
-{{< copyable "sql" >}}
-
 ```sql
 ADMIN RELOAD expr_pushdown_blacklist;
 ```
 
 以上语句用于重新加载表达式下推的黑名单。
 
-{{< copyable "sql" >}}
-
 ```sql
 ADMIN RELOAD opt_rule_blacklist;
 ```
@@ -47,16 +43,12 @@ ADMIN RELOAD opt_rule_blacklist;
 
 ## `ADMIN PLUGIN` 语句
 
-{{< copyable "sql" >}}
-
 ```sql
 ADMIN PLUGINS ENABLE plugin_name [, plugin_name] ...;
 ```
 
 以上语句用于启用 `plugin_name` 插件。
 
-{{< copyable "sql" >}}
-
 ```sql
 ADMIN PLUGINS DISABLE plugin_name [, plugin_name] ...;
 ```
@@ -65,32 +57,24 @@ ADMIN PLUGINS DISABLE plugin_name [, plugin_name] ...;
 
 ## `ADMIN ... BINDINGS` 语句
 
-{{< copyable "sql" >}}
-
 ```sql
 ADMIN FLUSH bindings;
 ```
 
 以上语句用于持久化 SQL Plan 绑定的信息。
 
-{{< copyable "sql" >}}
-
 ```sql
 ADMIN CAPTURE bindings;
 ```
 
 以上语句可以将出现超过一次的 `select`execution-plan 语句生成 SQL Plan 的绑定。
 
-{{< copyable "sql" >}}
-
 ```sql
 ADMIN EVOLVE bindings;
 ```
 
 开启自动绑定功能后，每隔 `bind-info-lease`（默认值为 `3s`）触发一次 SQL Plan 绑定信息的演进。以上语句用于主动触发此演进，SQL Plan 绑定详情可参考：[执行计划管理](/sql-plan-management.md)。
 
-{{< copyable "sql" >}}
-
 ```sql
 ADMIN RELOAD bindings;
 ```
@@ -99,8 +83,6 @@ ADMIN RELOAD bindings;
 
 ## `ADMIN REPAIR TABLE` 语句
 
-{{< copyable "sql" >}}
-
 ```sql
 ADMIN REPAIR TABLE tbl_name CREATE TABLE STATEMENT;
 ```
@@ -117,14 +99,10 @@ ADMIN SHOW t NEXT_ROW_ID;
 
 ## `ADMIN SHOW SLOW` 语句
 
-{{< copyable "sql" >}}
-
 ```sql
 ADMIN SHOW SLOW RECENT N;
 ```
 
-{{< copyable "sql" >}}
-
 ```sql
 ADMIN SHOW SLOW TOP [INTERNAL | ALL] N;
 ```
@@ -135,15 +113,57 @@ ADMIN SHOW SLOW TOP [INTERNAL | ALL] N;
 
 ```ebnf+diagram
 AdminStmt ::=
-    'ADMIN' ( 'SHOW' ( 'DDL' ( 'JOBS' Int64Num? WhereClauseOptional | 'JOB' 'QUERIES' NumList )? | TableName 'NEXT_ROW_ID' | 'SLOW' AdminShowSlow ) | 'CHECK' ( 'TABLE' TableNameList | 'INDEX' TableName Identifier ( HandleRange ( ',' HandleRange )* )? ) | 'RECOVER' 'INDEX' TableName Identifier | 'CLEANUP' ( 'INDEX' TableName Identifier | 'TABLE' 'LOCK' TableNameList ) | 'CHECKSUM' 'TABLE' TableNameList | 'CANCEL' 'DDL' 'JOBS' NumList | 'RELOAD' ( 'EXPR_PUSHDOWN_BLACKLIST' | 'OPT_RULE_BLACKLIST' | 'BINDINGS' ) | 'PLUGINS' ( 'ENABLE' | 'DISABLE' ) PluginNameList | 'REPAIR' 'TABLE' TableName CreateTableStmt | ( 'FLUSH' | 'CAPTURE' | 'EVOLVE' ) 'BINDINGS' )
+    'ADMIN' ( 
+        'SHOW' ( 
+            'DDL' ( 
+                'JOBS' Int64Num? WhereClauseOptional 
+                | 'JOB' 'QUERIES' (NumList | AdminStmtLimitOpt)
+            )? 
+            | TableName 'NEXT_ROW_ID' 
+            | 'SLOW' AdminShowSlow 
+            | 'BDR' 'ROLE'
+        ) 
+        | 'CHECK' ( 
+            'TABLE' TableNameList 
+            | 'INDEX' TableName Identifier ( HandleRange ( ',' HandleRange )* )? 
+        ) 
+        | 'RECOVER' 'INDEX' TableName Identifier 
+        | 'CLEANUP' ( 
+            'INDEX' TableName Identifier 
+            | 'TABLE' 'LOCK' TableNameList ) 
+        | 'CHECKSUM' 'TABLE' TableNameList | 'CANCEL' 'DDL' 'JOBS' NumList 
+        | ( 'CANCEL' | 'PAUSE' | 'RESUME' ) 'DDL' 'JOBS' NumList
+        | 'RELOAD' (
+            'EXPR_PUSHDOWN_BLACKLIST' 
+            | 'OPT_RULE_BLACKLIST' 
+            | 'BINDINGS'
+            | 'STATS_EXTENDED'
+            | 'STATISTICS'
+        ) 
+        | 'PLUGINS' ( 'ENABLE' | 'DISABLE' ) PluginNameList 
+        | 'REPAIR' 'TABLE' TableName CreateTableStmt 
+        | ( 'FLUSH' | 'CAPTURE' | 'EVOLVE' ) 'BINDINGS'
+        | 'FLUSH' ('SESSION' | 'INSTANCE') 'PLAN_CACHE'
+        | 'SET' 'BDR' 'ROLE' ( 'PRIMARY' | 'SECONDARY' )
+        | 'UNSET' 'BDR' 'ROLE'
+    )
+
+NumList ::=
+    Int64Num ( ',' Int64Num )*
+
+AdminStmtLimitOpt ::=
+    'LIMIT' LengthNum
+|    'LIMIT' LengthNum ',' LengthNum
+|    'LIMIT' LengthNum 'OFFSET' LengthNum
+
+TableNameList ::=
+    TableName ( ',' TableName )*
 ```
 
 ## 使用示例
 
 执行以下命令，可查看正在执行的 DDL 任务中最近 10 条已经完成的 DDL 任务。未指定 `NUM` 时，默认只显示最近 10 条已经执行完的 DDL 任务。
 
-{{< copyable "sql" >}}
-
 ```sql
 ADMIN SHOW DDL jobs;
 ```
@@ -168,8 +188,6 @@ ADMIN SHOW DDL jobs;
 
 执行以下命令，可查看正在执行的 DDL 任务中最近 5 条已经执行完的 DDL 任务：
 
-{{< copyable "sql" >}}
-
 ```sql
 ADMIN SHOW DDL JOBS 5;
 ```
@@ -205,8 +223,6 @@ ADMIN SHOW t NEXT_ROW_ID;
 
 执行以下命令，可查看 test 数据库中未执行完成的 DDL 任务，包括正在执行中以及最近 5 条已经执行完但是执行失败的 DDL 任务。
 
-{{< copyable "sql" >}}
-
 ```sql
 ADMIN SHOW DDL JOBS 5 WHERE state != 'synced' AND db_name = 'test';
 ```

sql-statements/sql-statement-import-into.md

@@ -349,6 +349,7 @@ IMPORT INTO t FROM SELECT * FROM src AS OF TIMESTAMP '2024-02-27 11:38:00';
 
 ## 另请参阅
 
-* [`SHOW IMPORT JOB(s)`](/sql-statements/sql-statement-show-import-job.md)
+* [`ADMIN CHECKSUM TABLE`](/sql-statements/sql-statement-admin-checksum-table.md)
 * [`CANCEL IMPORT JOB`](/sql-statements/sql-statement-cancel-import-job.md)
+* [`SHOW IMPORT JOB(s)`](/sql-statements/sql-statement-show-import-job.md)
 * [TiDB 分布式执行框架](/tidb-distributed-execution-framework.md)