1. 看懂 Iceberg 仓库目录一张目录树把 metadata 和 data 说清楚1.1 删除数据后存储没变小问题就出在目录结构上第一次接触 Iceberg 时我在一张测试表上跑了一条 DELETE删掉了几百万行。结果去看底层存储目录发现数据目录的占用空间几乎没变。当时的第一反应是清理工具坏了后来才反应过来Iceberg 的存储文件设计本来就是这样的。删数据不等于删文件SQL 层面是提交了一个新快照而旧文件还留着等后续清理动作来收尾。如果你从没看过 Iceberg 表的底层存储我强烈建议先建一张表写几批数据然后去看一眼 HDFS 或对象存储上的目录。下面是一个典型的三分区表布局实际路径可能因配置不同略有差别但结构基本一致warehouse/ my_db/ logs/ metadata/ version-hint.text 00000-6a17b6a0-...-metadata.json 00001-c0a13f24-...-metadata.json snap-5234817983400231150-...-00000.avro 00002-2e1a45f7-...-00001.avro 00003-b8c8d5a1-...-00002.avro data/ dt2024-01-01/ 00000-8f0a32d2-...-00001.parquet 00001-9dc640bf-...-00002.parquet dt2024-01-02/ 00000-127d3c54-...-00003.parquet这个目录树的层次和 Hive 最大区别不是多了一个 metadata 目录而是 Iceberg 把表状态完全放进了文件本身。metadata 目录下既有.metadata.json也有.avro文件。其中.metadata.json记录表的配置、schema、分区规范和快照列表.avro文件里存放的是 manifest 和 manifest list把表和数据文件关联起来。数据目录倒是和 Hive 分区表长得差不多分区以列名值的目录层级展示里面是 Parquet 或 ORC 文件。1.2 为什么元数据文件要带版本号还得靠 version-hint 指路注意 metadata 目录里那些.metadata.json文件名是以00000、00001这样的递增版本号开头。这说明元数据文件是不可变且追加式生成的。每次对表做 commit比如追加一批数据、改写文件、清理快照都会基于当前最新版本生成一个新的.metadata.json不是覆盖旧文件。所以一张反复写入的表metadata 目录里会积累很多元数据文件。这样做的好处是Iceberg 天然拥有可回溯的版本历史。但也会带来一个问题下一次打开表时系统需要知道最新版本是哪一个。这时version-hint.text就有用了。它是一个纯文本文件里面就是一个数字比如1表示当前应该读取00001-*.metadata.json。对对象存储或者 HDFS 来说更新这个只有一个数字的小文件成本远比在分布式数据库中维护复杂索引低得多。我见过不少同事第一次看到这个目录会误以为只有.metadata.json才是整个表的元数据.avro可以随便删。这里必须强调如果误删了snap-*.avro或 manifest 文件表一样会打开失败。Iceberg 的表状态是由 metadata json、manifest list、manifest 三层配合维护的少了哪一层都会出问题。2. Manifest 与 Manifest List把文件清单拆开揉碎2.1 Manifest File 的每一行都对应一个真实数据文件Manifest 文件用 Avro 格式保存你没法直接用文本编辑器看内容但可以用引擎的元数据表去读。如果用 SparkSQL 是SELECT * FROM my_db.logs.manifests; SELECT * FROM my_db.logs.files LIMIT 5;读出来的结果会包含很多字段。我在排障时最常关注的这几列字段含义我的用法status0 表示已存在1 表示新增2 表示已删除排查某文件为什么还在被读取file_path数据文件完整路径确认文件落在哪个分区目录partition该文件所属的分区值结合分区裁剪判断record_count文件内的记录数评估小文件严重度file_size_in_bytes文件大小配合小文件合并决策lower_bounds / upper_bounds各列的最小值和最大值判断查询能否裁剪文件Manifest 的核心价值是让 Iceberg 能做到文件级剪枝。Hive 表也能按分区目录裁剪但同一个分区目录下如果有一百个 Parquet 文件Hive 通常只能全部打开Iceberg 可以拿着查询条件里id 10000这类过滤条件逐个检查 manifest 里对应列的upper_bounds如果一个文件里id的最大值都不到 10000这个文件就直接跳过。这个设计带来的额外约束是如果一个表的数据文件切得太碎manifest 本身也会变得很大统计信息的收益会被文件数量摊薄。所以 Iceberg 表和传统 Hive 表的优化思路并不完全一样核心在控制文件数量和文件大小之间的平衡。2.2 Manifest List 是为了避免每个查询都得读全部 manifest表刚写入少量数据时一个快照可能只有一个 manifest 文件你会觉得 manifest list 这层就是个多余的历史包袱。但生产环境里每次写入都可能产生多个 manifest多个写入者还会并发几小时下来一个快照可能指向几十个甚至几百个 manifest 文件。如果每次查询都把这个表历史上所有 manifest 全读一遍再判断性能会非常难看。Manifest list 就是为每个快照准备的目录索引。它记录了这个快照包含哪些 manifest、每个 manifest 里 added/existing/deleted 的文件数量和行数以及每个 manifest 覆盖的分区范围。查询引擎在决定要不要读某个 manifest 时先看 manifest list 里记录的统计范围能挡住一大半无关扫描。我自己在调优慢查询时踩过一个坑只盯着数据文件大小看把 Parquet 文件都压到 500MB 左右但忽略了一个快照下面挂了几百个 manifest。结果每次扫描光解析 manifest 就花了好几秒。后来才明白保持合适的文件大小之余也要关注写入模型是不是太频繁、每个 commit 是不是太小。manifest 文件过多本质上是写入碎片化的一种表现。2.3 Metadata JSON 是表的总控台可不是一份简单配置Metadata JSON 的体积通常比 manifest 大不少因为它把所有快照信息都收进去了。读这个文件我一般先看几个字段schema定义表结构partition-spec定义当前分区规范current-snapshot-id指向当前快照snapshots数组列出所有快照每个快照里有 commit 时间、操作类型、新增文件数、以及最重要的manifest-list路径所以说整个 Iceberg 表的读取是从 metadata json 开始的。一个常见故障是表运行很长时间后 metadata json 越来越大每次 commit 生成新文件时都要复制和追加大量历史快照信息写路径越来越慢。这时不是去改什么参数而是应该做快照清理。有一次我看一张线上表的 metadata json已经涨到一百多 MB打开文件都费劲。用expire_snapshots清掉三个月前的快照后文件直接瘦到十几 MB。这个优化对写路径的影响比读路径更明显很多同事会忽略。3. Snapshot 不是备份不可变文件与元数据指针的设计逻辑3.1 不可变数据文件才是 Iceberg 的基石Iceberg 采用了一个看起来成本很高的原则数据文件一旦写入就永远不修改。新写入的数据追加成新文件更新数据则重写受影响的数据文件删除数据则要么重写文件要么写入独立的删除文件。无论哪种操作都不会去动已经写好的文件。这套设计从哪里体现出价值最大的点是与分布式存储的兼容性。HDFS 上文件覆盖不是原子的对象存储上更麻烦但新建一个文件并更新某个指针却是相对可靠的操作。Iceberg 把改表状态这个动作收敛成提交新文件 原子切换元数据指针这才能让它在 S3、OSS 这样的对象存储上稳定运行。另一个直接收益是读取一致性。多个引擎并发读同一张表不用加锁因为读到的永远是一个完整快照。文件不可变意味着任何引擎都不会在一个查询执行过程中看到写到一半的文件。这种隔离能力如果靠行级锁来实现成本高得多。3.2 清理文件为什么早不了快照隔离的代价回到开头那个删除数据后存储没变小的现象。Iceberg 执行 DELETE 时新快照已经生成旧数据文件也被标记为删除但物理文件还老老实实躺在磁盘上。原因很简单如果有另一个查询正在用旧快照做时间旅行这些旧文件可能还需要被读取。这不是 Iceberg 的缺陷而是快照隔离的必然代价。你不可能一边保留历史瞬间的一致性视图一边立刻把历史文件物理删除。所以 SQL DELETE 之后存储没立刻释放是正常现象。真正要释放空间需要等到你确认不再需要历史快照手动或定期触发expire_snapshots。时间旅行能力最常用的场景是应对误操作。有人对着整张分区表跑错了一个 UPDATE或者上游数据任务写错了数据只要快照还在就能用SELECT * FROM my_db.logs FOR SYSTEM_VERSION AS OF 5234817983400231150这样的语句读回修改前的数据再定向修回。这也是为什么我建议不要过度激进地清理旧快照至少保留一个能覆盖数据回溯窗口的时间范围。3.3 并发写入不靠锁靠乐观提交重试如果有两个 Spark 任务同时写一张 Iceberg 表Iceberg 不会下发锁而是让每个任务基于当前最新元数据各自准备新快照提交阶段通过 catalog 做一次比较并交换的操作。大体流程是任务 A 和任务 B 都读到当前 metadata 版本00001-*.metadata.json双方各自写数据文件和 manifest生成新的 metadata 版本00002-*.metadata.json和00003-*.metadata.json任务 A 先提交成功把 catalog 中的 metadata 位置指向00002任务 B 尝试提交时发现当前版本已经是00002和自己基于的00001不一致提交失败任务 B 重新读取00002基于新版本再次执行写入操作重试成功后生成00003这个机制保证了多写者场景下不会出现表状态被覆盖的问题。代价是任务 B 可能需要重算一部分数据文件但在分布式写入场景里这个代价通常可以接受。排查写入失败时如果错误信息里带着类似commit conflict或metadata location changed的提示多半就是并发提交冲突重试或降低写并发度就能缓解。4. 一条查询如何从表名精确定位到 Parquet 文件4.1 读取链路从 catalog 到文件的五个步骤Iceberg 查询最后能落成一个文件集合一路上会有多次裁剪。完整的路径是这样走的从 CatalogHive Metastore、REST 或 JDBC拿到表当前 metadata 文件的路径读取 metadata json得到current-snapshot-id和对应快照的manifest-list位置读取 manifest list按分区范围和文件数统计初步筛选 manifest读取筛选出的 manifest按列统计信息进一步过滤数据文件对最终命中的 Parquet/ORC 文件做并行读取和执行如果某一步没有做后续文件扫描范围就会扩大。比如查询里带了一个分区条件dt 2024-01-01理论上在步骤 3 就能把大量 manifest 过滤掉。但如果表经过分区规范演进某些 manifest 对应的分区 spec 不同裁剪逻辑会更复杂裁剪效果也可能变差。这在生产环境里是真实存在的优化盲区。4.2 统计信息不是万能的有些场景剪枝会失效Manifest 里的lower_bounds和upper_bounds是文件级裁剪的底气但这些统计信息的可靠性取决于写入时的文件格式和参数。比如 Parquet writer 没有开启写入统计信息功能、或者写入过程中遇到带 NaN 的值边界可能不会按预期填充。还有一种常见的情况是列本身包含大量 NULLbounds 可能直接为空那么查询引擎对这个列的裁剪就会退化。排查查询剪枝效果时我的习惯是打开执行计划看FileScan阶段读了多少文件。用 Spark 的话可以临时设置开启detailed执行计划或直接看SELECT * FROM my_db.logs.files中对应文件的数量和统计值和预期对比。如果明明加了过滤条件扫描文件数却没有减少先检查该列是否在lower_bounds/upper_bounds中有值。没有值的话问题不一定出在 SQL 写法而是文件写入时就没把边界统计好。4.3 隐藏分区让分区列不再出现在建表语句里使用 Hive 时分区列是额外字段吗其实不是分区列必须出现在 DDL 中比如PARTITIONED BY (dt STRING)查询也要记住它。Iceberg 的隐藏分区设计则完全不同用户可以按照任意业务列和时间函数组合定义分区规范Iceberg 自动生成对应的分区值并写入目录。举例来说表里有一个event_time字段分区规范是days(event_time)那么实际分区目录会表现为event_time_day2024-01-01。查询时不需要显式维护这个字段引擎同样会拿过滤条件去做分区裁剪。这个机制让分区对用户隐藏起来也减少了因为分区字段维护错误导致的数据错位问题。5. 联邦查询与开放格式为什么不同引擎能读同一份文件5.1 表格式是公共的不是某个引擎的私有财产Iceberg 的存储文件层是一套公开规范数据文件默认用 Parquet 或 ORC元数据文件用 Avro 和 JSONCatalog 用 Hive Metastore、REST 或 JDBC 这类通用组件封装。它不绑定某个计算引擎所以 Spark、Flink、Trino、Presto、Doris 都能通过各自的 connector 读同一张表。这在联邦查询场景里非常关键。所谓联邦查询简单说就是通过一个查询引擎去访问多个不同数据源再在一条 SQL 里做关联。Iceberg 作为其中一个数据源最大的优势不是存储格式多先进而是文件层完全开放、元数据结构稳定。引擎开发商不需要拿到 Iceberg 的私有二进制协议照着公开规范就能实现对表文件的并行读取和统计下推。我实际维护的一套数据环境中Flink 负责实时写入 IcebergSpark 负责离线分析Trino 负责临时查询和联邦 join三者同时跑在同一张表上没有出现过文件锁冲突或者数据读一半的问题。这在 Hive 表时代不是做不到但 Iceberg 把文件不可变和快照隔离做成了规范和默认行为省掉了很多协调成本。5.2 Trino 做联邦查询时Iceberg 的文件统计帮了大忙如果你在 Trino 里配了一个iceberg数据源又配了一个mysql数据源一条 SQL 可以长成这样SELECT t.app_id, count(*), sum(t.revenue) FROM iceberg.app_logs AS t LEFT JOIN mysql.dim_app_info AS d ON t.app_id d.app_id WHERE t.dt DATE 2024-01-01 AND t.revenue 0 GROUP BY t.app_id;执行时Trino 会把t.dt、t.revenue这些条件下推给 Iceberg connectorconnector 利用 manifest 和文件统计信息做裁剪只读必要的数据文件。然后 result 再和 MySQL 返回的维度表做 join。整个过程里Iceberg 侧的存储文件只是被按需读取并没有被引擎锁住其他实时任务可以继续往表里写。这种场景在走向服务化和数据编排时几乎避不开。所以在设计新表时我会有意识地选几个高频过滤字段注意写统计信息比如业务时间、用户 ID这样即便以后接联邦查询或新的查询引擎下游也能拿到好的裁剪收益。5.3 对象存储上的缓存策略要跟上联邦查询引擎读 Iceberg 表时会产生大量对 manifest 和 manifest list 的小文件读取请求。尤其 Trino、Presto 这类引擎每次查询的 coordinator 和 worker 都要做元数据解析如果每次冷启都去对象存储拉一遍所有元数据文件请求延迟会很难看。常见的优化手段是在查询引擎侧开 manifest 缓存和相关统计缓存同时结合对象存储上的文件布局做分区目录优化。生产上我更倾向于把表的 metadata 路径和 data 路径分开配置metadata 放到性能更好的存储介质或单独的 bucket数据文件保留在大容量存储上。这样两类文件的读写负载不会相互干扰排查问题时也更容易定位。6. 存储文件的清理与合并动手给表和目录瘦身6.1 小文件合并是 Iceberg 表的必修课Flink 实时写 Iceberg 的场景里小文件问题几乎必然出现。Checkpoint 间隔太短、写入并发太高、目标文件大小参数没调都会导致一小时内产生大量几 MB 甚至几百 KB 的文件。文件数量一多manifest 变大、查询时打开文件数量暴增整个表就像得了慢性病。合并的手段主要有两种直接改写数据文件或者调整写入链路参数从源头减少碎文件。Spark 里执行重写常见用法如下CALL spark_catalog.system.rewrite_data_files( table my_db.logs, strategy binpack, options map( min-file-size-bytes, 52428800, target-file-size-bytes, 1073741824 ) );首先明确一点具体语法取决于 Spark 版本和 Iceberg 版本生产环境务必先在小表验证。这个操作会把小于阈值的文件合并到目标大小但会产生新快照和新数据文件。重写完成后存储占用短期内反而可能上升因为旧文件并没立刻删除。需要配合快照过期才能真正释放空间。写完数据链路参数我也专门调过多次。对于持续写入的场景在源端合并 Flink 的写入行为比事后反复 rewrite 更经济。比如把 checkpoint 间隔和文件关闭阈值调整到合理范围减少超小文件直接落表。事后 rewrite 适合做周期性维护而不是把全部希望押在它上面。6.2 快照过期和孤儿文件清理要分开做别混为一谈很多维护任务我会把expire_snapshots和remove_orphan_files放在一起跑但这两个动作解决的问题完全不同。expire_snapshots清理的是历史快照和因此不再被引用的数据文件。它的典型使用方式是按时间来保留窗口比如保留最近三天快照。清理之后老数据文件会被物理删除表目录占用显著下降。ALTER TABLE my_db.logs EXECUTE expire_snapshots(TIMESTAMP 2024-01-01 00:00:00);remove_orphan_files清理的是那些已经不被任何快照引用、但仍残留在目录里的文件。这类文件通常来源于写入过程中崩溃产生的中途文件、或者失败提交留下的孤儿 manifest 和数据文件。清理命令也支持指定时间阈值避免误删正在处理的文件。ALTER TABLE my_db.logs EXECUTE remove_orphan_files(TIMESTAMP 2024-01-01 00:00:00);在生产环境我会先跑 expire确认数据文件已经被正确删除再跑 remove_orphan_files。如果反过来先清理孤儿文件可能会把某个尚未提交成功的中间文件误判为孤儿直接删掉导致正在运行的写入任务失败。另外要注意这两个操作本身也是 commit会生成新的快照所以频繁清理也会带来元数据文件增长。我的建议是定期维护比如每天凌晨跑一次不要想到就执行。6.3 几个容易踩的存储文件坑第一version-hint.text意外丢失后表打不开。这种情况多出现在手动操作对象存储导致文件被删除或覆盖。如果 metadata 目录里还有高版本号的.metadata.json可以手动创建一个version-hint.text把内容改成最高版本号再尝试读取表。这算是一种应急恢复不是官方建议操作前最好保留完整目录副本。第二手动删了数据目录里的文件查询报错。Iceberg 的元数据里仍然维护着这些文件的路径文件不在了就会直接报 FileNotFound。不要通过手动删除文件来清理表正确做法是走快照过期或 remove_orphan_files。第三清理节点上仍然有查询在跑旧快照。如果 expire_snapshots 的执行时间和某个长查询重叠长查询读取的文件可能已经被删除。结果就是查询中间报错。维护窗口要避开业务高峰宁愿保留更长的快照时间也不要让任务失败影响数据产出。还有一个容易被忽略的配置项是write.metadata.path。有些集群会把 data 和 metadata 放在两个不同的路径如果你排查问题时只在data目录里翻文件却找不到元数据可以看看表的 properties 里是否单独指定了 metadata 路径。我自己遇到过一次因为部署脚本配错了路径导致 metadata 写到了一个空目录表一直处于无法提交状态。看一眼表的元数据配置这类问题其实几分钟就能定位。最后分享一个实践性的建议在本地或测试环境建一张小表反复执行 append、delete、rewrite、expire 操作每执行一步都去元数据目录看一眼文件变化。把每次 commit 对应哪些文件新增、哪些文件被置为删除在脑子里过一遍。这套流程走下来对 Iceberg 存储文件的理解会非常扎实以后遇到线上存储问题也不容易慌。