PolarDB-X企业版创建TTL表_云原生数据库 PolarDB(PolarDB)-阿里云帮助中心

本文通过介绍TTL表的定义、创建、调整、删除，帮助您快速了解TTL表的基础操作。

适用范围

按行归档

引擎版本为MySQL 5.7时，实例版本需为polardb-2.4.0_5.4.19-20240927_xcluster5.4.19-20240920及以上。
引擎版本为MySQL 8.0时，实例版本需为polardb-2.4.0_5.4.19-20240927_xcluster8.4.19-20240924及以上。

按分区归档

引擎版本为MySQL 5.7时，实例版本需为polardb-2.5.0_5.4.20-20250328_xcluster5.4.20-20250221及以上。
引擎版本为MySQL 8.0时，实例版本需为polardb-2.5.0_5.4.20-20250328_xcluster8.4.20-20250304及以上。

说明

实例版本的规则说明，请参见版本说明。
实例版本的查看方式，请参见查看实例版本。

添加TTL定义

在PolarDB-X中，您可以通过ALTER语句为表指定TTL定义，以告诉数据库这个表的数据过期规则。被添加TTL定义的表，下文中统一称为TTL表。

重要

添加TTL定义，仅会修改在线表的TTL元数据，不会引起任何的数据清理或分区变更，不会对在线表的在线业务产生任何影响。
TTL定义仅支持AUTO模式数据库的分区表（不包括使用Local Partition的分区表）。

语法

ALTER TABLE table_name 
MODIFY TTL
SET
TTL_EXPR = xxx
[,TTL_JOB = xxx]
[,TTL_PART_INTERVAL = xxx]
[,TTL_FILTER = xxx]
[,TTL_ENABLE = xxx]
[,TTL_CLEANUP = xxx]
[,ARCHIVE_TYPE = xxx]
[,ARCHIVE_TABLE_PRE_ALLOCATE = xxx]
[,ARCHIVE_TABLE_POST_ALLOCATE = xxx]
;

说明

各参数详细说明，请参见TTL定义说明。

示例

创建示例分区表my_ttl_tbl：

CREATE TABLE `my_ttl_tbl` (
	`id` int(11) NOT NULL AUTO_INCREMENT,
	`date_field` datetime DEFAULT CURRENT_TIMESTAMP,
	PRIMARY KEY (`id`)
) ENGINE = InnoDB DEFAULT CHARSET = utf8mb4
PARTITION BY KEY(`id`)
PARTITIONS 8;

添加TTL定义：

ALTER TABLE my_ttl_tbl 
MODIFY TTL
SET 
TTL_EXPR = `date_field` EXPIRE AFTER 2 MONTH TIMEZONE '+08:00';

TTL定义说明

PolarDB-X 2.0的TTL定义主要由四部分组成，分别是TTL_EXPR、TTL_JOB（可选）、TTL_PART_INTERVAL（可选）、TTL_FILTER（可选）。

TTL_EXPR

用于定义TTL的时间列、数据存活时间间隔以及数据的过期策略。

语法
```
TTL_EXPR = data_expiration_expr_definition

data_expiration_expr_definition:
    data_expire_by_time_defition
  | data_expire_by_part_count_defition
  
data_expire_by_time_defition:
  ttl_time_column_expr EXPIRE AFTER data_expire_expr_definition timezone_definition

ttl_time_column_expr:
    ttl_time_col
  | FROM_UNIXTIME(ttl_ts_int_col)
  | FROM_UNIXTIME(ttl_milli_ts_int_col/1000)
  
data_expire_expr_definition:
  EXPIRE AFTER ttl_expire_interval_definition
    
ttl_expire_interval_definition:
  expire_after_interval_count interval_timeunit_expr

interval_timeunit_expr:
     DAY 
   | MONTH
   | YEAR

timezone_definition:
  TIMEZONE time_zone_value

time_zone_value:
  '[+-]HH:MM'

expire_after_interval_count:
  int_number

data_expire_by_part_count_defition:
  ttl_int_col data_expire_over_definition

data_expire_over_definition:
  EXPIRE OVER expire_over_partition_count PARTITIONS

expire_over_partition_count:
  int_number
```
说明
data_expiration_expr_definition支持以下两种数据过期策略：
- data_expire_by_time_defition：按照固定的时间间隔自动过期，即TTL表的数据若存活超过指定的时间间隔，将被认为是过期数据，通常用于按时间归档，下文统一将这种过期策略称为EXPIRE AFTER过期策略。
  - ttl_time_col：表示TTL列，支持类型如下：
    时间类型：DATE、DATETIME、TIMESTAMP。
    整数类型：INT、BIGINT。
  - ttl_ts_int_col：特指具有以秒为单位的时间戳（例如：UNIX系统的时间戳）含义的整数类型的时间列，FROM_UNIXTIME(ttl_ts_int_col)表示将时间戳的整数转为实际时间，并判断是否过期。
  - ttl_milli_ts_int_col：特指具有以毫秒为单位的时间戳含义（例如：JAVA时间戳）的整数类型的时间列，因此FROM_UNIXTIME(ttl_ts_int_col/1000)表示将毫秒时间戳的整数转为实际时间进行判断是否过期。
  - ttl_expire_interval_definition：数据存活的时间周期，格式为IntervalNumber IntervalTimeUnit，当(now() - ttl_time_column_expr) > ttl_expire_interval_definition时，满足条件的数据将会被自动清理。其中IntervalTimeUnit只支持DAY/MONTH/YEAR三种时间单位。示例：
    TTL_EXPR = `ttl_col` EXPIRE AFTER 3/*intervalNumber*/ MONTH /*intervalTimeUnit*/ TIMEZONE '+08:00'
    其中过期时间间隔数目IntervalNumber的值为3，过期时间间隔单位IntervalTimeUnit的值为MONTH。
    过期时间间隔单位IntervalTimeUnit是与清理时间区间的上界取值的截断及标准化处理有密切相关，详细信息，请参见TTL表冷数据清理算法。
    IntervalTimeUnit是TTL_PART_INTERVAL表达式的默认时间单位，如果TTL_PART_INTERVAL未被显式设置，则系统会采用IntervalTimeUnit为分区间隔单位。
  - timezone_definition：定义TTL列的时区，TTL表定时任务需要根据时区来计算是否过期，TTL列为TIMESTAMP类型时必须指定时区，仅支持'[+-]HH:MM'格式。
