diff --git a/system-variable-reference.md b/system-variable-reference.md index 3590ce3e5c8fd..9c33bb17889d9 100644 --- a/system-variable-reference.md +++ b/system-variable-reference.md @@ -4136,6 +4136,13 @@ Referenced in: - [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 + +Referenced in: + +- [Periodically Delete Expired Data Using TTL (Time to Live)](/time-to-live.md) +- [System Variables](/system-variables.md#tidb_ttl_enable_index_scan) + ### tidb_ttl_job_enable Referenced in: diff --git a/system-variables.md b/system-variables.md index ce7bf4e26cb5e..e4f31fe0b72f7 100644 --- a/system-variables.md +++ b/system-variables.md @@ -6725,6 +6725,19 @@ For details, see [Identify Slow Queries](/identify-slow-queries.md). - Range: `[1, 256]` - This variable is used to set the maximum concurrency of TTL jobs on each TiDB node. For more information, refer to [Time to Live](/time-to-live.md). +### tidb_ttl_enable_index_scan + +> **Note:** +> +> This variable is read-only for [{{{ .starter }}}](https://docs.pingcap.com/tidbcloud/select-cluster-tier#starter) and [{{{ .essential }}}](https://docs.pingcap.com/tidbcloud/select-cluster-tier#essential) instances. + +- Scope: GLOBAL +- Persists to cluster: Yes +- Applies to hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value): No +- Default value: `ON` +- Type: Boolean +- This variable controls whether TTL jobs can use an eligible secondary index or non-clustered primary key index that starts with the TTL column. When this variable is set to `OFF`, TTL jobs scan in table-key order. For index eligibility, see [Scan expired rows using an index](/time-to-live.md#scan-expired-rows-using-an-index). + ### tidb_ttl_job_enable New in v6.5.0 > **Note:** diff --git a/time-to-live.md b/time-to-live.md index 05c60079086eb..80e19f2781322 100644 --- a/time-to-live.md +++ b/time-to-live.md @@ -140,6 +140,23 @@ When executing a TTL job, TiDB splits the table into tasks, with the Region as t TiDB also limits the number of concurrent TTL tasks at the cluster level. You can adjust this concurrency by setting the system variable [`tidb_ttl_running_tasks`](/system-variables.md#tidb_ttl_running_tasks-new-in-v700). +### Scan expired rows using an index + +To use an index scan, the TTL column must be the first column of the index. This allows TiDB to scan the index range that can contain expired rows without scanning unexpired index entries. + +By default, TiDB automatically selects an eligible index for this scan. This behavior is controlled by the [`tidb_ttl_enable_index_scan`](/system-variables.md#tidb_ttl_enable_index_scan) global variable, which is enabled by default. When this variable is disabled or no eligible index is available, TiDB falls back to scanning in table-key order and prevents the optimizer from selecting a secondary index for that scan. For a table with a clustered primary key, the table-key scan uses that primary key. + +In addition to starting with the TTL column, an eligible index must meet the following requirements: + +- It is a visible secondary index or a non-clustered primary key index. It is not a partial index, global index, multi-valued index, vector search index, or full-text index. +- Each index column indexes the full column value. Prefix indexes and expression indexes are not supported. +- For a unique index that contains multiple columns, all columns except the TTL column are `NOT NULL`. +- A non-unique index meets the following requirements: + - It includes either all primary key columns or none of them. It cannot include only some columns of a composite primary key. + - If the table has a clustered primary key consisting of a single unsigned integer column, the index includes that primary key column. + - If any column of the clustered primary key is defined with a prefix length, the index includes all primary key columns. +- Index columns cannot use the `SET`, `FLOAT`, or `DOUBLE` data type. For a non-unique index that does not include primary key columns, the primary key columns cannot use these data types either. + To disable the execution of TTL jobs, in addition to setting the `TTL_ENABLE='OFF'` table option, you can also disable the execution of TTL jobs in the entire cluster by setting the [`tidb_ttl_job_enable`](/system-variables.md#tidb_ttl_job_enable-new-in-v650) global variable: ```sql @@ -207,7 +224,7 @@ In addition, TiDB provides three tables to obtain more information about TTL job The columns `{last, current}_job_{start_time, finish_time, ttl_expire}` describe respectively the start time, finish time, and expiration time used by the TTL job of the last or current execution. The `last_job_summary` column describes the execution status of the last TTL task, including the total number of rows, the number of successful rows, and the number of failed rows. -+ The `mysql.tidb_ttl_task` table contains information about the ongoing TTL subtasks. A TTL job is split into many subtasks, and this table records the subtasks that are currently being executed. ++ The `mysql.tidb_ttl_task` table contains information about the ongoing TTL subtasks. A TTL job is split into subtasks, and this table records the subtasks that are currently being executed. The `scan_index_id` column indicates the scan path selected when the job was created. A non-`NULL` value is the ID of the selected index, and `NULL` means that the task scans in table-key order. + The `mysql.tidb_ttl_job_history` table contains information about the TTL jobs that have been executed. The record of TTL job history is kept for 90 days. ```sql