tidb: document analyze v1 removal

information-schema/information-schema-analyze-status.md

@@ -62,7 +62,7 @@ SELECT * FROM information_schema.analyze_status;
 * `TABLE_SCHEMA`：表所属的数据库的名称。
 * `TABLE_NAME`：表的名称。
 * `PARTITION_NAME`：分区表的名称。
-* `JOB_INFO`：`ANALYZE` 任务的信息。如果分析索引，该信息会包含索引名。当 `tidb_analyze_version = 2` 时，该信息会包含采样率等配置项。
+* `JOB_INFO`：`ANALYZE` 子任务的简要描述。该描述包含 `ANALYZE` 的作用域（例如列、索引或全局统计信息合并），并可能包含实际生效的选项，例如 `buckets`、`topn`、`samplerate` 或 `samples`。
 * `PROCESSED_ROWS`：已经处理的行数。
 * `START_TIME`：`ANALYZE` 任务的开始时间。
 * `END_TIME`：`ANALYZE` 任务的结束时间。

sql-statements/sql-statement-show-analyze-status.md

@@ -21,7 +21,7 @@ aliases: ['/docs-cn/dev/sql-statements/sql-statement-show-analyze-status/']
 | `Table_schema` |  数据库名    |
 | `Table_name` | 表名 |
 | `Partition_name` | 分区名 |
-| `Job_info` | 任务具体信息。当收集索引的统计信息时，该信息会包含索引名。当 `tidb_analyze_version = 2` 时，该信息会包含采样率等配置项。 |
+| `Job_info` | `ANALYZE` 子任务的简要描述。该描述包含 `ANALYZE` 的作用域（例如列、索引或全局统计信息合并），并可能包含实际生效的选项，例如 `buckets`、`topn`、`samplerate` 或 `samples`。
 | `Processed_rows` | 已经 `ANALYZE` 的行数 |
 | `Start_time` | 任务开始执行的时间 |
 | `End_time` | 任务结束执行的时间 |
@@ -40,31 +40,14 @@ ShowLikeOrWhereOpt ::= 'LIKE' SimpleExpr | 'WHERE' Expression
 
 ## 示例
 