- data_expire_by_part_count_defition：按照固定的RANGE分区数目自动过期，即TTL表最多保留expire_over_partition_count个分区，会删除最小的RANGE分区，通常用于按分区归档，下文统一将这种过期策略称为EXPIRE OVER过期策略。通常该策略还需要与TTL_PART_INTERVAL属性配合使用。
  - ttl_int_col：特指整数类型的TTL列。
  - expire_over_partition_count：最多保留的固定分区数目。
示例
- TTL列类型为DATETIME类型，TTL表保留最近3个月数据。
```
TTL_EXPR = `<ttl_col>` EXPIRE AFTER 3 MONTH TIMEZONE '+08:00'
```
- TTL列类型为TIMESTAMP类型，TTL列使用的时区是东十时区，TTL表保留最近30天数据。
```
TTL_EXPR = `<ttl_col>` EXPIRE AFTER 30 DAY TIMEZONE '+10:00'
```
- TTL列类型为INT类型，TTL列是UNIX时间戳（以秒为单位）的整数，TTL列使用的时区是零点时区，TTL表保留最近7天数据。
```
TTL_EXPR = FROM_UNIXTIME(`<ttl_col>`) EXPIRE AFTER 7 DAY TIMEZONE '+00:00'
```
- TTL列类型为INT类型，TTL列是毫秒时间戳的整数，TTL列使用的时区是东八时区，TTL表保留最近60天数据。
```
TTL_EXPR = FROM_UNIXTIME(`<ttl_col>`/1000) EXPIRE AFTER 60 DAY TIMEZONE '+08:00'
```
- TTL列类型为BIGINT类型，TTL列是业务递增的流水单号，TTL表的RANGE分区最多保留16个分区。
```
TTL_EXPR = `<ttl_col>` EXPIRE OVER 16 PARTITIONS
```

TTL_JOB

用于定义TTL定时任务提交的时间点和频率，该属性为可选，默认值为'0 0 1 */1 * ? *'（每天凌晨一点调用一次）。

语法

TTL_JOB = quartz_cron_expr_definition［timezone_definition］

quartz_cron_expr_definition :
   CRON cron_expr_value

timezone_definition :
  TIMEZONE time_zone_value

time_zone_value:
  '[+-]HH:MM'

参数说明

名称

说明

cron_expr_value

系统清理任务的时间点和频率，使用QUARTZ框架的CRON表达式表示，该表达式由以下七部分组成：

秒（0-59）
分钟（0-59）
小时（0-23，用*表示每小时）
日期（1-31，表示月份中的某一天，用*表示每天）
月份（1-12或JAN、FEB、MAR、APR、...、DEC，用*表示每月）
星期中的日期（1-7或SUN、MON、TUE、WED、THU、FRI、SAT，1代表星期日，？表示占位符不设置）
年份（用*表示每一年）

timezone_definition（可选）

timezone_definition中的time_zone_value固定为'+08:00'，即默认后台TTL表定时任务的调度均衡按东八区时间进行计算，暂不支持修改为其它时区。

重要

因为定时清理任务运行占用一定的资源，所以PolarDB-X 2.0不支持将定时任务的周期设置为分钟级或秒级，也不建议设置为小时级别，以防止清理任务运行过于频繁影响业务稳定性。

