From 3e74bc5e8a269a38181b3fe7267721506a9478e3 Mon Sep 17 00:00:00 2001 From: Yang Keao Date: Wed, 9 Sep 2026 19:20:31 +0800 Subject: [PATCH 1/8] docs: document TTL index scan --- system-variable-reference.md | 7 +++++++ system-variables.md | 9 +++++++++ time-to-live.md | 26 +++++++++++++++++++++++++- 3 files changed, 41 insertions(+), 1 deletion(-) diff --git a/system-variable-reference.md b/system-variable-reference.md index e5838d4a58ae..b7a2806a0978 100644 --- a/system-variable-reference.md +++ b/system-variable-reference.md @@ -3992,6 +3992,13 @@ summary: 查看 TiDB 所有的系统变量，以及引用这些变量的文档 - [TiDB 7.1.6 Release Notes](/releases/release-7.1.6.md) - [TiDB 6.5.0 Release Notes](/releases/release-6.5.0.md) +### tidb_ttl_enable_index_scan + +引用该变量的文档： + +- [使用 TTL (Time to Live) 定期删除过期数据](/time-to-live.md) +- [系统变量](/system-variables.md#tidb_ttl_enable_index_scan) + ### tidb_ttl_job_enable 引用该变量的文档： diff --git a/system-variables.md b/system-variables.md index 01ab57207cee..615331bc34d0 100644 --- a/system-variables.md +++ b/system-variables.md @@ -5835,6 +5835,15 @@ Query OK, 0 rows affected, 1 warning (0.00 sec) - 范围：`[1, 256]` - 这个变量用于设置每个 TiDB 节点上 TTL 删除任务的最大并发数。更多信息，请参考 [Time to Live](/time-to-live.md)。 +### `tidb_ttl_enable_index_scan` + +- 作用域：GLOBAL +- 是否持久化到集群：是 +- 是否受 Hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value) 控制：否 +- 默认值：`ON` +- 类型：布尔型 +- 这个变量用于控制新创建的 TTL 任务是否可以使用以 TTL 列开头且符合条件的二级索引或非聚簇主键索引。设置为 `OFF` 时，新创建的 TTL 任务按照表键顺序扫描。修改该变量不会改变正在运行的 TTL 子任务的扫描路径。有关索引适用条件和滚动升级期间的行为，请参考[使用索引扫描过期行](/time-to-live.md#使用索引扫描过期行)。 + ### `tidb_ttl_job_enable` 从 v6.5.0 版本开始引入 - 作用域：GLOBAL diff --git a/time-to-live.md b/time-to-live.md index be5496401307..a33d9d6e7986 100644 --- a/time-to-live.md +++ b/time-to-live.md @@ -140,6 +140,30 @@ ALTER TABLE orders TTL_JOB_INTERVAL = '48h'; TiDB 还会在集群级别限制并发执行的 TTL 子任务数量。你可以通过修改系统变量 [`tidb_ttl_running_tasks`](/system-variables.md#tidb_ttl_running_tasks-从-v700-版本开始引入) 来设置最大并发数量。 +### 使用索引扫描过期行 + +默认情况下，TiDB 使用以 TTL 列开头且符合条件的索引扫描过期行。与按照表键顺序扫描相比，按照 TTL 列顺序扫描可以避免重复扫描尚未过期的索引项。TiDB 根据所选索引的 TiKV Region 拆分任务，完全位于过期时间边界之后的 Region 不参与任务。 + +该行为由全局变量 [`tidb_ttl_enable_index_scan`](/system-variables.md#tidb_ttl_enable_index_scan) 控制，默认开启。当关闭该变量或没有符合条件的索引时，TiDB 会回退到按照表键顺序扫描，并阻止优化器为该扫描选择二级索引。 + +TTL 任务使用的索引必须满足以下全部条件： + +- 索引是 public、可见且局部的二级索引或非聚簇主键索引。聚簇主键索引、全局索引、多值索引、列式索引和条件索引不符合条件。 +- 索引的第一列是 TTL 列，并且每个索引列都存储可见表列的完整值。前缀索引和包含隐藏表达式列的索引不符合条件。 +- 索引能提供稳定且唯一的分页顺序。对于唯一复合索引，除 TTL 列之外的每个索引列都必须为 `NOT NULL`。对于非唯一索引，声明的索引列必须包含完整表键或完全不包含表键。如果完全不包含表键，且 TiDB 支持相应的物理顺序，TiDB 会将隐式表键追加到分页顺序中。 +- 最终用于分页的列不包含 `SET`、`FLOAT` 或 `DOUBLE` 类型的列。 + +这里的表键是聚簇主键；对于没有聚簇主键的表，表键是 `_tidb_rowid`。仅包含复合表键中部分列的非唯一索引不符合条件。无符号整数聚簇主键以及包含前缀主键列的 common handle 不能用作隐式后缀，但如果索引显式包含完整表键，该索引仍然可能符合条件。 + +如果存在多个符合条件的索引，TiDB 依次优先选择仅包含 TTL 列的单列索引、显式包含完整表键的索引，以及分页元组最短的索引。如果分页元组长度相同，TiDB 优先选择需要读取列数更少的索引。 + +> **注意：** +> +> - 在滚动升级期间，如果某张表原本会使用索引扫描，但集群中 TiDB server 的构建版本不一致，TiDB 不会为该表创建新的 TTL 任务。TiDB server 的构建版本一致后，调度器会重试。如需在升级期间继续使用表键扫描创建 TTL 任务，请临时关闭 `tidb_ttl_enable_index_scan`。 +> - 如果 TiDB 无法获取或比较 TiDB server 信息，则使用表键扫描创建任务。 +> - 如果在创建 TTL 任务后删除所选索引，受影响的子任务会报错。后续 TTL 任务可以选择另一个符合条件的索引，或回退到表键扫描。 +> - 每个扫描分页都是独立的 SQL 语句。如果在扫描期间更新索引列的值，当前任务可能跳过该行或再次读到该行。删除前，TiDB 会再次检查过期条件，因此不会删除不再过期的行。当前任务跳过的过期行仍可由后续 TTL 任务处理。 + 如果想禁止 TTL 任务的执行，除了可以设置表属性 `TTL_ENABLE='OFF'` 外，也可以通过设置全局变量 `tidb_ttl_job_enable` 关闭整个集群的 TTL 任务的执行。 ```sql @@ -193,7 +217,7 @@ TiDB 会定时采集 TTL 的运行时信息，并在 Grafana 中提供了相关 列 `{last, current}_job_{start_time, finish_time, ttl_expire}` 分别描述了过去和当前 TTL 任务的开始时间、结束时间和过期时间。`last_job_summary` 列描述了上一次 TTL 任务的执行情况，包括总行数、成功行数、失败行数。 -+ `mysql.tidb_ttl_task` 表中包含了正在执行的 TTL 子任务。单个 TTL 任务会被拆分为多个子任务，该表中记录了正在执行的这些子任务的信息。 ++ `mysql.tidb_ttl_task` 表中包含了正在执行的 TTL 子任务。单个 TTL 任务会被拆分为多个子任务，该表中记录了正在执行的这些子任务的信息。`scan_index_id` 列表示创建任务时选择的扫描路径。非 `NULL` 值是所选索引的 ID，`NULL` 表示该子任务按照表键顺序扫描。 + `mysql.tidb_ttl_job_history` 表中记录了 TTL 任务的执行历史。TTL 任务的历史记录将被保存 90 天。以一行为例： ```sql From c4e4490f4346dbfddf2aec5cd9753f1b4b6f58c7 Mon Sep 17 00:00:00 2001 From: Yang Keao Date: Wed, 9 Sep 2026 19:48:11 +0800 Subject: [PATCH 2/8] docs: simplify TTL index scan requirements --- system-variables.md | 2 +- time-to-live.md | 24 ++++++++---------------- 2 files changed, 9 insertions(+), 17 deletions(-) diff --git a/system-variables.md b/system-variables.md index 615331bc34d0..e73f51df3161 100644 --- a/system-variables.md +++ b/system-variables.md @@ -5842,7 +5842,7 @@ Query OK, 0 rows affected, 1 warning (0.00 sec) - 是否受 Hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value) 控制：否 - 默认值：`ON` - 类型：布尔型 -- 这个变量用于控制新创建的 TTL 任务是否可以使用以 TTL 列开头且符合条件的二级索引或非聚簇主键索引。设置为 `OFF` 时，新创建的 TTL 任务按照表键顺序扫描。修改该变量不会改变正在运行的 TTL 子任务的扫描路径。有关索引适用条件和滚动升级期间的行为，请参考[使用索引扫描过期行](/time-to-live.md#使用索引扫描过期行)。 +- 这个变量用于控制 TTL 任务是否可以使用以 TTL 列开头且符合条件的二级索引或非聚簇主键索引。设置为 `OFF` 时，TTL 任务按照表键顺序扫描。有关索引适用条件，请参考[使用索引扫描过期行](/time-to-live.md#使用索引扫描过期行)。 ### `tidb_ttl_job_enable` 从 v6.5.0 版本开始引入 diff --git a/time-to-live.md b/time-to-live.md index a33d9d6e7986..a31762ee0db7 100644 --- a/time-to-live.md +++ b/time-to-live.md @@ -142,27 +142,19 @@ TiDB 还会在集群级别限制并发执行的 TTL 子任务数量。你可以 ### 使用索引扫描过期行 -默认情况下，TiDB 使用以 TTL 列开头且符合条件的索引扫描过期行。与按照表键顺序扫描相比，按照 TTL 列顺序扫描可以避免重复扫描尚未过期的索引项。TiDB 根据所选索引的 TiKV Region 拆分任务，完全位于过期时间边界之后的 Region 不参与任务。 +默认情况下，TiDB 使用以 TTL 列开头且符合条件的索引扫描过期行，从而避免扫描尚未过期的索引项。TiDB 根据所选索引的 Region 拆分任务，完全位于过期时间边界之后的 Region 不会生成任务。 该行为由全局变量 [`tidb_ttl_enable_index_scan`](/system-variables.md#tidb_ttl_enable_index_scan) 控制，默认开启。当关闭该变量或没有符合条件的索引时，TiDB 会回退到按照表键顺序扫描，并阻止优化器为该扫描选择二级索引。 -TTL 任务使用的索引必须满足以下全部条件： +符合条件的索引必须满足以下要求： -- 索引是 public、可见且局部的二级索引或非聚簇主键索引。聚簇主键索引、全局索引、多值索引、列式索引和条件索引不符合条件。 -- 索引的第一列是 TTL 列，并且每个索引列都存储可见表列的完整值。前缀索引和包含隐藏表达式列的索引不符合条件。 -- 索引能提供稳定且唯一的分页顺序。对于唯一复合索引，除 TTL 列之外的每个索引列都必须为 `NOT NULL`。对于非唯一索引，声明的索引列必须包含完整表键或完全不包含表键。如果完全不包含表键，且 TiDB 支持相应的物理顺序，TiDB 会将隐式表键追加到分页顺序中。 -- 最终用于分页的列不包含 `SET`、`FLOAT` 或 `DOUBLE` 类型的列。 +- 索引是可见的二级索引或非聚簇主键索引，且第一列是 TTL 列。 +- 每个索引列都索引完整的列值，不使用前缀索引或表达式索引。 +- 对于唯一复合索引，除 TTL 列之外的其他列都为 `NOT NULL`。 +- 对于非唯一索引，TiDB 必须能将数据行标识追加到扫描顺序中。在索引中包含全部主键列即可满足该要求；不支持仅包含复合主键中的部分列。 +- 用于标识数据行的列不是 `SET`、`FLOAT` 或 `DOUBLE` 类型。 -这里的表键是聚簇主键；对于没有聚簇主键的表，表键是 `_tidb_rowid`。仅包含复合表键中部分列的非唯一索引不符合条件。无符号整数聚簇主键以及包含前缀主键列的 common handle 不能用作隐式后缀，但如果索引显式包含完整表键，该索引仍然可能符合条件。 - -如果存在多个符合条件的索引，TiDB 依次优先选择仅包含 TTL 列的单列索引、显式包含完整表键的索引，以及分页元组最短的索引。如果分页元组长度相同，TiDB 优先选择需要读取列数更少的索引。 - -> **注意：** -> -> - 在滚动升级期间，如果某张表原本会使用索引扫描，但集群中 TiDB server 的构建版本不一致，TiDB 不会为该表创建新的 TTL 任务。TiDB server 的构建版本一致后，调度器会重试。如需在升级期间继续使用表键扫描创建 TTL 任务，请临时关闭 `tidb_ttl_enable_index_scan`。 -> - 如果 TiDB 无法获取或比较 TiDB server 信息，则使用表键扫描创建任务。 -> - 如果在创建 TTL 任务后删除所选索引，受影响的子任务会报错。后续 TTL 任务可以选择另一个符合条件的索引，或回退到表键扫描。 -> - 每个扫描分页都是独立的 SQL 语句。如果在扫描期间更新索引列的值，当前任务可能跳过该行或再次读到该行。删除前，TiDB 会再次检查过期条件，因此不会删除不再过期的行。当前任务跳过的过期行仍可由后续 TTL 任务处理。 +TTL 任务不使用聚簇主键索引、部分索引、全局索引、多值索引、列式索引或不可见索引。 如果想禁止 TTL 任务的执行，除了可以设置表属性 `TTL_ENABLE='OFF'` 外，也可以通过设置全局变量 `tidb_ttl_job_enable` 关闭整个集群的 TTL 任务的执行。 From e912138be0982ca5f3a7f13b9d18a5f30a0639d0 Mon Sep 17 00:00:00 2001 From: Yang Keao Date: Wed, 9 Sep 2026 19:54:04 +0800 Subject: [PATCH 3/8] docs: clarify eligible TTL indexes --- time-to-live.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/time-to-live.md b/time-to-live.md index a31762ee0db7..250d2c216a24 100644 --- a/time-to-live.md +++ b/time-to-live.md @@ -142,20 +142,18 @@ TiDB 还会在集群级别限制并发执行的 TTL 子任务数量。你可以 ### 使用索引扫描过期行 -默认情况下，TiDB 使用以 TTL 列开头且符合条件的索引扫描过期行，从而避免扫描尚未过期的索引项。TiDB 根据所选索引的 Region 拆分任务，完全位于过期时间边界之后的 Region 不会生成任务。 +默认情况下，TiDB 使用以 TTL 列开头且符合条件的索引扫描过期行，从而避免扫描尚未过期的索引项。 该行为由全局变量 [`tidb_ttl_enable_index_scan`](/system-variables.md#tidb_ttl_enable_index_scan) 控制，默认开启。当关闭该变量或没有符合条件的索引时，TiDB 会回退到按照表键顺序扫描，并阻止优化器为该扫描选择二级索引。 符合条件的索引必须满足以下要求： -- 索引是可见的二级索引或非聚簇主键索引，且第一列是 TTL 列。 -- 每个索引列都索引完整的列值，不使用前缀索引或表达式索引。 +- 索引是可见的二级索引或非聚簇主键索引，不是部分索引、全局索引、多值索引或列式索引。 +- 索引的第一列是 TTL 列，且每个索引列都索引完整的列值，不使用前缀索引或表达式索引。 - 对于唯一复合索引，除 TTL 列之外的其他列都为 `NOT NULL`。 -- 对于非唯一索引，TiDB 必须能将数据行标识追加到扫描顺序中。在索引中包含全部主键列即可满足该要求；不支持仅包含复合主键中的部分列。 +- 非唯一索引包含全部主键列或完全不包含主键列。 - 用于标识数据行的列不是 `SET`、`FLOAT` 或 `DOUBLE` 类型。 -TTL 任务不使用聚簇主键索引、部分索引、全局索引、多值索引、列式索引或不可见索引。 - 如果想禁止 TTL 任务的执行，除了可以设置表属性 `TTL_ENABLE='OFF'` 外，也可以通过设置全局变量 `tidb_ttl_job_enable` 关闭整个集群的 TTL 任务的执行。 ```sql From 2ea934153bd97bce2aaca437ad838eb1b3fe266f Mon Sep 17 00:00:00 2001 From: Yang Keao Date: Thu, 10 Sep 2026 13:16:56 +0800 Subject: [PATCH 4/8] docs: clarify TTL index column type limits --- time-to-live.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/time-to-live.md b/time-to-live.md index 250d2c216a24..350bec6b693f 100644 --- a/time-to-live.md +++ b/time-to-live.md @@ -152,7 +152,7 @@ TiDB 还会在集群级别限制并发执行的 TTL 子任务数量。你可以 - 索引的第一列是 TTL 列，且每个索引列都索引完整的列值，不使用前缀索引或表达式索引。 - 对于唯一复合索引，除 TTL 列之外的其他列都为 `NOT NULL`。 - 非唯一索引包含全部主键列或完全不包含主键列。 -- 用于标识数据行的列不是 `SET`、`FLOAT` 或 `DOUBLE` 类型。 +- 索引列不能是 `SET`、`FLOAT` 或 `DOUBLE` 类型。对于不包含主键列的非唯一索引，主键列也不能是这些类型。 如果想禁止 TTL 任务的执行，除了可以设置表属性 `TTL_ENABLE='OFF'` 外，也可以通过设置全局变量 `tidb_ttl_job_enable` 关闭整个集群的 TTL 任务的执行。 From 5cf35a338e51d35ac94875329402dc4d35e9b17f Mon Sep 17 00:00:00 2001 From: Yang Keao Date: Thu, 10 Sep 2026 14:27:54 +0800 Subject: [PATCH 5/8] docs: document additional TTL index restrictions --- system-variables.md | 2 +- time-to-live.md | 10 +++++++--- 2 files changed, 8 insertions(+), 4 deletions(-) diff --git a/system-variables.md b/system-variables.md index e73f51df3161..150ef7514490 100644 --- a/system-variables.md +++ b/system-variables.md @@ -5842,7 +5842,7 @@ Query OK, 0 rows affected, 1 warning (0.00 sec) - 是否受 Hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value) 控制：否 - 默认值：`ON` - 类型：布尔型 -- 这个变量用于控制 TTL 任务是否可以使用以 TTL 列开头且符合条件的二级索引或非聚簇主键索引。设置为 `OFF` 时，TTL 任务按照表键顺序扫描。有关索引适用条件，请参考[使用索引扫描过期行](/time-to-live.md#使用索引扫描过期行)。 +- 这个变量用于控制 TTL 任务是否可以使用以 TTL 列开头且符合条件的二级索引或非聚簇主键。设置为 `OFF` 时，TTL 任务按照表键顺序扫描。有关索引适用条件，请参考[使用索引扫描过期行](/time-to-live.md#使用索引扫描过期行)。 ### `tidb_ttl_job_enable` 从 v6.5.0 版本开始引入 diff --git a/time-to-live.md b/time-to-live.md index 350bec6b693f..fe4b402175b7 100644 --- a/time-to-live.md +++ b/time-to-live.md @@ -148,10 +148,14 @@ TiDB 还会在集群级别限制并发执行的 TTL 子任务数量。你可以 符合条件的索引必须满足以下要求： -- 索引是可见的二级索引或非聚簇主键索引，不是部分索引、全局索引、多值索引或列式索引。 +- 索引是二级索引或非聚簇主键。TiDB 不使用聚簇主键、部分索引、全局索引、多值索引、向量搜索索引、全文索引或不可见索引进行该扫描。 - 索引的第一列是 TTL 列，且每个索引列都索引完整的列值，不使用前缀索引或表达式索引。 -- 对于唯一复合索引，除 TTL 列之外的其他列都为 `NOT NULL`。 -- 非唯一索引包含全部主键列或完全不包含主键列。 +- 对于包含多列的唯一索引，除 TTL 列之外的其他列都为 `NOT NULL`。 +- 非唯一索引满足以下要求： + - 索引包含全部主键列或完全不包含主键列，不能只包含复合主键中的部分列。 + - 如果表的聚簇主键由单个无符号整数列组成，索引必须包含该主键列。 + - 如果聚簇主键中的任意列指定了前缀长度，索引必须包含全部主键列。 + - 如果集群启用了[新排序规则框架](/character-set-and-collation.md#新框架下的排序规则支持)，对于由较早 TiDB 版本创建且聚簇主键包含非二进制字符串列的表，请在索引中包含全部主键列，以避免兼容性限制。 - 索引列不能是 `SET`、`FLOAT` 或 `DOUBLE` 类型。对于不包含主键列的非唯一索引，主键列也不能是这些类型。 如果想禁止 TTL 任务的执行，除了可以设置表属性 `TTL_ENABLE='OFF'` 外，也可以通过设置全局变量 `tidb_ttl_job_enable` 关闭整个集群的 TTL 任务的执行。 From b5155b7388078845571f28f263678e7aef71c854 Mon Sep 17 00:00:00 2001 From: Yang Keao Date: Thu, 10 Sep 2026 14:36:12 +0800 Subject: [PATCH 6/8] docs: simplify TTL index compatibility requirement --- time-to-live.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/time-to-live.md b/time-to-live.md index fe4b402175b7..1787ad03ee74 100644 --- a/time-to-live.md +++ b/time-to-live.md @@ -155,7 +155,7 @@ TiDB 还会在集群级别限制并发执行的 TTL 子任务数量。你可以 - 索引包含全部主键列或完全不包含主键列，不能只包含复合主键中的部分列。 - 如果表的聚簇主键由单个无符号整数列组成，索引必须包含该主键列。 - 如果聚簇主键中的任意列指定了前缀长度，索引必须包含全部主键列。 - - 如果集群启用了[新排序规则框架](/character-set-and-collation.md#新框架下的排序规则支持)，对于由较早 TiDB 版本创建且聚簇主键包含非二进制字符串列的表，请在索引中包含全部主键列，以避免兼容性限制。 + - 对于由较早 TiDB 版本创建且聚簇主键包含非二进制字符串列的表，索引必须包含全部主键列。 - 索引列不能是 `SET`、`FLOAT` 或 `DOUBLE` 类型。对于不包含主键列的非唯一索引，主键列也不能是这些类型。 如果想禁止 TTL 任务的执行，除了可以设置表属性 `TTL_ENABLE='OFF'` 外，也可以通过设置全局变量 `tidb_ttl_job_enable` 关闭整个集群的 TTL 任务的执行。 From dc751e97c827c51fba9d06337f208d284740afba Mon Sep 17 00:00:00 2001 From: Yang Keao Date: Thu, 10 Sep 2026 14:50:31 +0800 Subject: [PATCH 7/8] docs: remove unsupported legacy TTL restriction --- time-to-live.md | 1 - 1 file changed, 1 deletion(-) diff --git a/time-to-live.md b/time-to-live.md index 1787ad03ee74..1b67f6a27559 100644 --- a/time-to-live.md +++ b/time-to-live.md @@ -155,7 +155,6 @@ TiDB 还会在集群级别限制并发执行的 TTL 子任务数量。你可以 - 索引包含全部主键列或完全不包含主键列，不能只包含复合主键中的部分列。 - 如果表的聚簇主键由单个无符号整数列组成，索引必须包含该主键列。 - 如果聚簇主键中的任意列指定了前缀长度，索引必须包含全部主键列。 - - 对于由较早 TiDB 版本创建且聚簇主键包含非二进制字符串列的表，索引必须包含全部主键列。 - 索引列不能是 `SET`、`FLOAT` 或 `DOUBLE` 类型。对于不包含主键列的非唯一索引，主键列也不能是这些类型。 如果想禁止 TTL 任务的执行，除了可以设置表属性 `TTL_ENABLE='OFF'` 外，也可以通过设置全局变量 `tidb_ttl_job_enable` 关闭整个集群的 TTL 任务的执行。 From 04788807fa39af423cdfd695ef4305f4dc2ba846 Mon Sep 17 00:00:00 2001 From: Yang Keao Date: Thu, 10 Sep 2026 16:31:33 +0800 Subject: [PATCH 8/8] clarify TTL index scan requirements --- system-variables.md | 2 +- time-to-live.md | 10 +++++----- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/system-variables.md b/system-variables.md index 150ef7514490..e73f51df3161 100644 --- a/system-variables.md +++ b/system-variables.md @@ -5842,7 +5842,7 @@ Query OK, 0 rows affected, 1 warning (0.00 sec) - 是否受 Hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value) 控制：否 - 默认值：`ON` - 类型：布尔型 -- 这个变量用于控制 TTL 任务是否可以使用以 TTL 列开头且符合条件的二级索引或非聚簇主键。设置为 `OFF` 时，TTL 任务按照表键顺序扫描。有关索引适用条件，请参考[使用索引扫描过期行](/time-to-live.md#使用索引扫描过期行)。 +- 这个变量用于控制 TTL 任务是否可以使用以 TTL 列开头且符合条件的二级索引或非聚簇主键索引。设置为 `OFF` 时，TTL 任务按照表键顺序扫描。有关索引适用条件，请参考[使用索引扫描过期行](/time-to-live.md#使用索引扫描过期行)。 ### `tidb_ttl_job_enable` 从 v6.5.0 版本开始引入 diff --git a/time-to-live.md b/time-to-live.md index 1b67f6a27559..a8fed3720b48 100644 --- a/time-to-live.md +++ b/time-to-live.md @@ -142,14 +142,14 @@ TiDB 还会在集群级别限制并发执行的 TTL 子任务数量。你可以 ### 使用索引扫描过期行 -默认情况下，TiDB 使用以 TTL 列开头且符合条件的索引扫描过期行，从而避免扫描尚未过期的索引项。 +要使用索引扫描，TTL 列必须是索引的第一列。这样，TiDB 可以直接扫描可能包含过期行的索引范围，而不必扫描尚未过期的索引项。 -该行为由全局变量 [`tidb_ttl_enable_index_scan`](/system-variables.md#tidb_ttl_enable_index_scan) 控制，默认开启。当关闭该变量或没有符合条件的索引时，TiDB 会回退到按照表键顺序扫描，并阻止优化器为该扫描选择二级索引。 +默认情况下，TiDB 会自动选择一个符合条件的索引进行扫描。该行为由全局变量 [`tidb_ttl_enable_index_scan`](/system-variables.md#tidb_ttl_enable_index_scan) 控制，默认开启。当关闭该变量或没有符合条件的索引时，TiDB 会回退到按照表键顺序扫描，并阻止优化器为该扫描选择二级索引。对于使用聚簇主键的表，表键扫描会使用该聚簇主键。 -符合条件的索引必须满足以下要求： +除 TTL 列位于首位外，符合条件的索引还必须满足以下要求： -- 索引是二级索引或非聚簇主键。TiDB 不使用聚簇主键、部分索引、全局索引、多值索引、向量搜索索引、全文索引或不可见索引进行该扫描。 -- 索引的第一列是 TTL 列，且每个索引列都索引完整的列值，不使用前缀索引或表达式索引。 +- 索引是可见的二级索引或非聚簇主键索引，且不是部分索引、全局索引、多值索引、向量搜索索引或全文索引。 +- 每个索引列均索引完整的列值，不能使用前缀索引或表达式索引。 - 对于包含多列的唯一索引，除 TTL 列之外的其他列都为 `NOT NULL`。 - 非唯一索引满足以下要求： - 索引包含全部主键列或完全不包含主键列，不能只包含复合主键中的部分列。