+> **注意：**
+>
+> 从 v9.0.0 起，TiDB 不再支持使用统计信息版本 1（`tidb_analyze_version = 1`）收集新的统计信息。以下示例展示了统计信息版本 2 下当前的 `ANALYZE` 行为。
+
 ```sql
 mysql> create table t(x int, index idx(x)) partition by hash(x) partitions 2;
 Query OK, 0 rows affected (0.69 sec)
 
-mysql> set @@tidb_analyze_version = 1;
-Query OK, 0 rows affected (0.00 sec)
-
-mysql> analyze table t;
-Query OK, 0 rows affected (0.20 sec)
-
-mysql> show analyze status;
-+--------------+------------+----------------+-------------------+----------------+---------------------+---------------------+----------+-------------+----------------+------------+------------------+----------+---------------------+
-| Table_schema | Table_name | Partition_name | Job_info          | Processed_rows | Start_time          | End_time            | State    | Fail_reason | Instance       | Process_ID | Remaining_seconds| Progress | Estimated_total_rows|
-+--------------+------------+----------------+-------------------+----------------+---------------------+---------------------+----------+-------------+----------------+------------+------------------+----------+---------------------+
-| test         | t          | p1             | analyze index idx |              0 | 2022-05-27 11:29:46 | 2022-05-27 11:29:46 | finished | NULL        | 127.0.0.1:4000 | NULL       | NULL             | NULL     | NULL                |
-| test         | t          | p0             | analyze index idx |              0 | 2022-05-27 11:29:46 | 2022-05-27 11:29:46 | finished | NULL        | 127.0.0.1:4000 | NULL       | NULL             | NULL     | NULL                |
-| test         | t          | p1             | analyze columns   |              0 | 2022-05-27 11:29:46 | 2022-05-27 11:29:46 | finished | NULL        | 127.0.0.1:4000 | NULL       | NULL             | NULL     | NULL                |
-| test         | t          | p0             | analyze columns   |              0 | 2022-05-27 11:29:46 | 2022-05-27 11:29:46 | finished | NULL        | 127.0.0.1:4000 | NULL       | NULL             | NULL     | NULL                |
-| test         | t1         | p0             | analyze columns   |       28523259 | 2022-05-27 11:29:46 | 2022-05-27 11:29:46 | running  | NULL        | 127.0.0.1:4000 | 690208308  | 0s               | 0.9843   | 28978290            |
-+--------------+------------+----------------+-------------------+----------------+---------------------+---------------------+----------+-------------+----------------+------------+------------------+----------+---------------------+
-4 rows in set (0.01 sec)
-
-mysql> set @@tidb_analyze_version = 2;
-Query OK, 0 rows affected (0.00 sec)
-
 mysql> analyze table t;
 Query OK, 0 rows affected, 2 warnings (0.03 sec)
 
@@ -74,12 +57,8 @@ mysql> show analyze status;
 +--------------+------------+----------------+--------------------------------------------------------------------+----------------+---------------------+---------------------+----------+-------------+----------------+------------+--------------------+----------+----------------------+
 | test         | t          | p1             | analyze table all columns with 256 buckets, 500 topn, 1 samplerate |              0 | 2022-05-27 11:30:12 | 2022-05-27 11:30:12 | finished | NULL        | 127.0.0.1:4000 | NULL       | NULL               | NULL     | NULL                 |
 | test         | t          | p0             | analyze table all columns with 256 buckets, 500 topn, 1 samplerate |              0 | 2022-05-27 11:30:12 | 2022-05-27 11:30:12 | finished | NULL        | 127.0.0.1:4000 | NULL       | NULL               | NULL     | NULL                 |
-| test         | t          | p1             | analyze index idx                                                  |              0 | 2022-05-27 11:29:46 | 2022-05-27 11:29:46 | finished | NULL        | 127.0.0.1:4000 | NULL       | NULL               | NULL     | NULL                 |
-| test         | t          | p0             | analyze index idx                                                  |              0 | 2022-05-27 11:29:46 | 2022-05-27 11:29:46 | finished | NULL        | 127.0.0.1:4000 | NULL       | NULL               | NULL     | NULL                 |
-| test         | t          | p1             | analyze columns                                                    |              0 | 2022-05-27 11:29:46 | 2022-05-27 11:29:46 | finished | NULL        | 127.0.0.1:4000 | NULL       | NULL               | NULL     | NULL                 |
-| test         | t          | p0             | analyze columns                                                    |              0 | 2022-05-27 11:29:46 | 2022-05-27 11:29:46 | finished | NULL        | 127.0.0.1:4000 | NULL       | NULL               | NULL     | NULL                 |
 +--------------+------------+----------------+--------------------------------------------------------------------+----------------+---------------------+---------------------+----------+-------------+----------------+------------+--------------------+----------+----------------------+
-6 rows in set (0.00 sec)
+2 rows in set (0.00 sec)
 ```
 
 ## MySQL 兼容性

statistics.md

@@ -267,7 +267,7 @@ TiDB 会使用最新的 `ANALYZE` 语句中指定的配置覆盖先前记录的
 
 ### 关闭 `ANALYZE` 配置持久化
 
-如果要关闭 `ANALYZE` 配置持久化功能，请将系统变量 `tidb_persist_analyze_options` 设置为 `OFF`。此外，由于 `ANALYZE` 配置持久化功能在 `tidb_analyze_version = 1` 的情况下不适用，因此设置 `tidb_analyze_version = 1` 同样会达到关闭配置持久化的效果。
+如需关闭 `ANALYZE` 配置持久化功能，请将系统变量 `tidb_persist_analyze_options` 设置为 `OFF`。
 
 关闭 `ANALYZE` 配置持久化功能后，已持久化的配置记录不会被清除。因此，当再次开启该功能时，TiDB 会继续使用之前记录的持久化配置收集统计信息。
 
@@ -321,13 +321,19 @@ SHOW COLUMN_STATS_USAGE WHERE db_name = 'test' AND table_name = 't' AND last_ana
 
 ## 统计信息版本
 