示例
TTL后台的清理任务每天凌晨一点调用一次：
```
TTL_JOB = CRON '0 0 1 */1 * ? *' TIMEZONE '+08:00'
```
注意事项
- TTL_JOB定义的是TTL表定时任务被定时自动提交的时间点及频率，但TTL表定时任务的实际运行还要受到可运维窗口（默认窗口为02:00~05:00）的限制。
- 本轮可运维窗口未执行完成的TTL表定时任务会自动暂停，并且在下一轮可运维窗口继续执行。例如：TTL_JOB = CRON '0 0 1 */1 * ? *' TIMEZONE '+08:00'，若可运维时间窗口是02:00~05:00，TTL表定时任务会在每天的01:00发起任务并提交，但任务实际会等到02:00才开始正式运行，并且若在05:00TTL表定时任务还没执行完成，TTL表定时任务将自动进入暂停状态，并等到第二天02:00到继续运行。
- TTL表定时任务尽量在可运维窗口时间内执行完毕，否则可能会导致残留的数据积累的越来越多。

TTL_PART_INTERVAL

用于指定TTL表及其归档表的相邻两个分区之间的时间间隔或数值间隔。该属性生效的三个主要场景：

TTL表在采用按分区归档时，定时任务给TTL表自动预建新的RANGE分区，新建分区之间时间间隔即是TTL_PART_INTERVAL的间隔；
TTL表在创建归档表以保存归档数据时，数据库会为归档表自动构建RANGE分区定义，这些RANGE分区的时间间隔就是TTL_PART_INTERVAL的间隔。
TTL表在创建归档表后，定时任务给归档表自动预建新的RANGE分区，新建分区之间时间间隔即是TTL_PART_INTERVAL的间隔。

该属性通常与TTL_EXPR配合一起使用。

语法
```
TTL_PART_INTERVAL = INTERVAL(int_value, interval_time_unit)

interval_time_unit :
    DAY
  | MONTH
  | YEAR
  | NUMBER
```
说明
- 其中NUMBER（整数）为间隔单位时，TTL列需为整数类型且使用EXPIRE OVER的过期策略，且取值必须是正整数。
- 关于TTL_PART_INTERVAL的默认值，按分区归档时，如果仅指定TTL_EXPR的过期时间间隔（例如：`ttl_col` EXPIRE AFTER 3 MONTH TIMEZONE '+08:00'），没有显式指定TTL_PART_INTERVAL，其默认值按照如下方式定义：
  - TTL_PART_INTERVAL的时间间隔单位与TTL_EXPR的过期时间间隔单位相同。
  - TTL_PART_INTERVAL的间隔数默认为1。
示例
- 按年分区（一年一个分区）。
```
TTL_PART_INTERVAL = INTERVAL(1, YEAR)
```
- 按月分区（一个月一个分区）。
```
TTL_PART_INTERVAL = INTERVAL(1, MONTH)
```
- 按周分区（7天一个分区）。
```
TTL_PART_INTERVAL = INTERVAL(7, DAY)
```
- 按天分区（一天一个分区）。
```
TTL_PART_INTERVAL = INTERVAL(1, DAY)
```
- 按整数范围分区（按间隔100000为一个分区）
```
TTL_PART_INTERVAL = INTERVAL(100000, NUMBER)
```

TTL_FILTER

对于使用了按行归档的TTL表，该属性可供您指定额外的业务过滤条件，让TTL任务仅清理满足业务特殊查询条件的过期数据。

语法
```
TTL_FILTER = COND_EXPR (query_cond_expr)
```
query_cond_expr指的是普通DELETE语句中的WHERE子句的条件表达式，默认值为''，与TTL按行清理的时间条件是AND关系。例如：当前正在清理的时间范围是`ttl_col` < '2025-05-01'，query_cond_expr是`status`=1，即实际的清理过滤条件是(( `ttl_col` < '2025-05-01' ) AND ( `status` ＝ 1))。因为query_cond_expr的条件表达式不能使用TTL列的索引，所以建议您尽量简化query_cond_expr条件表达式，复杂的条件表达式可能会影响按行清理速度。
重要
清理任务默认会将TTL列为NULL值的数据行当做最小值并清理，您可以设置TTL_FILTER = COND_EXPR( <ttl_col_name> IS NOT NULL ))后，不再自动清理TTL列为NULL值的数据行，该设置仅支持实例版本polardb-2.5.0_5.4.20-20250328_xcluster5.4.20-20250221（MySQL 5.7）及以上或polardb-2.5.0_5.4.20-20250328_xcluster8.4.20-20250304（MySQL 8.0）及以上。
示例
数据清理规则只想应用于被标记为完成状态（status=1）的过期数据：
```
TTL_FILTER = COND_EXPR(`status` = 1)
```

其他定义说明

