Add the doc for the TTL feature

TOC.md

@@ -37,6 +37,7 @@
     - [插入数据](/develop/dev-guide-insert-data.md)
     - [更新数据](/develop/dev-guide-update-data.md)
     - [删除数据](/develop/dev-guide-delete-data.md)
+    - [使用 TTL (Time to Live) 定期删除过期数据](/time-to-live.md)
     - [预处理语句](/develop/dev-guide-prepared-statement.md)
   - 数据读取
     - [单表读取](/develop/dev-guide-get-data-from-single-table.md)

experimental-features.md

@@ -34,6 +34,7 @@ aliases: ['/docs-cn/dev/experimental-features-4.0/','/zh/tidb/dev/experimental-f
 + [Cascades Planner](/system-variables.md#tidb_enable_cascades_planner)：基于 Cascades 框架的自顶向下查询优化器。（v3.0 实验特性）
 + [表级锁 (Table Lock)](/tidb-configuration-file.md#enable-table-lock-从-v400-版本开始引入)（v4.0.0 实验特性）
 + [Range INTERVAL 分区](/partitioned-table.md#range-interval-分区)（v6.3.0 实验特性）
++ [使用 TTL (Time to Live) 定期删除过期数据](/time-to-live.md)。(v6.5.0 实验特性)
 + [TiFlash 查询结果物化](/tiflash/tiflash-results-materialization.md)（v6.5.0 实验特性）
 
 ## 存储

grafana-tidb-dashboard.md

@@ -169,3 +169,10 @@ aliases: ['/docs-cn/dev/grafana-tidb-dashboard/','/docs-cn/dev/reference/key-mon
     - Wait Duration 95: 批量消息处理的等待时间。
     - Batch Client Unavailable Duration 95：批处理客户端的不可用时长。
     - No Available Connection Counter：批处理客户端不可用的连接数。
+
+- TTL
+    - TTL QPS By Type：TTL 任务产生的不同类型语句的 QPS 信息。
+    - TTL Processed Rows Per Second：TTL 任务每秒处理的过期数据的行数。
+    - TTL Scan/Delete Query Duration：TTL 的扫描/删除语句的执行时间。
+    - TTL Scan/Delete Worker Time By Phase：TTL 内部工作线程的不同阶段所占用的时间。
+    - TTL Job Count By Status：当前正在执行的 TTL 任务的数量。

sql-statements/sql-statement-alter-table.md

@@ -49,6 +49,11 @@ AlterTableSpec ::=
 |   'SECONDARY_UNLOAD'
 |   ( 'AUTO_INCREMENT' | 'AUTO_ID_CACHE' | 'AUTO_RANDOM_BASE' | 'SHARD_ROW_ID_BITS' ) EqOpt LengthNum
 |   ( 'CACHE' | 'NOCACHE' )
+|   (
+        'TTL' EqOpt TimeColumnName '+' 'INTERVAL' Expression TimeUnit (TTLEnable EqOpt ( 'ON' | 'OFF' ))?
+        | 'REMOVE' 'TTL'
+        | TTLEnable EqOpt ( 'ON' | 'OFF' )
+    )
 |   PlacementPolicyOption
 
 PlacementPolicyOption ::=

sql-statements/sql-statement-create-table.md

@@ -83,6 +83,7 @@ TableOption ::=
 |   'SECONDARY_ENGINE' EqOpt ( 'NULL' | StringName )
 |   'UNION' EqOpt '(' TableNameListOpt ')'
 |   'ENCRYPTION' EqOpt EncryptionOpt
+|    'TTL' EqOpt TimeColumnName '+' 'INTERVAL' Expression TimeUnit (TTLEnable EqOpt ( 'ON' | 'OFF' ))?
 |   PlacementPolicyOption
 
 OnCommitOpt ::=

system-variables.md

@@ -3215,6 +3215,114 @@ Query OK, 0 rows affected, 1 warning (0.00 sec)
 >
 > 如果 PD leader 的 TSO RPC 延迟升高，但其现象并非由 CPU 使用率达到瓶颈而导致（可能存在网络等问题），此时，调高 `tidb_tso_client_batch_max_wait_time` 可能会导致 TiDB 的语句执行延迟上升，影响集群的 QPS 表现。
 
+### `tidb_ttl_delete_rate_limit` <span class="version-mark">从 v6.5.0 版本开始引入</span>
+
+> **警告：**
+>
+> [TTL](/time-to-live.md) 目前为实验性特性，此变量定义可能在之后发生变化或者删除。
+
+- 作用域：GLOBAL
+- 是否持久化到集群：是
+- 默认值：`0`
+- 范围：`[0, 9223372036854775807]`
+- 这个变量用来对每个 TiDB 节点的 TTL 删除操作进行限流。其值代表了在 TTL 任务中单个节点每秒允许 `DELETE` 语句执行的最大次数。当此变量设置为 `0` 时，则表示不做限制。
+
+### `tidb_ttl_delete_batch_size` <span class="version-mark">从 v6.5.0 版本开始引入</span>
+
+> **警告：**
+>
+> [TTL](/time-to-live.md) 目前为实验性特性，此变量定义可能在之后发生变化或者删除。
+
+- 作用域：GLOBAL
+- 是否持久化到集群：是
+- 默认值：`100`
+- 范围：`[1, 10240]`
+- 这个变量用于设置 TTL 任务中单个删除事务中允许删除的最大行数。
+
+### `tidb_ttl_delete_worker_count` <span class="version-mark">从 v6.5.0 版本开始引入</span>
+
+> **警告：**
+>
+> [TTL](/time-to-live.md) 目前为实验性特性，此变量定义可能在之后发生变化或者删除。
+
+- 作用域：GLOBAL
+- 是否持久化到集群：是
+- 默认值：`4`
+- 范围：`[1, 256]`
+- 这个变量用于设置每个 TiDB 节点上 TTL 删除任务的最大并发数。
+
+### `tidb_ttl_job_enable` <span class="version-mark">从 v6.5.0 版本开始引入</span>
+
+> **警告：**
+>
+> [TTL](/time-to-live.md) 目前为实验性特性，此变量定义可能在之后发生变化或者删除。
+
+- 作用域：GLOBAL
+- 是否持久化到集群：是
+- 默认值：`ON`
+- 类型：布尔型
+- 这个变量用于控制是否启动 TTL 后台清理任务。如果设置为 `OFF`，所有具有 TTL 属性的表会自动停止对过期数据的清理。
+
+### `tidb_ttl_scan_batch_size` <span class="version-mark">从 v6.5.0 版本开始引入</span>
+
+> **警告：**
+>
+> [TTL](/time-to-live.md) 目前为实验性特性，此变量定义可能在之后发生变化或者删除。
+
+- 作用域：GLOBAL
+- 是否持久化到集群：是
+- 默认值：`500`
+- 范围：`[1, 10240]`
+- 这个变量用于设置 TTL 任务中用来扫描过期数据的每个 `SELECT` 语句的 `LIMIT` 的值。 
+
+### `tidb_ttl_scan_worker_count` <span class="version-mark">从 v6.5.0 版本开始引入</span>
+
+> **警告：**
+>
+> [TTL](/time-to-live.md) 目前为实验性特性，此变量定义可能在之后发生变化或者删除。
+
+- 作用域：GLOBAL
+- 是否持久化到集群：是
+- 默认值：`4`
+- 范围：`[1, 256]`
+- 这个变量用于设置每个 TiDB 节点 TTL 扫描任务的最大并发数。
+
+### `tidb_ttl_job_run_interval` <span class="version-mark">从 v6.5.0 版本开始引入</span>
+
+> **警告：**
+>
+> [TTL](/time-to-live.md) 目前为实验性特性，此变量定义可能在之后发生变化或者删除。
+
+- 作用域：GLOBAL
+- 是否持久化到集群：是
+- 默认值：`1h0m0s`
+- 范围：`[10m0s, 8760h0m0s]`
+- 这个变量用于控制 TTL 后台清理任务的调度周期。比如，如果当前值设置成了 `1h0m0s`，则代表每张设置了 TTL 属性的表会每小时清理一次过期数据。
+
+### `tidb_ttl_job_schedule_window_start_time` <span class="version-mark">从 v6.5.0 版本开始引入</span>
+
+> **警告：**
+>
+> [TTL](/time-to-live.md) 目前为实验性特性，此变量定义可能在之后发生变化或者删除。
+
+- 作用域：GLOBAL
+- 类型：时间
+- 是否持久化到集群：是
+- 默认值：`00:00 +0000`
+- 这个变量用于控制 TTL 后台清理任务的调度窗口的起始时间。请谨慎调整此参数，过小的窗口有可能会造成过期数据的清理无法完成。
+
+### `tidb_ttl_job_schedule_window_end_time` <span class="version-mark">从 v6.5.0 版本开始引入</span>
+
+> **警告：**
+>
+> [TTL](/time-to-live.md) 目前为实验性特性，此变量定义可能在之后发生变化或者删除。
+
+- 作用域：GLOBAL
+- 类型：时间
+- 是否持久化到集群：是
+- 默认值：`23:59 +0000`
+- 这个变量用于控制 TTL 后台清理任务的调度窗口的结束时间。请谨慎调整此参数，过小的窗口有可能会造成过期数据的清理无法完成。
+
 ### `tidb_txn_assertion_level` <span class="version-mark">从 v6.0.0 版本开始引入</span>
 
 - 作用域：SESSION | GLOBAL

time-to-live.md

@@ -0,0 +1,172 @@
+---
+title: 使用 TTL (Time to Live) 定期删除过期数据
+summary: 介绍如何通过 SQL 来管理表数据的生命周期
+---
+
+# 使用 TTL (Time to Live) 定期删除过期数据
+
+Time to Live (TTL) 提供了行级别的生命周期控制策略。通过为表设置 TTL 属性，TiDB 可以周期性地自动检查并清理表中的过期数据。此功能在一些场景可以有效节省存储空间、提升性能。
+
+TTL 常见的使用场景：
+
+* 定期删除验证码、短网址记录
+* 定期删除不需要的历史订单
+* 自动删除计算的中间结果
+
+TTL 设计的目标是在不影响在线读写负载的前提下，帮助用户周期性且及时地清理不需要的数据。TTL 会以表为单位，并发地分发不同的任务到不同的 TiDB Server 节点上，进行并行删除处理。TTL 并不保证所有过期数据立即被删除，也就是说即使数据过期了，客户端仍然有可能在这之后的一段时间内读到过期的数据，直到其真正的被后台处理任务删除。
+
+> **警告：**
+>
+> 当前该功能为实验特性，不建议在生产环境中使用。
+> TTL 无法在 [Serverless Tier clusters](https://docs.pingcap.com/tidbcloud/select-cluster-tier#serverless-tier-beta) 上使用
+
+## 语法
+
+你可以通过 [`CREATE TABLE`](/sql-statements/sql-statement-create-table.md) 或 [`ALTER TABLE`](/sql-statements/sql-statement-alter-table.md) 语句来配置表的 TTL 功能。
+
+### 创建具有 TTL 属性的表
+
+- 创建一个具有 TTL 属性的表：
+
+    ```sql
+    CREATE TABLE t1 (
+        id int PRIMARY KEY,
+        created_at TIMESTAMP
+    ) TTL = `created_at` + INTERVAL 3 MONTH;
+    ```
+
+    上面的例子创建了一张表 `t1`，并指定了 `created_at` 为 TTL 的时间列，表示数据的创建时间。同时，它还通过 `INTERVAL 3 MONTH` 设置了表中行的最长存活时间为 3 个月。超过了此时长的过期数据会在之后被删除。
+
+- 设置 `TTL_ENABLE` 属性来开启或关闭清理过期数据的功能：
+
+    ```sql
+    CREATE TABLE t1 (
+        id int PRIMARY KEY,
+        created_at TIMESTAMP
+    ) TTL = `created_at` + INTERVAL 3 MONTH TTL_ENABLE = 'OFF';
+    ```
+
+    如果 `TTL_ENABLE` 被设置成了 `OFF`，则即使设置了其他 TTL 选项，当前表也不会自动清理过期数据。对于一个设置了 TTL 属性的表，`TTL_ENABLE` 在缺省条件下默认为 `ON`。
+
+- 为了与 MySQL 兼容，你也可以使用注释语法来设置 TTL：
+
+    ```sql
+    CREATE TABLE t1 (
+        id int PRIMARY KEY,
+        created_at TIMESTAMP
+    ) /*T![ttl] TTL = `created_at` + INTERVAL 3 MONTH TTL_ENABLE = 'OFF'*/;
+    ```
+
+    在 TiDB 环境中，使用表的 TTL 属性和注释语法来配置 TTL 是等价的。在 MySQL 环境中，会自动忽略注释中的内容，并创建普通的表。
+
+### 修改表的 TTL 属性
+
+- 修改表的 TTL 属性：
+
+    ```sql
+    ALTER TABLE t1 TTL = `created_at` + INTERVAL 1 MONTH;
+    ```
+
+    上面的语句既支持修改已配置 TTL 属性的表，也支持为一张非 TTL 的表添加 TTL 属性。
+
+- 单独修改 TTL 表的 `TTL_ENABLE` 值：
+
+    ```sql
+    ALTER TABLE t1 TTL_ENABLE = 'OFF';
+    ```
+
+- 清除一张表的所有 TTL 属性：
+
+    ```sql
+    ALTER TABLE t1 REMOVE TTL;
+    ```
+
+### TTL 和数据类型的默认值
+
+TTL 可以和[数据类型的默认值](/data-type-default-values.md)一起使用。以下是两种常见的用法示例：
+
+* 使用 `DEFAULT CURRENT_TIMESTAMP` 来指定某一列的默认值为该行的创建时间，并用这一列作为 TTL 的时间列，创建时间超过 3 个月的数据将被标记为过期：
+
+    ```sql
+    CREATE TABLE t1 (
+        id int PRIMARY KEY,
+        created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+    ) TTL = `created_at` + INTERVAL 3 MONTH;
+    ```
+
+* 指定某一列的默认值为该行的创建时间或更新时间，并用这一列作为 TTL 的时间列，创建时间或更新时间超过 3 个月的数据将被标记为过期：
+
+    ```sql
+    CREATE TABLE t1 (
+        id int PRIMARY KEY,
+        created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+    ) TTL = `created_at` + INTERVAL 3 MONTH;
+    ```
+
+### TTL 和生成列
+
+TTL 可以和[生成列](/generated-columns.md)（实验特性）一起使用，用来表达更加复杂的过期规则。例如：
+
+```sql
+CREATE TABLE message (
+    id int PRIMARY KEY,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    image bool,
+    expire_at TIMESTAMP AS (IF(image,
+            created_at + INTERVAL 5 DAY,
+            created_at + INTERVAL 30 DAY
+    ))
+) TTL = `expire_at` + INTERVAL 0 DAY;
+```
+
+上述语句的消息以 `expire_at` 列来作为过期时间，并按照消息类型来设定。如果是图片，则 5 天后过期，不然就 30 天后过期。
+
+TTL 还可以和 [JSON 类型](/data-type-json.md) 一起使用。例如：
+
+```sql
+CREATE TABLE orders (
+    id INT NOT NULL AUTO_INCREMENT PRIMARY KEY,
+    order_info JSON,
+    created_at DATE AS (JSON_EXTRACT(order_info, '$.created_at')) VIRTUAL
+) TTL = `created_at` + INTERVAL 3 month;
+```
+
+## TTL 任务
+
+对于每张设置了 TTL 属性的表，TiDB 内部会定期调度后台任务来清理过期的数据。你可以通过设置全局变量 [`tidb_ttl_job_run_interval`](/system-variables.md#tidb_ttl_job_run_interval-从-v650-版本开始引入) 来自定义任务的执行周期，比如通过下面的语句将后台清理任务设置为每 24 小时执行一次：
+
+```sql
+SET @@global.tidb_ttl_job_run_interval = '24h';
+```
+
+如果想禁止 TTL 任务的执行，除了可以设置表属性 `TTL_ENABLE='OFF'` 外，也可以通过设置全局变量 `tidb_ttl_job_enable` 关闭整个集群的 TTL 任务的执行。
+
+```sql
+SET @@global.tidb_ttl_job_enable = OFF;
+```
+
+在某些场景下，你可能希望只允许在每天的某个时间段内调度后台的 TTL 任务，此时可以设置全局变量 [`tidb_ttl_job_schedule_window_start_time`](/system-variables.md#tidb_ttl_job_schedule_window_start_time-从-v650-版本开始引入) 和 [`tidb_ttl_job_schedule_window_end_time`](/system-variables.md#tidb_ttl_job_schedule_window_end_time-从-v650-版本开始引入) 来指定时间窗口，比如：
+
+```sql
+SET @@global.tidb_ttl_job_schedule_window_start_time = '01:00 +0000';
+SET @@global.tidb_ttl_job_schedule_window_end_time = '05:00 +0000';
+```
+
+上述语句只允许在 UTC 时间的凌晨 1 点到 5 点调度 TTL 任务。默认情况下的时间窗口设置为 `00:00 +0000` 到 `23:59 +0000`，即允许所有时段的任务调度。
+
+## 监控与图表
+
+TiDB 会定时采集 TTL 的运行时信息，并在 Grafana 中提供了相关指标的可视化图表。你可以 TiDB -> TTL 的面板下看到这些信息。指标详情见 [TiDB 重要监控指标详解](/grafana-tidb-dashboard.md) 中的 `TTL` 部分。
+
+## 工具兼容性
+
+作为实验特性，TTL 特性暂时不兼容包括 BR、TiDB Lightning、TiCDC 在内的数据导入导出以及同步工具。
+
+## 使用限制
+
+目前，TTL 特性具有以下限制:
+
+* 不允许在临时表上设置 TTL 属性，包括本地临时表和全局临时表。
+* 具有 TTL 属性的表不支持作为外键约束的主表被其他表引用。
+* 不保证所有过期数据立即被删除，过期数据被删除的时间取决于后台清理任务的调度周期和调度窗口。
+* 目前单个表的清理任务同时只能在同一个 TiDB Server 节点运行，这在某些场景下（比如表特别大的情况）可能会产生性能瓶颈。此问题会在后续版本中优化。