-系统变量 [`tidb_analyze_version`](/system-variables.md#tidb_analyze_version-从-v510-版本开始引入) 用于控制 TiDB 收集统计信息的行为。目前 TiDB 支持两个版本的统计信息，即 `tidb_analyze_version = 1` 和 `tidb_analyze_version = 2`。
+系统变量 [`tidb_analyze_version`](/system-variables.md#tidb_analyze_version-从-v510-版本开始引入) 用于控制 TiDB 收集统计信息的行为。
 
-- 从 v5.3.0 开始，变量 `tidb_analyze_version` 的默认值从 `1` 变为了 `2`。
-- 如果从 v5.3.0 之前版本的集群升级至 v5.3.0 或之后的版本，该变量的默认值不会发生变化。
-<!-- - TiDB Cloud 中，从 v6.5.0 开始，该变量的默认值从 `1` 变为了 `2`。-->
+在 v9.0.0 之前，TiDB 在收集新的统计信息时支持两个统计信息版本：Version 1（`tidb_analyze_version = 1`）和 Version 2（`tidb_analyze_version = 2`）。从 v9.0.0 开始，TiDB 不再支持使用 Version 1（`tidb_analyze_version = 1`）收集新的统计信息，仅支持使用 Version 2（`tidb_analyze_version = 2`）收集新的统计信息。
 
-更推荐选择 Version 2。Version 2 将继续增强，并最终完全取代 Version 1。与 Version 1 相比，Version 2 提高了大数据量场景下多项统计信息收集的准确性。此外，Version 2 在进行谓词选择率估算时不再需要收集 Count-Min Sketch 统计信息，并支持仅对选定列进行自动收集（参见[收集部分列的统计信息](#收集部分列的统计信息)），从而提高了收集性能。
+> **警告：**
+>
+> 如果你的 TiDB 集群是从更早版本升级而来的，并且集群中依然存在升级前已收集到的 Version 1 统计信息，出于升级兼容性考虑，TiDB 仍然可以读取这些 Version 1 统计信息。但是，TiDB 已无法再使用 Version 1 收集新的统计信息。建议你使用 Statistics Version 2（`tidb_analyze_version = 2`），并将[使用 Statistics Version 1 的现有对象迁移到 Version 2](#切换统计信息版本)。
+
+- 对于 TiDB Self-Managed，从 v5.3.0 开始，该变量的默认值从 `1` 变为 `2`。
+- 对于 TiDB Cloud，从 v6.5.0 开始，该变量的默认值从 `1` 变为 `2`。
+- 如果要升级的集群已经持久化 `tidb_analyze_version = 1` 配置，TiDB 会在升级过程中将持久化的全局值重写为 `2`。
+
+更推荐选择 Version 2。与 Version 1 相比，Version 2 提高了大数据量场景下多项统计信息的准确性。此外，Version 2 在进行谓词选择率估算时不再需要收集 Count-Min sketch 统计信息，并支持仅对选定列进行自动收集（参见[收集部分列的统计信息](#收集部分列的统计信息)），从而提高了收集性能。目前，TiDB 仅支持使用 Statistics Version 2 收集新的统计信息。
 
 以下表格列出了两个统计信息版本为优化器估算收集的信息：
 
@@ -342,29 +348,22 @@ SHOW COLUMN_STATS_USAGE WHERE db_name = 'test' AND table_name = 't' AND last_ana
 
 ### 切换统计信息版本
 
-建议确保所有表、索引（和分区）使用相同版本的统计信息收集功能。推荐使用 Version 2，但不建议在没有正当理由（例如使用中的版本出现问题）的情况下切换版本。版本之间的切换可能需要一段时间，在此期间可能没有统计信息，直到所有表都使用了新版本进行统计。如果没有统计信息，可能会影响优化器的计划选择。
+建议所有表、索引和分区使用相同版本的统计信息。如果你的集群仍在使用 Statistics Version 1，请尽快迁移到 Statistics Version 2。在某个对象（例如表、索引或分区）收集到 Version 2 统计信息之前，TiDB 会继续使用该对象现有的 Version 1 统计信息。
 
-切换版本的正当理由可能包括：使用 Version 1 在收集 Count-Min Sketch 统计信息时，由于哈希冲突导致等值查询或 `IN` 查询谓词估算不准确。此时，你可以参考 [Count-Min Sketch](#count-min-sketch) 小节中描述的解决方案，或者设置 `tidb_analyze_version = 2` 并对所有对象重新运行 `ANALYZE`。在 Version 2 的早期阶段，执行 `ANALYZE` 后有内存溢出的风险，现在这个问题已经解决，但最初的解决方案是设置 `tidb_analyze_version = 1` 并对所有对象重新运行 `ANALYZE`。
+迁移的一个主要原因是，使用 Version 1 在收集 Count-Min Sketch 统计信息时，由于哈希冲突会导致等值查询或 IN 查询谓词估算不准确。更多信息请参见 [Count-Min Sketch](#count-min-sketch)。为避免此问题，请设置 `tidb_analyze_version = 2` 并对所有对象重新运行 `ANALYZE`。
 
-要为切换统计信息版本做好 `ANALYZE` 准备，请根据情况进行以下操作：
+要为从 Statistics Version 1 迁移到 Statistics Version 2 做好 `ANALYZE` 准备，请根据情况进行以下操作：
 
 - 如果 `ANALYZE` 语句是手动执行的，请手动统计每张需要统计的表：
 
     ```sql
     SELECT DISTINCT(CONCAT('ANALYZE TABLE ', table_schema, '.', table_name, ';'))
     FROM information_schema.tables JOIN mysql.stats_histograms
     ON table_id = tidb_table_id
-    WHERE stats_ver = 2;
+    WHERE stats_ver = 1;
     ```
 
-- 如果 `ANALYZE` 语句是由 TiDB 自动执行的（当开启自动更新统计信息时），请执行以下语句生成 [`DROP STATS`](/sql-statements/sql-statement-drop-stats.md) 语句：
-
-    ```sql
-    SELECT DISTINCT(CONCAT('DROP STATS ', table_schema, '.', table_name, ';'))
-    FROM information_schema.tables JOIN mysql.stats_histograms
-    ON table_id = tidb_table_id
-    WHERE stats_ver = 2;
-    ```
+- 如果 `ANALYZE` 语句是由 TiDB 自动执行的（当开启自动更新统计信息时），在你设置 `tidb_analyze_version = 2` 后，TiDB 会通过后续的自动分析逐步将统计信息刷新为 Version 2。在某个对象收集到 Version 2 统计信息之前，TiDB 仍然可以继续使用其现有的 Version 1 统计信息。为了加快重要对象的迁移速度，你可以手动对这些对象运行 `ANALYZE`。
 
 - 如果上一条语句的返回结果太长，不方便复制粘贴，可以将结果导出到临时文件后，再执行：
 

system-variables.md

@@ -1048,14 +1048,20 @@ MPP 是 TiFlash 引擎提供的分布式计算框架，允许节点之间的数
 
 ### `tidb_analyze_version` <span class="version-mark">从 v5.1.0 版本开始引入</span>
 
+> **警告：**
+>
+> 从 v9.0.0 起，TiDB 不再支持使用统计信息版本 1（`tidb_analyze_version = 1`）收集新的统计信息。如果你尝试将此变量设置为 `1`，TiDB 会返回错误。出于升级兼容性考虑，TiDB 仍支持读取现有的版本 1 的统计信息，但所有新的 `ANALYZE` 操作都使用统计信息版本 2（`tidb_analyze_version = 2`）。建议使用 `tidb_analyze_version = 2`。
+
 - 作用域：SESSION | GLOBAL
 - 是否持久化到集群：是
 - 是否受 Hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value) 控制：否
 - 类型：整数型
 - 默认值：`2`
-- 范围：`[1, 2]`
 - 这个变量用于控制 TiDB 收集统计信息的行为。
-- 在 v5.3.0 及之后的版本中，该变量的默认值为 `2`，具体可参照[常规统计信息](/statistics.md)文档。如果从 v5.3.0 之前版本的集群升级至 v5.3.0 及之后的版本，`tidb_analyze_version` 的默认值不发生变化。
+    - 对于 TiDB Self-Managed，从 v5.3.0 开始，此变量的默认值已从 `1` 更改为 `2`。
+    - 对于 TiDB Cloud，从 v6.5.0 开始，此变量的默认值已从 `1` 更改为 `2`。
+    - 如果要升级的集群已经持久化 `tidb_analyze_version = 1` 配置，TiDB 会在升级期间将持久化的全局值重写为 `2`。请注意，升级后，现有的版本 1 统计信息不会自动转换为版本 2 统计信息。建议你[将使用统计信息版本 1 的现有对象迁移到版本 2](/statistics.md#切换统计信息版本)。
+- 关于此变量的详细介绍，参见[统计信息简介](/statistics.md)。
 
 ### `tidb_analyze_skip_column_types` <span class="version-mark">从 v7.2.0 版本开始引入</span>