名称	说明	示例
TTL_ENABLE	TTL表的定时任务开关。取值范围如下： OFF（默认值）：关闭定时任务。 ON：开启定时任务。开启后定时任务会完成以下工作： TTL表清理过期的历史数据（按行归档场景）。 TTL表按需自动加减分区（按分区归档场景）。归档表按需自动增加分区。	`TTL_ENABLE='ON'`
TTL_CLEANUP	清理TTL表的过期数据的开关。取值范围如下： OFF（默认值）：TTL表定时任务不再清理过期数据和删除过期分区，但依然允许自动新增分区。 ON：TTL表定时任务会清理过期数据和删除过期分区。说明 `TTL_CLEANUP`参数设置需实例版本达到`polardb-2.5.0_5.4.20-20250328_xcluster5.4.20-20250221`或`polardb-2.5.0_5.4.20-20250328_xcluster8.4.20-20250304`及其以上。早期版本无需设置该参数，默认能进行过期数据清理。因为`TTL_CLEANUP`参数默认值为OFF，所以一般情况下需要和`TTL_ENABLE`参数同时设置为ON，才能顺利完成过期数据的定时清理。	`TTL_CLEANUP='ON'`
ARCHIVE_TYPE（必填）	TTL表的归档类型，可取值如下： ROW（默认值）：表示按行归档，即定期对TTL表按行执行`DELETE`操作，实现过期数据的清理及归档。 PARTITION：按一级分区归档，即通过定期删除TTL表的一级`RANGE`分区，实现过期数据的清理及归档，该属性要求TTL表的一级`RANGE`分区必须使用TTL时间列作为分区列。 SUBPARTITION：按模板化二级分区归档，即通过定期删除TTL表的二级`RANGE`分区，以完成过期数据的清理及归档，该属性要求TTL表的模板化二级`RANGE`分区必须使用TTL时间列作为分区列。	`ARCHIVE_TYPE='ROW'`
ARCHIVE_TABLE_PRE_ALLOCATE	TTL表定时任务提前给TTL表或归档表的预建`RANGE`分区数目。取值为正整数，默认值为3。	`ARCHIVE_TABLE_PRE_ALLOCATE=3`
ARCHIVE_TABLE_POST_ALLOCATE	TTL表在创建新的归档表时，TTL给归档表的过去时间自动补建的`RANGE`分区数目。该属性仅在新建归档表时起作用。取值为正整数，默认值为64。	`ARCHIVE_TABLE_POST_ALLOCATE=64`

TTL定义示例

PolarDB-X的TTL目前支持以下两种的归档方式：

按行归档：TTL表使用DELETE的DML语句清理过期数据，　且所有被清理的过期数据走列存提前归档；
按分区归档：TTL表使用DROP (SUB)PARTITION的DDL语句清理过期数据，且所有被清理的过期分区的数据走列存提前归档。在按分区归档场景下，按数据过期策略，又可细分为2种：
- EXPIRE AFTER策略：数据按固定的时间间隔过期，即数据存活超过指定的时间间隔后，将被视为过期数据；
- EXPIRE OVER策略：数据按固定的分区数目过期，即RANGE分区数目超过指定的数量后，默认将最小的分区视为过期数据，该策略通常适用于TTL列是整数类型的数据归档。

以下是两种归档方式在各种场景的TTL定义的使用示例。

按行归档

TTL表首先将过期数据通过列存索引提前上传或同步到OSS，完成归档；再使用DELETE的DML语句清理过期数据。

由于按行归档时清理使用的DELETE语句，清理逻辑因TTL列的不同数据类型（主要是时间类型及整数类型）而有所不同，下边分别以TTL列是时间类型及TTL列是整数类型举例说明。

TTL列为时间类型示例

示例场景：

TTL列类型：TIMESTAMP。
TTL列时区：东八区。
过期策略：TTL表保留最近1个月数据。
任务时间：每天02:00开始启动一次。
归档表分区间隔：一个月一个分区。
归档表预建分区数：提前预建3个月的分区。
归档表补建分区数：补建过去48个月的RANGE分区（仅当创建归档表时生效）。

示例代码：

CREATE TABLE ttl_t1
(
  id BIGINT,
  ttl_ts_col TIMESTAMP
)
PARTITION BY KEY(`id`)
PARTITIONS 8;

-- 指定TTL
ALTER TABLE　`ttl_t1`
MODIFY TTL
SET
TTL_ENABLE='ON',
TTL_CLEANUP='OFF',
TTL_EXPR=`ttl_ts_col` EXPIRE AFTER 1 MONTH TIMEZONE '+08:00',
TTL_JOB=CRON '0 0 2 */1 * ? *' TIMEZONE '+08:00'
TTL_PART_INTERVAL=INTERVAL(1,MONTH),
ARCHIVE_TYPE='ROW',
ARCHIVE_TABLE_PRE_ALLOCATE=3,
ARCHIVE_TABLE_POST_ALLOCATE=24;

TTL列是整数类型示例

示例场景：

TTL列类型：BIGINT（毫秒时间戳）。
TTL列时区：GMT时区。
过期策略：TTL表保留最近1个月数据。
额外清理条件：只清理`flag` = 1的数据。
任务时间：每天02:00开始启动一次。
归档表分区间隔：一个月一个分区。
归档表预建分区数：提前预建3个月的分区。
归档表补建分区数：补建过去48个月的RANGE分区（仅当创建归档表时才生效）。

示例代码：

CREATE TABLE ttl_t2
(
  id BIGINT,
  ttl_int_col BIGINT,
  flag INT
)
PARTITION BY KEY(`id`)
PARTITIONS 8;

