事实核验：2026-08-16 · 状态：维护中

记录仅说明核验时间与维护状态，不保证适用于所有环境；使用前请留意正文中的版本、适用条件与风险提示。

warning 适用范围与待维护事项

本文适用于已掌握 Spark、Iceberg 快照及存储路径机制的维护人员，提供治理流程而非可直接投产的脚本。尚未限定 Spark/Iceberg 版本、Catalog 配置及所需扩展；latest 文档和既有核验日期不代表本轮已验证兼容性。SQL 中固定日期仅为示例，须按实际执行时间及最长写入、补数、恢复和历史读取窗口重新计算。生产删除前应检查候选文件（版本支持时使用 dry_run）、路径一致性及保留的分支和标签；快照过期、孤儿清理不能依靠普通快照回滚恢复已删除文件。

Iceberg表维护与小文件治理

abstract 本文目标

区分快照过期、孤儿文件清理、数据文件合并和 Manifest 重写
用元数据表判断问题，而不是固定周期盲目执行维护任务
理解保留期、并发写入和对象存储路径变化带来的数据风险
建立可以回滚、审计和验证的维护流程

前置阅读：Iceberg核心架构与表演进、Iceberg Spark快速实践。

为什么Iceberg仍需要维护

Iceberg 让写入变成快照提交，但不会自动保证文件布局永远健康。高频流式写入、失败重试和查询模式变化会逐渐积累：

大量历史快照和元数据文件；
未被任何快照引用的孤儿文件；
数量很多、体积很小的数据文件；
与查询过滤条件不匹配的 Manifest 分组。

这些问题分别对应不同操作，不能用一个“全量清理脚本”粗暴处理。

四类维护操作

操作	解决的问题	主要风险
Expire Snapshots	历史快照和不再需要的数据引用持续累积	失去时间旅行和回滚窗口
Delete Orphan Files	失败任务留下未被元数据引用的文件	误删仍在写入或路径表示不同的有效文件
Rewrite Data Files	小文件过多、文件打开与规划成本高	重写放大、并发冲突和资源占用
Rewrite Manifests	Manifest 过碎或分组与过滤条件不匹配	额外提交和短期规划开销

先做基线检查

SELECT
    count(*) AS file_count,
    round(avg(file_size_in_bytes) / 1024 / 1024, 2) AS avg_mb,
    min(file_size_in_bytes) AS min_bytes,
    max(file_size_in_bytes) AS max_bytes
FROM prod.analytics.orders.files;

SELECT committed_at, snapshot_id, operation
FROM prod.analytics.orders.snapshots
ORDER BY committed_at DESC;

预期结果：获得当前快照文件规模和快照增长速度。只有在看到文件数、平均大小、查询规划时间或对象存储请求成本出现问题后，才应制定对应维护动作。

过期历史快照

成功提交的数据变更通常会产生新快照；失败或尚未提交的写入不一定产生快照。官方建议定期过期不再需要的快照，以控制元数据体积并删除不再被任何保留快照引用的数据文件。

CALL prod.system.expire_snapshots(
    table => 'analytics.orders',
    older_than => TIMESTAMP '2026-08-01 00:00:00',
    retain_last => 10
);

参数和过程名称以当前 Spark/Iceberg 版本为准。执行前应回答三个问题：

业务承诺的时间旅行窗口是多少？
灾备和审计是否依赖历史快照？
是否有长时间运行的读任务仍绑定旧快照？

warning 快照过期不可当作普通缓存清理

快照从元数据移除后，相关时间旅行和回滚能力也会消失。先做只读预估、审批和备份策略确认，再执行生产清理。

删除孤儿文件

孤儿文件是存储中存在、但没有被表元数据引用的文件。失败写入可能产生孤儿文件，但“当前看不到引用”不等于“可以立刻删除”。

CALL prod.system.remove_orphan_files(
    table => 'analytics.orders',
    older_than => TIMESTAMP '2026-08-13 00:00:00'
);

官方文档特别警告：保留间隔如果短于任何写任务可能持续的时间，清理过程可能把进行中的文件当作孤儿文件，从而损坏表。官方默认间隔为三天，但生产值仍应根据最长写入、补数和故障恢复时间设定。

对象存储 endpoint、HDFS authority 或路径规范发生变化时，也要确认元数据路径与文件系统枚举结果一致；同一文件的字符串路径不一致可能导致误判。

合并小数据文件

流式或微批写入常产生大量小文件。文件过多会增加 Manifest 元数据、对象存储请求和查询打开文件的成本。

CALL prod.system.rewrite_data_files(
    table => 'analytics.orders',
    options => map(
        'target-file-size-bytes', '536870912'
    )
);

512 MB 只是演示值，不是通用答案。目标大小要结合查询扫描粒度、对象存储吞吐、写入并发、下游引擎和分区规模确定。优先按问题分区逐步重写，避免一次全表重写造成资源峰值。

重写Manifest

Manifest 相当于数据文件索引的一部分。写入模式和查询过滤模式长期错位时，即使数据文件大小正常，规划阶段也可能读取过多 Manifest。

重写 Manifest 的目标是重新组织文件条目，通常按分区聚集，以改善基于分区统计信息的 Manifest 剪枝；它不会改变数据文件布局，也不等于按任意查询过滤维度重新生成统计信息。它不是每天必跑的固定任务，应结合规划耗时、Manifest 数量和过滤效果判断。

维护编排与并发控制

推荐流程：

收集文件、快照、Manifest 和查询性能基线。
计算影响范围并明确保留窗口。
在测试表或单一分区验证命令。
避开大规模写入窗口，限制维护任务并发。
执行后重新读取元数据表和核心查询结果。
记录输入参数、快照 ID、运行耗时和释放空间。
若出现冲突，停止自动重试并判断是否需要重新规划。

调度系统可以参考 DolphinScheduler生产运维与故障排查，但维护任务的安全门禁必须由 Iceberg 表状态驱动，不能只靠 Cron。

验收指标

文件数量下降，平均文件大小接近目标区间；
核心查询结果行数、聚合指标与维护前一致；
最新快照可读，保留窗口内时间旅行仍可用；
查询规划耗时和对象存储请求量没有恶化；
写入作业没有出现持续提交冲突；
释放空间与预估范围基本一致。

练习

创建一张测试表，执行 20 次小批量写入并观察文件数量。
只对一个分区执行数据文件重写，比较前后查询计划。
制定快照保留策略，明确“至少保留数量”和“最长保留时间”。
模拟失败写入留下文件，验证孤儿清理的时间门槛。