TTL（Time To Live）是指数据的生存时间，在 ByteHouse 企业版中 TTL 可以按照删除级别和行为进行分类。

基本概念 #

按删除级别分类的 TTL 包括 Partition-level TTL 和 Row-level TTL：

• Partition-level TTL：要求 TTL 涉及的列必须是 Partition 字段的一部分，同一 partition 内的数据在 TTL 过期时可执行统一的动作（删除或移动到其他磁盘）。
• Row-level TTL：TTL 字段可由任意列组成，过期的数据在 Merge 的时候从磁盘删除或 parts 在其包含的所有数据都过期时被移动到其他磁盘。

按行为分类的 TTL 包括 Delete TTL 和 Move TTL：

• Delete TTL：会在 TTL 过期时将数据删除。
• Move TTL：会在 TTL 过期时将数据移动到其他磁盘或者磁盘组（Volume）。

另外，对于修改 TTL 也有一定的使用限制：

• 对于 Partition-level TTL，在 ByteHouse 企业版 2.4 以上版本，对于 Delete TTL 和 Move TTL 都支持了实时计算，所以当修改 TTL 后，旧数据也可通过 TTL 实现自动删除或移动到其他磁盘。
• 对于Row-level TTL，因为其 TTL 信息存储在磁盘，修改TTL后需执行Materialize TTL修改旧parts的TTL信息，旧parts才可按新的TTL生效。

差异对比 #

Partition-level TTL 和 Row-level TTL都可以实现数据的删除或移动，但其在数据的删除和移动上的行为会有所差别。另外，当用户通过Alter命令修改TTL后，两种TTL的表现也有所差别，具体参考下表。

表引擎支持情况 #

MergeTree Family 表引擎对于以上 TTL支持情况如下表。

使用示例 #

基本语法 #

TTL 常常与配冷热分层移动因子策略一同配置，详情可参考冷热分层存储。
基本示例如下：

-- 建表时增加TTL
CREATE TABLE example_table on cluster xxxx
(
    d Date,
    a Int
)
ENGINE = HaMergeTree(...)
PARTITION BY d
ORDER BY d
TTL d + INTERVAL 1 MONTH DELETE,
    d + INTERVAL 2 WEEK TO DISK 'S3'
SETTINGS index_granularity = 8192, storage_policy = 's3_cold';

-- 修改 TTL 策略
ALTER TABLE table_name on cluster cluster_name 
MODIFY TTL toDate(create_date) + toIntervalDay(30) TO DISK 's3';

若如此配置，多级 TTL 和移动因子策略会同时生效。即数据满足了 TTL 的移动条件，或者冷热因子的移动条件后，都会发起热数据向冷数据的移动。

Partition-level TTL 与 Row-level TTL #

以下为Partition-level TTL 和 Row-level TTL 使用示例。

Case 1:
PARTITION BY p_date

TTL p_date + interval 10 day -- Partition-level TTL
TTL toDate(x) + interval 10 day -- Row-level TTL: x 不是partition by的字段

Case 2:
PARTITION BY toDate(event_time), toHour(event_time)

TTL toDate(event_time) + interval 10 day -- Partition-level TTL, toDate(event_time)是partition by中的一个字段
TTL event_time + interval 10 day -- Row-level TTL, event_time不是partition by中的一个字段

Case 3:
PARTITION BY event_time
 
TTL toDate(event_time) + INTERVAL 1 MONTH -- Partition-level TTL, event_time是partition by字段

Delete TTL 与 Move TTL #

以下为Delete TTL 和 Move TTL 使用示例。

TTL p_date + interval 10 day -- Delete TTL, p_date超过10天的数据将会被删除
TTL p_date + interval 10 day TO Disk 'disk_s3' -- Move TTL, p_date超过10天的数据会移动到disk_s3
TTL event_time + interval 10 hour -- Delete TTL
TTL event_time + interval 10 hour TO Volume 'volume_s3' -- Move TTL

需要注意的是，一张表只能指定一个Delete TTL，可以指定多个Move TTL；一张表的TTL可由0~1个Delete TTL 和0~n个Move TTL组成。

TTL p_date + interval 10 day -- Yes, 仅包含1个Delete TTL
TTL p_date + interval 10 day, event_time + interval 10 hour -- Error: 最多只能有一个Delete TTL
TTL p_date + interval 10 day TO disk 'disk_s3', event_time + interval 10 hour TO Volume 'volume_s3' -- Yes, 包含0个Delete TTL和2个Move TTL
TTL p_date + interval 20 day， p_date + interval 10 day TO disk 'disk_s3', event_time + interval 10 hour TO Volume 'volume_s3' -- Yes, 包含1个Delete TTL和2个Move TTL

修改系统表 TTL #

由于系统表在升级时可能会重建，所以修改系统表的 TTL 时，不仅要修改表的 TTL，还需要修改集群配置文件中系统表相关的配置。
操作步骤：

1. 通过 ALTER 修改系统表 TTL。

   -- 以 system.query_log 为例
   ALTER TABLE system.query_log MODIFY TTL event_date + INTERVAL 10 DAY SETTINGS materialize_ttl_after_modify = 0;
   
   ALTER TABLE system.query_log DROP PARTITION WHERE xxx; -- 按条件删除较老的分区，该操作执行较快
   

   参数说明：
   materialize_ttl_after_modify：

   • 设置为 1，则会生成 mutation 删除过期数据，但比较耗资源，不建议在数据量大或集群负载高时设置为 1。
   • 设置为 0，代表不要对旧 part 做 materialize TTL 操作，但旧数据也不会被删除，需要通过 drop partition 删数据。

2. 修改集群配置文件，需修改的参数示例如下，配置操作请参见配置集群参数。

   <query_log>
       <database>system</database>
       <flush_interval_milliseconds>100000</flush_interval_milliseconds>
       <partition_by>event_date</partition_by> 
       <table>query_log</table>
       <ttl>event_date + interval 30 day</ttl> 
   </query_log>
   

   注意

   填写时请注意以下参数配置：

   • 配置文件中 <partition_by> 之前设置的值请保持原样，无需改动。
   • 需要通过 <ttl>ttl_expr</ttl> 修改 TTL 表达式，最好和当前表的 TTL 保持一致，该 TTL 将在下次重新生成 query_log 表时生效。