-- 指定TTL
ALTER TABLE　`ttl_t2`
MODIFY TTL
SET
TTL_ENABLE = 'ON',
TTL_CLEANUP = 'OFF',
TTL_EXPR = FROM_UNIXTIME(`ttl_int_col`/1000) EXPIRE AFTER 1 MONTH TIMEZONE '+00:00',
TTL_JOB = CRON '0 0 2 */1 * ? *' TIMEZONE '+08:00',
TTL_PART_INTERVAL = INTERVAL(1,MONTH),
TTL_FILTER = COND_EXPR( `flag` = 1 ),
ARCHIVE_TYPE = 'ROW',
ARCHIVE_TABLE_PRE_ALLOCATE = 3,
ARCHIVE_TABLE_POST_ALLOCATE = 48;

按分区归档

TTL表首先将过期数据通过列存索引提前上传或同步到OSS，完成归档（如果没有配置归档表则没有这一步）；再使用DROP (SUB)PARTITION的DDL语句清理过期数据。

由于按分区归档使用的DROP (SUB)PARTITION的DDL语句清理过期的RANGE分区，所以下边分别以按一级分区归档及按二级分区归档举例说明。

重要

注意事项：如果一个已存在的在线表与其他在线表存在JOIN关系，则将该在线表更改为使用按分区归档策略的TTL表，可能会影响该在线表与其他在线表的JOIN性能（例如，JOIN计算下推可能失效）。因此，请您在进行此更改前进行充分评估。

原因在于，使用按分区策略归档的TTL表将在后续自动调度的TTL任务中自动删除过期的分区，并增加预建的新分区，从而导致该表的分区定义发生变化。这会使得该表与其他存在JOIN关系的在线表的分区定义不再对齐，从而可能导致它们之间的JOIN计算下推失效。

按一级分区归档

数据按时间间隔自动过期示例

以下为您列举TTL列为DATETIME、TIMESTAMP以及BIGINT/INT类型时的示例：

`DATETIME`

示例场景：

TTL列类型：DATETIME。
TTL列时区：东八区。
过期策略：TTL表（一级分区是按时间RANGE分区）保留最近3个月数据。
任务时间：每天02:00开始启动一次。
TTL表和归档表分区间隔：一个月一个分区。
TTL表和归档表预建分区数：提前预建3个分区。
归档表补建分区数：补建过去48个RANGE分区（仅当创建归档表时才生效）。

示例代码：

CREATE TABLE ttl_t_2_1_0
(
  id BIGINT,
  ttl_dt_col DATETIME
)
PARTITION BY RANGE COLUMNS(`ttl_dt_col`)
(
  PARTITION p1 VALUES LESS THAN ('2025-04-01'),
  PARTITION p2 VALUES LESS THAN ('2025-05-01'),
  PARTITION p3 VALUES LESS THAN ('2025-06-01')
);

-- 指定TTL
ALTER TABLE　`ttl_t_2_1_0`
MODIFY TTL
SET
TTL_ENABLE = 'ON',
TTL_CLEANUP = 'OFF',
TTL_EXPR = `ttl_dt_col` EXPIRE AFTER 1 MONTH TIMEZONE '+08:00',
TTL_JOB = CRON '0 0 2 */1 * ? *' TIMEZONE '+08:00',
TTL_PART_INTERVAL = INTERVAL(1,MONTH),
ARCHIVE_TYPE = 'PARTITION',
ARCHIVE_TABLE_PRE_ALLOCATE = 3,
ARCHIVE_TABLE_POST_ALLOCATE = 48;

`TIMESTAMP`

示例场景：

TTL列类型：TIMESTAMP。
TTL列时区：东八区。
过期策略：TTL表（一级分区是按时间RANGE分区）保留最近3个月数据。
任务时间：每天02:00开始启动一次。
TTL表和归档表分区间隔：一个月一个分区。
TTL表和归档表预建分区数：提前预建3个分区。
归档表补建分区数：补建过去48个RANGE分区（仅当创建归档表时才生效）。

示例代码：

CREATE TABLE ttl_t_2_1_1
(
  id BIGINT,
  ttl_ts_col TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
)
PARTITION BY RANGE(UNIX_TIMESTAMP(`ttl_ts_col`))
(
  PARTITION p1 VALUES LESS THAN (UNIX_TIMESTAMP('2025-04-01 00:00:00')),
  PARTITION p2 VALUES LESS THAN (UNIX_TIMESTAMP('2025-05-01 00:00:00')),
  PARTITION p3 VALUES LESS THAN (UNIX_TIMESTAMP('2025-06-01 00:00:00'))
);

-- 指定TTL
ALTER TABLE　`ttl_t_2_1_1`
MODIFY TTL
SET
TTL_ENABLE = 'ON',
TTL_CLEANUP = 'OFF',
TTL_EXPR = `ttl_ts_col` EXPIRE AFTER 1 MONTH TIMEZONE '+08:00',
TTL_JOB = CRON '0 0 2 */1 * ? *' TIMEZONE '+08:00',
TTL_PART_INTERVAL = INTERVAL(1,MONTH),
ARCHIVE_TYPE = 'PARTITION',
ARCHIVE_TABLE_PRE_ALLOCATE = 3,
ARCHIVE_TABLE_POST_ALLOCATE = 48;

`BIGINT/INT`

示例场景：

