Rehash and update statistics and SQL docs (pingcap#17827)

shawn0915 · Jul 24, 2024 · cbccda9 · cbccda9
1 parent 82557fc
commit cbccda9
Show file tree

Hide file tree

Showing 18 changed files with 600 additions and 526 deletions.
diff --git a/TOC.md b/TOC.md
@@ -841,6 +841,7 @@
       - [`SHOW BUILTINS`](/sql-statements/sql-statement-show-builtins.md)
       - [`SHOW CHARACTER SET`](/sql-statements/sql-statement-show-character-set.md)
       - [`SHOW COLLATION`](/sql-statements/sql-statement-show-collation.md)
+      - [`SHOW COLUMN_STATS_USAGE`](/sql-statements/sql-statement-show-column-stats-usage.md)
       - [`SHOW COLUMNS FROM`](/sql-statements/sql-statement-show-columns-from.md)
       - [`SHOW CONFIG`](/sql-statements/sql-statement-show-config.md)
       - [`SHOW CREATE PLACEMENT POLICY`](/sql-statements/sql-statement-show-create-placement-policy.md)
@@ -867,10 +868,12 @@
       - [`SHOW PROFILES`](/sql-statements/sql-statement-show-profiles.md)
       - [`SHOW PUMP STATUS`](/sql-statements/sql-statement-show-pump-status.md)
       - [`SHOW SCHEMAS`](/sql-statements/sql-statement-show-schemas.md)
+      - [`SHOW STATS_BUCKETS`](/sql-statements/sql-statement-show-stats-buckets.md)
       - [`SHOW STATS_HEALTHY`](/sql-statements/sql-statement-show-stats-healthy.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 STATS_TOPN`](/sql-statements/sql-statement-show-stats-topn.md)
       - [`SHOW STATUS`](/sql-statements/sql-statement-show-status.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)

diff --git a/extended-statistics.md b/extended-statistics.md
@@ -7,8 +7,8 @@ summary: 了解如何使用扩展统计信息指导优化器。
 
 TiDB 可以收集以下两种类型的统计信息，本文主要介绍如何使用扩展统计信息来指导优化器。阅读本文前，建议先阅读[常规统计信息](/statistics.md)。
 
-- 常规统计信息：例如直方图和 Count-Min Sketch，详情参见[常规统计信息](/statistics.md)。
-- 扩展统计信息：通过表和列过滤的统计信息。
+- 常规统计信息：主要关注单个列的统计信息，例如直方图和 Count-Min Sketch。这些统计信息对优化器估算查询成本至关重要。详情参见[常规统计信息](/statistics.md)。
+- 扩展统计信息：主要关注指定列之间的数据相关性，指导优化器在查询有相关性的列时更精确地估算查询成本。
 
 当手动或自动执行 `ANALYZE` 语句时，TiDB 默认只收集常规统计信息，不收集扩展统计信息。这是因为扩展统计信息仅在特定场景下用于优化器估算，而且收集扩展统计信息会增加额外开销。
 

diff --git a/optimizer-fix-controls.md b/optimizer-fix-controls.md
@@ -36,7 +36,7 @@ SET SESSION tidb_opt_fix_control = '44262:ON,44389:ON';
 
 - 默认值：`OFF`
 - 可选值：`ON`、`OFF`
-- 是否允许在缺少 [GlobalStats](/statistics.md#动态裁剪模式下的分区表统计信息) 的情况下使用[动态裁剪模式](/partitioned-table.md#动态裁剪模式)访问分区表。
+- 是否允许在缺少 [GlobalStats](/statistics.md#收集动态裁剪模式下的分区表统计信息) 的情况下使用[动态裁剪模式](/partitioned-table.md#动态裁剪模式)访问分区表。
 
 ### [`44389`](https://github.com/pingcap/tidb/issues/44389) <span class="version-mark">从 v6.5.3 和 v7.2.0 版本开始引入</span>
 

diff --git a/partitioned-table.md b/partitioned-table.md
@@ -1785,7 +1785,7 @@ select * from t;
 
 ### 动态裁剪模式
 
-TiDB 访问分区表有两种模式，`dynamic` 和 `static`。从 v6.3.0 开始，默认使用 `dynamic` 模式。但是注意，`dynamic` 模式仅在表级别汇总统计信息（即 GlobalStats）收集完成的情况下生效。如果选择了 `dynamic` 但 GlobalStats 未收集完成，TiDB 会仍采用 `static` 模式。关于 GlobalStats 更多信息，请参考[动态裁剪模式下的分区表统计信息](/statistics.md#动态裁剪模式下的分区表统计信息)。
+TiDB 访问分区表有两种模式，`dynamic` 和 `static`。从 v6.3.0 开始，默认使用 `dynamic` 模式。但是注意，`dynamic` 模式仅在表级别汇总统计信息（即 GlobalStats）收集完成的情况下生效。如果选择了 `dynamic` 但 GlobalStats 未收集完成，TiDB 会仍采用 `static` 模式。关于 GlobalStats 更多信息，请参考[动态裁剪模式下的分区表统计信息](/statistics.md#收集动态裁剪模式下的分区表统计信息)。
 
 {{< copyable "sql" >}}
 

diff --git a/releases/release-5.4.0.md b/releases/release-5.4.0.md
@@ -36,7 +36,7 @@ TiDB 版本：5.4.0
 |  [`tidb_enable_column_tracking`](/system-variables.md#tidb_enable_column_tracking-从-v540-版本开始引入) | 新增 | 用于控制是否开启 TiDB 对 `PREDICATE COLUMNS` 的收集，默认值为 `OFF`。 |
 | [`tidb_enable_paging`](/system-variables.md#tidb_enable_paging-从-v540-版本开始引入)  | 新增 | 此变量用于控制 `IndexLookUp` 算子是否使用分页 (paging) 方式发送 Coprocessor 请求，默认值为 `OFF`。对于使用 `IndexLookUp` 和 `Limit` 并且 `Limit` 无法下推到 `IndexScan` 上的读请求，可能会出现读请求的延迟高、TiKV 的 Unified read pool CPU 使用率高的情况。在这种情况下，由于 `Limit` 算子只需要少部分数据，开启 `tidb_enable_paging`，能够减少处理数据的数量，从而降低延迟、减少资源消耗。 |
 | [`tidb_enable_top_sql`](/system-variables.md#tidb_enable_top_sql-从-v540-版本开始引入) | 新增 | 用于控制是否开启 Top SQL 特性，默认值为 OFF。 |
-| [`tidb_persist_analyze_options`](/system-variables.md#tidb_persist_analyze_options-从-v540-版本开始引入)  | 新增  | 用于控制是否开启 [ANALYZE 配置持久化](/statistics.md#analyze-配置持久化)特性，默认值为 `ON`。 |
+| [`tidb_persist_analyze_options`](/system-variables.md#tidb_persist_analyze_options-从-v540-版本开始引入)  | 新增  | 用于控制是否开启 [ANALYZE 配置持久化](/statistics.md#持久化-analyze-配置)特性，默认值为 `ON`。 |
 | [`tidb_read_staleness`](/system-variables.md#tidb_read_staleness-从-v540-版本开始引入) | 新增 | 用于设置当前会话允许读取的历史数据范围，默认值为 `0`。 |
 | [`tidb_regard_null_as_point`](/system-variables.md#tidb_regard_null_as_point-从-v540-版本开始引入) | 新增 | 用于控制优化器是否可以将包含 null 的等值条件作为前缀条件来访问索引。 |
 | [`tidb_stats_load_sync_wait`](/system-variables.md#tidb_stats_load_sync_wait-从-v540-版本开始引入) | 新增 | 这个变量用于控制是否开启统计信息的同步加载模式（默认为 `0` 代表不开启，即为异步加载模式），以及开启的情况下，SQL 执行同步加载完整统计信息等待多久后会超时。 |
@@ -201,7 +201,7 @@ TiDB 版本：5.4.0
 
     `ANALYZE` 配置持久化功能默认开启（系统变量 `tidb_analyze_version` 为默认值 `2`，[`tidb_persist_analyze_options`](/system-variables.md#tidb_persist_analyze_options-从-v540-版本开始引入) 为默认值 `ON`），用于记录手动执行 `ANALYZE` 语句时指定的持久化配置项。记录后，当 TiDB 下一次自动更新统计信息或者你手动收集统计信息但未指定配置项时，TiDB 会按照记录的配置项收集统计信息。
 
-    [用户文档](/statistics.md#analyze-配置持久化)
+    [用户文档](/statistics.md#持久化-analyze-配置)
 
 ### 高可用和容灾
 

diff --git a/releases/release-6.3.0.md b/releases/release-6.3.0.md
@@ -147,7 +147,7 @@ TiDB 版本：6.3.0-DMR
 
 * 缺少 GlobalStats 时自动选择分区静态剪裁 [#37535](https://github.com/pingcap/tidb/issues/37535) @[Yisaer](https://github.com/Yisaer)
 
-    当启用分区[动态剪裁](/partitioned-table.md#动态裁剪模式)时，优化器依赖 [GlobalStats](/statistics.md#动态裁剪模式下的分区表统计信息) 进行执行计划的选择。在 [GlobalStats](/statistics.md#动态裁剪模式下的分区表统计信息) 收集完成前，使用 pseudo 统计信息可能会造成性能回退。在 v6.3.0 版本中，如果在 [GlobalStats](/statistics.md#动态裁剪模式下的分区表统计信息) 收集未完成的情况下打开动态分区裁剪开关，TiDB 会维持静态分区剪裁的状态，直到 GlobalStats 收集完成。该方式确保在切换分区剪裁策略时系统性能保持稳定。
+    当启用分区[动态剪裁](/partitioned-table.md#动态裁剪模式)时，优化器依赖 [GlobalStats](/statistics.md#收集动态裁剪模式下的分区表统计信息) 进行执行计划的选择。在 [GlobalStats](/statistics.md#收集动态裁剪模式下的分区表统计信息) 收集完成前，使用 pseudo 统计信息可能会造成性能回退。在 v6.3.0 版本中，如果在 [GlobalStats](/statistics.md#收集动态裁剪模式下的分区表统计信息) 收集未完成的情况下打开动态分区裁剪开关，TiDB 会维持静态分区剪裁的状态，直到 GlobalStats 收集完成。该方式确保在切换分区剪裁策略时系统性能保持稳定。
 
 ### 易用性
 

diff --git a/releases/release-7.4.0.md b/releases/release-7.4.0.md
@@ -179,7 +179,7 @@ TiDB 版本：7.4.0
     - `lightning`：使用 [TiDB Lightning](/tidb-lightning/tidb-lightning-overview.md) 或 [`IMPORT INTO`](/sql-statements/sql-statement-import-into.md) 执行导入任务。
     - `br`：使用 [BR](/br/backup-and-restore-overview.md) 执行数据备份和恢复。目前不支持 PITR。
     - `ddl`：对于 Reorg DDL，控制批量数据回写阶段的资源使用。
-    - `stats`：对应手动执行或系统自动触发的[收集统计信息](/statistics.md#统计信息的收集)任务。
+    - `stats`：对应手动执行或系统自动触发的[收集统计信息](/statistics.md#收集统计信息)任务。
 
   默认情况下，被标记为后台任务的任务类型为空，此时后台任务的管理功能处于关闭状态，其行为与 TiDB v7.4.0 之前版本保持一致。你需要手动修改 `default` 资源组的后台任务类型以开启后台任务管理。
 

diff --git a/sql-statements/sql-statement-drop-stats.md b/sql-statements/sql-statement-drop-stats.md
@@ -12,34 +12,59 @@ aliases: ['/docs-cn/dev/sql-statements/sql-statement-drop-stats/']
 
 ```ebnf+diagram
 DropStatsStmt ::=
-    'DROP' 'STATS' TableNameList 
-
-TableNameList ::=
-    TableName ( ',' TableName )*
+    'DROP' 'STATS' TableName  ("PARTITION" partition | "GLOBAL")? ( ',' TableName )*
 
 TableName ::=
     Identifier ('.' Identifier)?
 ```
 
-## 示例
+## 使用
 
-{{< copyable "sql" >}}
+以下语句用于删除 `TableName` 的所有统计信息。如果指定了分区表，则此语句还会删除该表中所有分区的统计信息以及[动态裁剪模式下的分区表统计信息](/statistics.md#收集动态裁剪模式下的分区表统计信息)。
 
 ```sql
-CREATE TABLE t(a INT);
+DROP STATS TableName
+```
+
 ```
+Query OK, 0 rows affected (0.00 sec)
+```
+
+以下语句只删除 `PartitionNameList` 中指定分区的统计信息：
 
 ```sql
-Query OK, 0 rows affected (0.01 sec)
+DROP STATS TableName PARTITION PartitionNameList;
 ```
 
-{{< copyable "sql" >}}
+```
+Query OK, 0 rows affected (0.00 sec)
+```
+
+以下语句只删除指定表在动态裁剪模式下生成的 GlobalStats 统计信息：
 
 ```sql
-SHOW STATS_META WHERE db_name='test' and table_name='t';
+DROP STATS TableName GLOBAL;
+```
+
+```
+Query OK, 0 rows affected (0.00 sec)
+```
+
+## 示例
+
+```sql
+CREATE TABLE t(a INT);
+```
+
+```
+Query OK, 0 rows affected (0.01 sec)
 ```
 
 ```sql
+SHOW STATS_META WHERE db_name='test' and table_name='t';
+```
+
+```
 +---------+------------+----------------+---------------------+--------------+-----------+
 | Db_name | Table_name | Partition_name | Update_time         | Modify_count | Row_count |
 +---------+------------+----------------+---------------------+--------------+-----------+
@@ -48,23 +73,19 @@ SHOW STATS_META WHERE db_name='test' and table_name='t';
 1 row in set (0.00 sec)
 ```
 
-{{< copyable "sql" >}}
-
 ```sql
 DROP STATS t;
 ```
 
-```sql
+```
 Query OK, 0 rows affected (0.00 sec)
 ```
 
-{{< copyable "sql" >}}
-
 ```sql
 SHOW STATS_META WHERE db_name='test' and table_name='t';
 ```
 
-```sql
+```
 Empty set (0.00 sec)
 ```
 

diff --git a/sql-statements/sql-statement-show-analyze-status.md b/sql-statements/sql-statement-show-analyze-status.md
@@ -14,6 +14,22 @@ aliases: ['/docs-cn/dev/sql-statements/sql-statement-show-analyze-status/']
 
 从 TiDB v7.3.0 起，你可以通过系统表 `mysql.analyze_jobs` 或者 `SHOW ANALYZE STATUS` 查看当前 `ANALYZE` 任务的进度。
 
+目前，`SHOW ANALYZE STATUS` 语句返回以下列：
+
+| 列名 | 说明            |
+| :-------- | :------------- |
+| `Table_schema` |  数据库名    |
+| `Table_name` | 表名 |
+| `Partition_name` | 分区名 |
+| `Job_info` | 任务具体信息。当收集索引的统计信息时，该信息会包含索引名。当 `tidb_analyze_version = 2` 时，该信息会包含采样率等配置项。 |
+| `Processed_rows` | 已经 `ANALYZE` 的行数 |
+| `Start_time` | 任务开始执行的时间 |
+| `End_time` | 任务结束执行的时间 |
+| `State` | 任务状态，包括 pending（等待）、running（正在执行）、finished（执行成功）和 failed（执行失败）|
+| `Fail_reason` | 任务失败的原因。如果执行成功则为 `NULL`。 |
+| `Instance` | 执行任务的 TiDB 实例 |
+| `Process_id` | 执行任务的 process ID |
+
 ## 语法图
 
 ```ebnf+diagram
@@ -72,4 +88,4 @@ mysql> show analyze status;
 
 ## 另请参阅
 
-* [ANALYZE_STATUS 表](/information-schema/information-schema-analyze-status.md)
+* [`ANALYZE_STATUS` 表](/information-schema/information-schema-analyze-status.md)
diff --git a/sql-statements/sql-statement-show-column-stats-usage.md b/sql-statements/sql-statement-show-column-stats-usage.md
@@ -0,0 +1,57 @@
+---
+title: SHOW COLUMN_STATS_USAGE
+summary: TiDB 数据库中 SHOW COLUMN_STATS_USAGE 的使用概况。
+---
+
+# SHOW COLUMN_STATS_USAGE
+
+`SHOW COLUMN_STATS_USAGE` 语句显示列统计信息的最近一次使用时间和收集时间。你还可以使用该语句来查看 `PREDICATE COLUMNS` 和已收集统计信息的列。
+
+目前，`SHOW COLUMN_STATS_USAGE` 语句返回以下列：
+
+| 列名 | 说明            |
+| -------- | ------------- |
+| `Db_name`  |  数据库名   |
+| `Table_name` | 表名 |
+| `Partition_name` | 分区名 |
+| `Column_name` | 列名 |
+| `Last_used_at` | 最近一次将列统计信息用于查询优化的时间 |
+| `Last_analyzed_at` | 最近一次收集列统计信息的时间 |
+
+## 语法图
+
+```ebnf+diagram
+ShowColumnStatsUsageStmt ::=
+    "SHOW" "COLUMN_STATS_USAGE" ShowLikeOrWhere?
+ShowLikeOrWhere ::=
+    "LIKE" SimpleExpr
+|   "WHERE" Expression
+```
+
+## 示例
+
+```sql
+SHOW COLUMN_STATS_USAGE;
+```
+
+```
++---------+------------+----------------+-------------+--------------+---------------------+
+| Db_name | Table_name | Partition_name | Column_name | Last_used_at | Last_analyzed_at    |
++---------+------------+----------------+-------------+--------------+---------------------+
+| test    | t1         |                | id          | NULL         | 2024-05-10 11:04:23 |
+| test    | t1         |                | b           | NULL         | 2024-05-10 11:04:23 |
+| test    | t1         |                | pad         | NULL         | 2024-05-10 11:04:23 |
+| test    | t          |                | a           | NULL         | 2024-05-10 11:37:06 |
+| test    | t          |                | b           | NULL         | 2024-05-10 11:37:06 |
++---------+------------+----------------+-------------+--------------+---------------------+
+5 rows in set (0.00 sec)
+```
+
+## MySQL 兼容性
+
+该语句是 TiDB 对 MySQL 语法的扩展。
+
+## 另请参阅
+
+* [`ANALYZE`](/sql-statements/sql-statement-analyze-table.md)
+* [常规统计信息](/statistics.md)
diff --git a/sql-statements/sql-statement-show-stats-buckets.md b/sql-statements/sql-statement-show-stats-buckets.md
@@ -0,0 +1,63 @@
+---
+title: SHOW STATS_BUCKETS
+summary: TiDB 数据库中 SHOW STATS_BUCKETS 的使用概况。
+---
+
+# SHOW STATS_BUCKETS
+
+`SHOW STATS_BUCKETS` 语句显示[常规统计信息](/statistics.md)中桶的信息。
+
+目前，`SHOW STATS_BUCKETS` 语句返回以下列：
+
+| 列名 | 说明   |
+| :-------- | :------------- |
+| `Db_name`  |  数据库名  |
+| `Table_name` | 表名 |
+| `Partition_name` | 分区名 |
+| `Column_name` | 取决于 `Is_index` 值：`Is_index` 为 `0` 时显示列名，为 `1` 时显示索引名 |
+| `Is_index` | 是否是索引列 |
+| `Bucket_id` | 桶的 ID |
+| `Count` | 该桶和之前桶中所有数值的个数 |
+| `Repeats` | 最大值的出现次数 |
+| `Lower_bound` | 最小值 |
+| `Upper_bound` | 最大值 |
+| `Ndv` | 桶中不同值的数量。当 `tidb_analyze_version` = `1` 时，`Ndv` 总是 `0`，没有实际意义。 |
+
+## 语法图
+
+```ebnf+diagram
+ShowStatsBucketsStmt ::=
+    "SHOW" "STATS_BUCKETS" ShowLikeOrWhere?
+ShowLikeOrWhere ::=
+    "LIKE" SimpleExpr
+|   "WHERE" Expression
+```
+
+## 示例
+
+```sql
+SHOW STATS_BUCKETS WHERE Table_name='t';
+```
+
+```
++---------+------------+----------------+-------------+----------+-----------+-------+---------+--------------------------+--------------------------+------+
+| Db_name | Table_name | Partition_name | Column_name | Is_index | Bucket_id | Count | Repeats | Lower_Bound              | Upper_Bound              | Ndv  |
++---------+------------+----------------+-------------+----------+-----------+-------+---------+--------------------------+--------------------------+------+
+| test    | t          |                | a           |        0 |         0 |     1 |       1 | 2023-12-27 00:00:00      | 2023-12-27 00:00:00      |    0 |
+| test    | t          |                | a           |        0 |         1 |     2 |       1 | 2023-12-28 00:00:00      | 2023-12-28 00:00:00      |    0 |
+| test    | t          |                | ia          |        1 |         0 |     1 |       1 | (NULL, 2)                | (NULL, 2)                |    0 |
+| test    | t          |                | ia          |        1 |         1 |     2 |       1 | (NULL, 4)                | (NULL, 4)                |    0 |
+| test    | t          |                | ia          |        1 |         2 |     3 |       1 | (2023-12-27 00:00:00, 1) | (2023-12-27 00:00:00, 1) |    0 |
+| test    | t          |                | ia          |        1 |         3 |     4 |       1 | (2023-12-28 00:00:00, 3) | (2023-12-28 00:00:00, 3) |    0 |
++---------+------------+----------------+-------------+----------+-----------+-------+---------+--------------------------+--------------------------+------+
+6 rows in set (0.00 sec)
+```
+
+## MySQL 兼容性
+
+该语句是 TiDB 对 MySQL 语法的扩展。
+
+## 另请参阅
+
+* [`ANALYZE`](/sql-statements/sql-statement-analyze-table.md)
+* [常规统计信息](/statistics.md)
diff --git a/sql-statements/sql-statement-show-stats-healthy.md b/sql-statements/sql-statement-show-stats-healthy.md
@@ -9,6 +9,15 @@ summary: TiDB 数据库中 SHOW STATS_HEALTHY 的使用概况。
 
 可以通过执行 [`ANALYZE`](/sql-statements/sql-statement-analyze-table.md) 语句来改善表的健康度。当表的健康度下降到低于 [`tidb_auto_analyze_ratio`](/system-variables.md#tidb_auto_analyze_ratio) 时，则会自动执行 `ANALYZE` 语句。
 
+目前，`SHOW STATS_HEALTHY` 语句返回以下列：
+
+| 列名 | 说明            |
+| :-------- | :------------- |
+| `Db_name`  |  数据库名    |
+| `Table_name` | 表名 |
+| `Partition_name`| 分区名 |
+| `Healthy` | 健康度，0~100 之间 |
+
 ## 语法图
 
 ```ebnf+diagram