增量Clustering功能详解配置指南-数据湖构建-阿里云-数据湖构建(DLF)-阿里云帮助中心

增量 Clustering说明

增量 Clustering 是 DLF 针对 Paimon Append 表 提供的一种数据布局优化机制。开启该功能后，系统将定期对表中的部分数据文件执行聚类重写操作，在保持较低资源开销的同时，持续优化数据物理存储结构，从而显著提升基于聚类键的查询效率。

对于 bucket > 0 的 Append 表（Append Bucketed 表），当查询条件中包含完整 bucket-key，且每个 bucket key 都使用等值条件（= 或 IN 谓词）时，Paimon 会先进行 bucket 级别的过滤。在 bucket 过滤的基础上，如果您希望继续提升查询效率，开启增量 Clustering 后，系统可以继续利用聚类键进行高效的 data skipping。

该功能特别适用于以下场景：

期望提升 Append 表的查询速率
表持续接收增量写入
查询条件中频繁使用某些列作为过滤条件

核心能力

增量聚类（Incremental Clustering）
每次执行时，系统会选择部分数据文件进行聚类重写。重写后的文件在指定的聚类列上具有更紧凑的统计范围（如 min/max 值区间更小），使得查询引擎能够高效跳过无关数据文件，大幅减少扫描量。数据规模越大，性能提升效果越显著。
小文件合并（Small File Compaction）
聚类重写过程会遵循 target-file-size 配置，自动将多个小文件合并为接近目标大小的大文件，减少文件数量，提升读取效率。
历史分区全量聚类（可选）
对于长时间未更新的“历史分区”，系统可在资源允许时自动触发 Full Clustering（全量聚类），进一步优化其查询性能。

使用前提与限制

增量 Clustering 目前仅支持满足以下条件的 Paimon Append 表：

不支持启用行级追踪（row-tracking.enabled = true）的表。
不支持启用数据演进（data-evolution.enabled = true）的表。
不支持启用 deletion vectors（deletion-vectors.enabled = true）的 Append Bucketed 表。

重要

若您的 Append 表单次增量数据超过 256 GB，可能因资源限制影响聚类效果。建议联系阿里云技术支持，获取定制化配置建议。

开启增量 Clustering

目前 DLF 控制台暂未提供图形化配置入口，需通过 SQL 或表属性手动设置以下参数：

配置项	值示例	是否必填	类型	说明
`clustering.incremental`	`true`	是	Boolean	启用增量 Clustering。默认为 `false`。
`clustering.columns`	`'user_id,event_time'`	是	String	聚类列（也称排序列）。多个列以英文逗号分隔，如 `'col1,col2'`。建议选择高频查询条件中使用的过滤列。不推荐将分区字段或 bucket keys 设为聚类列。
`clustering.strategy`	`'zorder'` / `'hilbert'` / `'order'`	否	String	聚类算法策略。若未显式指定，系统按聚类列数量自动选择： • 1 列：`order` • 2–4 列：`zorder` • 5 列及以上：`hilbert`

对于 bucket > 0 的 Append 表，Paimon 默认会保留写入数据的有序性，开启增量 Clustering 需要舍弃掉有序性保证，您还需额外设置：

配置项	值	是否必须	类型	描述
`bucket-append-ordered`	`false`	是	Boolean	默认为 `true`，开启 Incremental Clustering 必须设为 `false`。

示例 1（针对 bucket = -1 的 Paimon Append 表）：

ALTER TABLE catalog.db.my_table SET (
  'clustering.incremental' = 'true',
  'clustering.columns' = 'event_time,user_id',
  'clustering.strategy' = 'zorder'
);

示例 2（针对 bucket > 0 的 Paimon Append 表）：

ALTER TABLE catalog.db.my_table SET (
  'bucket-append-ordered' = 'false',
  'clustering.incremental' = 'true',
  'clustering.columns' = 'event_time,user_id',
  'clustering.strategy' = 'zorder'
);

调整聚类执行频率

增量 Clustering 默认每 1 小时 触发一次调度。您可通过以下参数调整检查间隔：

配置项	值示例	是否必填	类型	说明
`morax.compact.check-interval`	`1h`	否	Duration	调度执行间隔。最小值为 `5min`。缩短间隔可加快增量数据的优化速度，但会增加系统负载。

示例：设置为 30 分钟

ALTER TABLE catalog.db.my_table SET ('morax.compact.check-interval' = '30min');

启用历史分区自动 Full Clustering（可选）

重要

当前仅 bucket=-1 的表支持历史分区自动 Full Clustering。

对于长期无新增数据的分区（历史分区），可启用自动 Full Clustering 以提升其查询性能。

配置项	值示例	是否必填	类型	说明
`clustering.history-partition.idle-to-full-sort`	`3d`	是	Duration	分区在指定时间内无更新即视为历史分区。
`clustering.history-partition.limit`	`5`	否	Integer	单次任务最多处理的历史分区数量。默认为 5。

重要

历史分区的 Full Clustering 仅在系统资源富余时执行，优先级低于活跃分区的增量聚类。

示例：

ALTER TABLE catalog.db.my_table SET (
  'clustering.history-partition.idle-to-full-sort' = '3d',
  'clustering.history-partition.limit' = '3'
);

查看分区优化情况

Paimon 表的数据文件具有level属性，对于 Append 表而言：

初始写入文件的 level = 0；
经过聚类优化后的文件 level 为 1 至 5。

可通过查询 $files 元数据表确认聚类是否生效：

SELECT *
FROM `catalog_name`.`database_name`.`table_name$files`
WHERE `partition` = 'your_partition_value';

若返回结果中存在 level > 0 的文件，说明该分区已成功执行聚类优化。

说明

可结合查询执行计划或实际查询耗时，评估聚类带来的性能提升。