TTL列类型：BIGINT（TTL列是UNIX时间戳整数）。
TTL列时区：东八区。
过期策略：TTL表（一级分区是按时间RANGE分区）保留最近3个月数据。
任务时间：每天02:00开始启动一次。
TTL表和归档表分区间隔：一个月一个分区。
TTL表和归档表预建分区数：提前预建3个分区。
归档表补建分区数：补建过去48个RANGE分区（仅当创建归档表时才生效）。

示例代码：

CREATE TABLE ttl_t_2_1_2
(
  id BIGINT,
  ttl_ts_int_col BIGINT
)
PARTITION BY RANGE COLUMNS(`ttl_ts_int_col`)
(
  PARTITION p20250401 VALUES LESS THAN (1743436800),
  PARTITION p20250501 VALUES LESS THAN (1746028800),
  PARTITION p20250601 VALUES LESS THAN (1748707200)
);

-- 指定TTL
ALTER TABLE　`ttl_t_2_1_2`
MODIFY TTL
SET
TTL_ENABLE = 'ON',
TTL_CLEANUP = 'OFF',
TTL_EXPR = FROM_UNIXTIME(`ttl_ts_int_col`) EXPIRE AFTER 1 MONTH TIMEZONE '+08:00',
TTL_JOB = CRON '0 0 2 */1 * ? *' TIMEZONE '+08:00',
TTL_PART_INTERVAL = INTERVAL(1,MONTH),
ARCHIVE_TYPE = 'PARTITION',
ARCHIVE_TABLE_PRE_ALLOCATE = 3,
ARCHIVE_TABLE_POST_ALLOCATE = 48;

数据按分区数目自动过期示例

示例场景：

TTL列类型：BIGINT(非时间戳整数)。
TTL列时区：东八区。
过期策略：TTL表（二级分区是按整数RANGE分区）保留最近3个分区。
任务时间：每天02:00开始启动一次。
TTL表和归档表分区间隔：每100000一个分区。
TTL表和归档表预建分区数：提前预建3个分区。
归档表补建分区数：补建过去48个RANGE分区（仅当创建归档表时才生效）。

示例代码：

CREATE TABLE ttl_t_2_2
(
  id BIGINT,
  ttl_int_col BIGINT
)
PARTITION BY RANGE COLUMNS(`ttl_int_col`)
(
  PARTITION p1 VALUES LESS THAN (400000),
  PARTITION p2 VALUES LESS THAN (500000),
  PARTITION p3 VALUES LESS THAN (600000),
  PARTITION p4 VALUES LESS THAN (700000)
);

-- 指定TTL
ALTER TABLE　`ttl_t_2_2`
MODIFY TTL
SET
TTL_ENABLE = 'ON',
TTL_CLEANUP = 'OFF',
TTL_EXPR = ttl_int_col EXPIRE OVER 3 PARTITIONS,
TTL_JOB = CRON '0 0 2 */1 * ? *' TIMEZONE '+08:00',
TTL_PART_INTERVAL = INTERVAL(100000,NUMBER),
ARCHIVE_TYPE = 'PARTITION',
ARCHIVE_TABLE_PRE_ALLOCATE = 3,
ARCHIVE_TABLE_POST_ALLOCATE = 48;

按二级分区归档

数据按时间间隔自动过期示例

以下为您列举TTL列为DATETIME、TIMESTAMP以及BIGINT/INT类型时的示例：

`DATETIME`

示例场景：

TTL列类型：DATETIME。
TTL列时区：东八区。
过期策略：TTL表（二级分区是按时间RANGE分区）保留最近3个分区。
任务时间：每天02:00开始启动一次。
TTL表和归档表分区间隔：一个月一个分区。
TTL表和归档表预建分区数：提前预建3个分区。
归档表补建分区数：补建过去48个RANGE分区（仅当创建归档表时才生效）。

示例代码：

CREATE TABLE ttl_t_2_3_0
(
  id BIGINT,
  ttl_dt_col DATETIME
)
PARTITION BY KEY(`id`)
PARTITIONS 8
SUBPARTITION BY RANGE COLUMNS(`ttl_dt_col`)
(
  SUBPARTITION sp20250401 VALUES LESS THAN ('2025-04-01'),
  SUBPARTITION sp20250501 VALUES LESS THAN ('2025-05-01'),
  SUBPARTITION sp20250601 VALUES LESS THAN ('2025-06-01')
);

-- 指定TTL
ALTER TABLE　`ttl_t_2_3_0`
MODIFY TTL
SET
TTL_ENABLE = 'ON',
TTL_CLEANUP = 'OFF',
TTL_EXPR = `ttl_dt_col` EXPIRE AFTER 1 MONTH TIMEZONE '+08:00',
TTL_JOB = CRON '0 0 2 */1 * ? *' TIMEZONE '+08:00',
TTL_PART_INTERVAL = INTERVAL(1,MONTH),
ARCHIVE_TYPE = 'SUBPARTITION',
ARCHIVE_TABLE_PRE_ALLOCATE = 3,
ARCHIVE_TABLE_POST_ALLOCATE = 48;

`TIMESTAMP`

