Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions TOC.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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)
Expand Down
4 changes: 2 additions & 2 deletions extended-statistics.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,8 @@ summary: 了解如何使用扩展统计信息指导优化器。

TiDB 可以收集以下两种类型的统计信息,本文主要介绍如何使用扩展统计信息来指导优化器。阅读本文前,建议先阅读[常规统计信息](/statistics.md)。

- 常规统计信息:例如直方图和 Count-Min Sketch详情参见[常规统计信息](/statistics.md)。
- 扩展统计信息:通过表和列过滤的统计信息
- 常规统计信息:主要关注单个列的统计信息,例如直方图和 Count-Min Sketch。这些统计信息对优化器估算查询成本至关重要。详情参见[常规统计信息](/statistics.md)。
- 扩展统计信息:主要关注指定列之间的数据相关性,指导优化器在查询有相关性的列时更精确地估算查询成本

当手动或自动执行 `ANALYZE` 语句时,TiDB 默认只收集常规统计信息,不收集扩展统计信息。这是因为扩展统计信息仅在特定场景下用于优化器估算,而且收集扩展统计信息会增加额外开销。

Expand Down
2 changes: 1 addition & 1 deletion optimizer-fix-controls.md
Original file line number Diff line number Diff line change
Expand Up @@ -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>

Expand Down
2 changes: 1 addition & 1 deletion partitioned-table.md
Original file line number Diff line number Diff line change
Expand Up @@ -1784,7 +1784,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" >}}

Expand Down
4 changes: 2 additions & 2 deletions releases/release-5.4.0.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 执行同步加载完整统计信息等待多久后会超时。 |
Expand Down Expand Up @@ -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-配置)

### 高可用和容灾

Expand Down
2 changes: 1 addition & 1 deletion releases/release-6.3.0.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 收集完成。该方式确保在切换分区剪裁策略时系统性能保持稳定。

### 易用性

Expand Down
2 changes: 1 addition & 1 deletion releases/release-7.4.0.md
Original file line number Diff line number Diff line change
Expand Up @@ -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` 资源组的后台任务类型以开启后台任务管理。

Expand Down
53 changes: 37 additions & 16 deletions sql-statements/sql-statement-drop-stats.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,34 +11,59 @@ summary: TiDB 数据库中 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 |
+---------+------------+----------------+---------------------+--------------+-----------+
Expand All @@ -47,23 +72,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)
```

Expand Down
18 changes: 17 additions & 1 deletion sql-statements/sql-statement-show-analyze-status.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,22 @@ summary: TiDB 数据库中 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
Expand Down Expand Up @@ -71,4 +87,4 @@ mysql> show analyze status;

## 另请参阅

* [ANALYZE_STATUS 表](/information-schema/information-schema-analyze-status.md)
* [`ANALYZE_STATUS` 表](/information-schema/information-schema-analyze-status.md)
57 changes: 57 additions & 0 deletions sql-statements/sql-statement-show-column-stats-usage.md
Original file line number Diff line number Diff line change
@@ -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)
63 changes: 63 additions & 0 deletions sql-statements/sql-statement-show-stats-buckets.md
Original file line number Diff line number Diff line change
@@ -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)
9 changes: 9 additions & 0 deletions sql-statements/sql-statement-show-stats-healthy.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading
Loading