示例场景：

TTL列类型：TIMESTAMP。
TTL列时区：东八区。
过期策略：TTL表（二级分区是按时间RANGE分区）保留最近3个分区。
任务时间：每天02:00开始启动一次。
TTL表和归档表分区间隔：一个月一个分区。
TTL表和归档表预建分区数：提前预建3个分区。
归档表补建分区数：补建过去48个RANGE分区（仅当创建归档表时才生效）。

示例代码：

CREATE TABLE ttl_t_2_3_1
(
  id BIGINT,
  ttl_ts_col TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
)
PARTITION BY KEY(`id`)
PARTITIONS 8
SUBPARTITION BY RANGE(UNIX_TIMESTAMP(`ttl_ts_col`))
(
  SUBPARTITION sp20250401 VALUES LESS THAN (UNIX_TIMESTAMP('2025-04-01 00:00:00')),
  SUBPARTITION sp20250501 VALUES LESS THAN (UNIX_TIMESTAMP('2025-05-01 00:00:00')),
  SUBPARTITION sp20250601 VALUES LESS THAN (UNIX_TIMESTAMP('2025-06-01 00:00:00'))
);

-- 指定TTL
ALTER TABLE　`ttl_t_2_3_1`
MODIFY TTL
SET
TTL_ENABLE = 'ON',
TTL_CLEANUP = 'OFF',
TTL_EXPR = `ttl_ts_col` EXPIRE AFTER 1 MONTH TIMEZONE '+08:00',
TTL_JOB = CRON '0 0 2 */1 * ? *' TIMEZONE '+08:00',
TTL_PART_INTERVAL = INTERVAL(1,MONTH),
ARCHIVE_TYPE = 'SUBPARTITION',
ARCHIVE_TABLE_PRE_ALLOCATE = 3,
ARCHIVE_TABLE_POST_ALLOCATE = 48;

`BIGINT/INT`

示例场景：

TTL列类型：BIGINT（TTL列是UNIX时间戳整数）。
TTL列时区：东八区。
过期策略：TTL表（二级分区是按时间RANGE分区）保留最近3个月数据。
任务时间：每天02:00开始启动一次。
TTL表和归档表分区间隔：一个月一个分区。
TTL表和归档表预建分区数：提前预建3个分区。
归档表补建分区数：补建过去48个RANGE分区（仅当创建归档表时才生效）。

示例代码：

CREATE TABLE ttl_t_2_3_2
(
  id BIGINT,
  ttl_ts_int_col BIGINT
)
PARTITION BY KEY(`id`)
PARTITIONS 8
SUBPARTITION BY RANGE COLUMNS(`ttl_ts_int_col`)
(
  SUBPARTITION sp20250401 VALUES LESS THAN (1743436800),
  SUBPARTITION sp20250501 VALUES LESS THAN (1746028800),
  SUBPARTITION sp20250601 VALUES LESS THAN (1748707200)
);

-- 指定TTL
ALTER TABLE　`ttl_t_2_3_2`
MODIFY TTL
SET
TTL_ENABLE = 'ON',
TTL_CLEANUP = 'OFF',
TTL_EXPR = FROM_UNIXTIME(ttl_ts_int_col) EXPIRE AFTER 1 MONTH TIMEZONE '+08:00',
TTL_JOB = CRON '0 0 2 */1 * ? *' TIMEZONE '+08:00',
TTL_PART_INTERVAL = INTERVAL(1,MONTH),
ARCHIVE_TYPE = 'SUBPARTITION',
ARCHIVE_TABLE_PRE_ALLOCATE = 3,
ARCHIVE_TABLE_POST_ALLOCATE = 48;

数据按分区数目自动过期示例

示例场景：

TTL列类型：BIGINT（非时间戳整数）。
TTL列时区：东八区。
过期策略：TTL表（二级分区是按整数RANGE分区）保留最近3个分区。
任务时间：每天02:00开始启动一次。
TTL表和归档表分区间隔：每100000一个分区。
TTL表和归档表预建分区数：提前预建3个分区。
归档表补建分区数：补建过去48个RANGE分区（仅当创建归档表时才生效）。

示例代码：

CREATE TABLE ttl_t_2_4
(
  id BIGINT,
  ttl_int_col BIGINT
)
PARTITION BY KEY(`id`)
PARTITIONS 8
SUBPARTITION BY RANGE COLUMNS(`ttl_int_col`)
(
  SUBPARTITION sp1 VALUES LESS THAN (400000),
  SUBPARTITION sp2 VALUES LESS THAN (500000),
  SUBPARTITION sp3 VALUES LESS THAN (600000),
  SUBPARTITION sp4 VALUES LESS THAN (700000)
);

-- 指定TTL
ALTER TABLE　`ttl_t_2_4`
MODIFY TTL
SET
TTL_ENABLE = 'ON',
TTL_CLEANUP = 'OFF',
TTL_EXPR = ttl_int_col EXPIRE OVER 3 PARTITIONS,
TTL_JOB = CRON '0 0 2 */1 * ? *' TIMEZONE '+08:00',
TTL_PART_INTERVAL = INTERVAL(100000,NUMBER),
ARCHIVE_TYPE = 'SUBPARTITION',
ARCHIVE_TABLE_PRE_ALLOCATE = 3,
ARCHIVE_TABLE_POST_ALLOCATE = 48;

调整TTL定义示例

TTL定义支持您通过SQL进行调整，但只会在N+1轮及以后生效。

调整任务开关（TTL_ENABLE）

默认情况下TTL_ENABLE是OFF（关闭）状态，如需开启该表的TTL任务的自动调度，可使用如下SQL：

ALTER TABLE `my_ttl_tbl`
MODIFY TTL
SET
TTL_ENABLE = 'ON';

说明

其中表my_ttl_tbl必须添加了TTL定义。

调整数据清理开关（TTL_CLEANUP）

TTL_CLEANUP在默认情况下是OFF（关闭）状态。当TTL_CLEANUP ＝ 'OFF'时，每次TTL任务将不会清理任何数据或删除任何过期的分区，但会自动为TTL表或归档表补充新的分区。因此，如果需要创建归档表以保存归档的历史数据，强烈建议只有当归档表创建完成后，再显式打开TTL表的这个数据清理开关，以避免在还没归档完成时，出现数据清理现象。

ALTER TABLE `my_ttl_tbl`
MODIFY TTL
SET
TTL_CLEANUP = 'ON';

调整数据过期定义（TTL_EXPR）

假设表my_ttl_tbl的TTL_EXPR定义是：

TTL_EXPR = `date_field` EXPIRE AFTER 2 YEAR TIMEZONE '+08:00';

将TTL的过期时期间间隔改为保留最近1年，通过重新设置TTL_EXPR的定义来修改：

ALTER TABLE `my_ttl_tbl`
MODIFY TTL
SET
TTL_EXPR = `date_field` EXPIRE AFTER 12 MONTH TIMEZONE '+08:00';

调整调度任务频率（TTL_JOB）

调整清理任务的调度频率为每天03:00：

ALTER TABLE `my_ttl_tbl`
MODIFY TTL
SET
TTL_JOB = CRON '0 0 3 */1 * ? *' TIMEZONE '+08:00';

说明

TTL任务的实际运行还会受运维时间窗口的时间限制，即所有自动触发的后台任务只能在每天指定运维时间区间内才能运行，默认的运维时间窗口是02:00~05:00（东八区时间）。

调整分区间隔（TTL_PART_INTERVAL）

调整分区间隔为一月一个分区（INTERVAL(1,MONTH)）：

ALTER TABLE `my_ttl_tbl`
MODIFY TTL
SET
TTL_PART_INTERVAL = INTERVAL(1,MONTH);

说明

在按分区归档场景，TTL_PART_INTERVAL同时会对TTL表及其归档表生效。这是因为TTL表及其归档表会同步地自动增加分区，两者分区会一直保持对齐。比如，TTL任务准备给TTL表预建'2025-06-01'的新分区，那么若TTL表存在对应归档表的话，它的归档表也会同时地增加'2025-06-01'的新分区。
在按行归档场景，TTL_PART_INTERVAL只对归档表生效。这是因为归档表是强制按TTL列进行范围分区，而原来的TTL表的分区方案保持不变。

调整附加过滤条件（TTL_FILTER）

按行归档可以动态调整TTL表在数据清理时所用的过滤条件。例如：仅清理订单状态为已完成的数据（`order_status`=1）：

ALTER TABLE `my_ttl_tbl`
MODIFY TTL
SET
TTL_FILTER=COND_EXPR(`order_status`=1);

说明

过滤条件列必须存在，否则清理任务开始后会报错。
过滤条件可以使用索引优化查询性能，建议使用索引列当作过滤条件。
不建议使用复杂的过滤条件（例如：子查询、大批量IN查询），以免影响清理性能。
过滤条件表达式和TTL列过期时间条件（ttl_col < 'yyyy-MM-dd'）是强制AND关系，即TTL_FILTER只能对过期数据进行筛选。

清空所有TTL_FILTER所定义的附加过滤条件：

ALTER TABLE `my_ttl_tbl`
MODIFY TTL
SET
TTL_FILTER=COND_EXPR(TRUE);

调整归档类型（ARCHIVE_TYPE）

您可以通过如下SQL动态调整TTL表的归档策略（即切换按分区归档或按行归档）：

-- 修改为按行归档
ALTER TABLE `my_ttl_tbl`
MODIFY TTL
SET
ARCHIVE_TYPE = 'ROW';

说明

按行归档转为按分区归档之前，需确保TTL表是按TTL列进行分区的，否则转换失败。

调整预建分区数（ARCHIVE_TABLE_PRE_ALLOCATE）

调整TTL表预建分区数目为3个：

ALTER TABLE `my_ttl_tbl`
MODIFY TTL
SET
ARCHIVE_TABLE_PRE_ALLOCATE = 3;

清除TTL定义

ALTER TABLE `my_ttl_tbl` REMOVE TTL;

重要

TTL表下有归档表时，不允许直接清除TTL定义，需先删除其下的归档表。