Apache Iceberg 1.12.0 于 2026-09-30 发布：765 个 PR 删掉 14 处弃用能力与 Spark 3.4 支持。 这条版本更新的落点是「前置部署」Forward Deployed Engineer（FDE）每天要碰的那一段：湖仓 lakehouse 的「表格式」 table format 一升版本，Spark 与 Flink 的运行时 JAR、提交器行为、元数据兼容性都会跟着变，而这些表的持有者往往不是写代码的人。对「前置部署」Forward Deployed Engineer（FDE）来说，判断客户现场这套 Iceberg 能不能从 1.11.0 升到 1.12.0、要改哪几行代码，比读一遍新功能清单重要得多。 发布事实先钉死：Apache 软件基金会的 Apache Iceberg 项目于 2026-09-30 推送正式标签 apache-iceberg-1.12.0，本次发布经理是 Neelesh Salian。该版本走完三轮候选投票：RC0 于 2026-09-17 出包、RC1 于 2026-09-22、RC2 于 2026-09-25，RC2 的投票窗口开到 2026-09-29 14:00 太平洋时间，随后发布正式标签。Maven 中央仓库已经可以拉到 org.apache.iceberg:iceberg-core:1.12.0。 标签自带的自述文件列出 765 个 PR，其中 476 个不是构建与文档类改动，按模块分布是 Core 121 条、Flink 88 条、Spark 35 条、Parquet 33 条、API 26 条、Kafka Connect 15 条、Spec 12 条、Data 11 条、Arrow 7 条、ORC 6 条。这组数字本身就是决策依据：改动重心在 Core 与 Flink，「前置部署」Forward Deployed Engineer（FDE）接手的存量集群如果以 Flink 流式入湖为主，受影响面比 Spark 批处理更大。 先看会直接挡住升级的门槛，这两条比任何新功能都优先。 第一条是引擎矩阵收窄。1.12.0 的 gradle.properties 里 knownSparkVersions 只剩 3.5、4.0、4.1、4.2，knownFlinkVersions 只剩 1.20、2.1、2.2、2.3，配套的 PR 是 Spark 3.4 支持移除，编号 #14122。改动前的状态是 1.11.0 已经把 Spark 3.4 标为弃用，运行时可选项里还留着它；改动后下载页给出的 Spark 运行时 JAR 只有 Spark 4.1（Scala 2.13）、Spark 4.0（Scala 2.13）、Spark 3.5（Scala 2.12 与 2.13）四条，Flink 侧只有 2.1、2.0、1.20 三条，再叠加 aws、gcp、azure 三个 bundle JAR。也就是说仍在 Spark 3.4 上的集群，升级路径必须先跨到 Spark 3.5，这一步不是换一个 Iceberg 版本号能解决的。 第二条是 JDK 门槛。1.12.0 的 build.gradle 显式断言构建 JDK 必须是 17 或 21，源码与目标兼容级别都写成 17，改动链条是 1.11.0 已经删掉 Java 11 支持（PR #14400），1.12.0 把这个门槛固化进构建脚本。「前置部署」Forward Deployed Engineer（FDE）在客户里做升级评估时，要连带确认的不只是 Iceberg 自己：CI 镜像、Spark 提交机的 JAVA_HOME、打包 bundle 用的基础镜像都得落在 17 或 21 上，否则会在编译期就直接失败，而不是运行期报错。 本次最需要提前处理的是弃用能力的整批删除，这也是它比普通小版本更危险的原因。 根因是 Apache Iceberg 的弃用策略：一个 API 被标记为弃用时会写死一个预定删除版本，到期就整批删掉，不给缓冲。1.12.0 就是那批预定版本的到期点——原文里逐条写明删除动作的条目共有 14 条，其中 12 条由同一位贡献者一次性提交。改动前的表现是编译时只出现弃用警告，代码照样能跑；改动后这些符号不存在了，编译直接失败。所以升级的第一个动作不是改配置，而是在 JDK 17 或 21 下重新编译一遍。 14 条清单逐条列出来，方便对着自己的代码库勾选。第 1 条是 Spark 3.4 支持移除（#14122）。第 2 条是 Core 与 ORC 里旧「分区统计」partition statistics 的读写功能移除（#14998）。第 3 条是 Flink 里 RewriteDataFiles.Builder.filter(Expression) 这个重载被删（#17624）。第 4 条是 Spark 的 SparkReadConf、SparkWriteConf 与 SparkSchemaUtil 里弃用和无人使用的方法被删（#17626）。 第 5 条是 Kafka Connect 的 TableReference 与 IcebergWriterResult 成员被删（#17623），第 6 条是 BigQuery 目录的弃用属性常量被删（#17625），第 7 条是 Spark 的 SparkFilters 被删（#17702），替代品在同一版本线里由 #16616 指明，是 SparkV2Filters。第 8 条是 Data 模块的 GenericAppenderFactory 与 BaseFileWriterFactory 被删（#17696），第 9 条是 Spark 4.0 与 4.1 里弃用的 SparkTableUtil 方法被删（#17703）。 第 10 条是 Core 里计划在 1.12.0 删除的弃用方法与字段被批量删净（#17700），第 11 条是 AWS 模块里弃用的 S3 signer 类与属性被删（#17627），这一条对自建对象存储或自定义签名链的客户现场影响最大。第 12 条是 Core 的 DataReader 被删，替代品是 PlannedDataReader（#17699）。第 13 条是 Core 里弃用的 REST namespace 编码辅助方法被删（#17697）。第 14 条是 Core 的 HadoopFileIO(SerializableSupplier) 构造器被删（#17704），调用点要换成接收 Hadoop Configuration 的那条构造路径。 这里必须写清一个局限：正式标签自带的说明只列出 PR 标题，没有逐条给出「旧类名换成哪个新类名」的对照表，上面第 3、8、14 条的替代写法需要在编译报错与 javadoc 上再核一遍，不要直接把本文的推断当成官方迁移指南。 再来看看新增的部分，其中三条对交付流程是立刻可用的。 第一条是 REST 规范新增「注销表」端点，PR 编号 #16400。改动前一个表一旦从目录里被误删，元数据指针就断了，恢复要靠手工重建；改动后 REST 目录多了一个只注销目录登记、不动底层数据的动作，这给「前置部署」Forward Deployed Engineer（FDE）在客户现场做误删恢复留了一条正式路径。同一批 spec 改动还包括 OpenAPI 里新增函数 list 与 load 端点（#15180），以及新增 CatalogObjectIdentifier 这个目录对象标识 schema（#16144、#16160）。 第二条是 Spark 侧新增 rest.catalog-purge 属性，PR 编号 #15614，随后在 Spark 4.0 与 4.1 上各自回填了一份（#17185、#17186）。改动前 DROP TABLE PURGE 的物理删除语义由 Spark 会话自己处理；改动后可以把这个动作下推给 REST catalog 执行，对要求所有删除动作都留痕的受监管客户，这一条能把删除收敛到目录侧审计。这一条对「前置部署」Forward Deployed Engineer（FDE）的用处是：把「谁有权物理删数」从每个计算引擎的会话配置收回到目录的权限模型里，审计口径不再随引擎不同而变。 第三条是 ignore_missing_files 选项被加进 migrate 与 snapshot 两个过程，Spark 4.1 的编号是 #16643 与 #16710，Spark 3.5 与 4.0 的编号是 #16684 与 #16754。改动前把外部表迁进 Iceberg 或做快照时，底层只要有一个文件在存储侧已经消失，整个过程就中断；改动后可以显式跳过缺失文件继续执行，代价是这一批数据不会被纳入。这条配置是「前置部署」Forward Deployed Engineer（FDE）接手中途停工的历史数据迁移时最实用的一项。 其余新增能力按模块简要列清，每条都带编号，方便回查。加密读写以 DelegateFileIO 的形式进入 Core（#14876）。几何类型 geometry type 与地理类型 geography 补齐了 WKB 读写：Parquet 侧读写在 #16982、Parquet 逻辑类型映射在 #16765、Avro 侧读写在 #17119、Spark 4.1 的类型映射在 #16851、数据读写在 #17073，几何包围盒指标在 #17161 与 #17509。 变体类型 variant type 这条线也补完了：Flink 侧支持写 shredded variant（#15596），Spark 侧支持写（#14297），Kafka Connect 与通用 Record 写入启用 Parquet variant shredding（#17520），Spark 侧新增对变体列的向量化 Parquet 读取（#16292）。V4 表格式的骨架继续补齐：spec 加入相对路径（#15630）、位置相对化工具（#16174）、V4 清单文件 manifest 读取器（#16958）、V4 里可以用 Parquet 或 Avro 写清单文件（#15634）、删除向量 DeletionVector 加上 key_metadata 字段（#17438）。规范层面新增了「内容统计」content stats（#14234），配套的 Core 求值器在 #17413。 还有两条属于「让故障别再被吞掉」的改动，值得单独记。Kafka Connect 的「提交失败」改动前会被静默吞掉，改动后在 #16237 里改成向上抛出，并在 #16433 里补了一个部分「提交失败」的指标；同一模块还修掉协调器在某些再均衡场景下重复提交上一批文件的问题（#17713）。AWS 模块里 REST 目录的 SigV4 签名改用承担角色 assumed-role 的凭据（#16794），这条解决的是长期凭据在客户账号里的暴露面。对「前置部署」Forward Deployed Engineer（FDE）来说，入湖链路的失败静默是客户最晚发现、代价最高的一类问题，这一条值得优先升。 正确性修复里有几条属于「不升级就会算错」的级别，这里点出来。 Parquet 侧：对带默认值的列做过滤时，initial-default 行会被丢掉（#16692）；变体列大数（精度大于 18）的 shredding 会出错（#17002）；变体字符串指标的上下界没有按 UTF-8 字节序比较（#17397）。ParquetVariantReaders 去掉了对 commons-lang3 的引用（#18208），改动前在 commons-lang3 版本低于 3.13 的环境里读变体列会抛 NoSuchMethodError。Core 侧：ShreddedObject.put 没有清掉先前的删除标记（#17066）。Spark 侧：分布式「扫描计划」下对改名后的列做「时间旅行」过滤会失效（#16523）。这几条都不是新功能，属于升级才能拿到的正确性修复，「前置部署」Forward Deployed Engineer（FDE）在客户现场做数据核对时如果发现对不上的行数，可以先回到这份清单里排查。 作者与投票人自己承认的局限必须写全，这几条决定了 1.12.0 现在的适用边界。 第一条是 Spark 4.2 故意不发布。gradle.properties 里 defaultSparkVersions 已经写成 4.2，但下载页没有对应的运行时 JAR。投票线程里贡献者明确说明「我们故意不发布 4.2」，理由是 Spark 侧的 API 还在演进，现在发出去会把兼容性风险压到下游。不要在客户现场自行假设 4.2 可用。 第二条是「分区统计」partition statistics 新版扫描接口依赖基于 Hadoop 的 Parquet 客户端。这条是 RC0 投票阶段由验证者提出的保留意见，含义是习惯把 Hadoop 依赖从镜像里剔掉的团队，这次迁移路径不成立。原文没有给出不依赖 Hadoop 的替代实现。 第三条是这次发布的候选版本被否过两轮：RC0 与 RC1 的投票都因为 LICENSE 缺项被投了反对票，具体是 gcp-bundle 里打包进去的 Caffeine 没有对应 LICENSE 条目，以及文档站资产里的 Bootstrap 样式表与 Lottie 脚本缺少许可声明。这些问题在 RC2 修掉了，但它说明 bundle 的许可证检查流程刚刚被补齐，1.12.x 早期的小版本仍有可能出现类似缺口。 第四条是 V4 表格式仍未成为默认。1.12.0 里 V4 相关改动是读取器、构造器与相对路径工具这类骨架工作，规格本身还在演进。所以升级本身不会自动把表升到 V4；反过来，如果手工把 format-version 改成 4，就等于把回滚路径砍断了。 第五条是官方整理版发布说明尚未上线。截至本次发布时，项目官网的发布页最新一章仍是 1.11.0，1.12.0 只有正式标签自带的逐条 PR 清单可用。这意味着本文的模块归类与影响面判断是按 PR 标题做的，没有官方二级分类可交叉核对，「前置部署」Forward Deployed Engineer（FDE）如果要做正式升级评审，应等整理版发布说明补齐后再复核一次。 该行动的是三类人：仍把 Iceberg 跑在 Spark 3.4 上的数据平台团队；直接编译 iceberg-core、iceberg-data、iceberg-aws 或 Kafka Connect 且调用了上面 14 条里任何一个符号的自研代码团队；以及用 Kafka Connect 做入湖、却没有监控提交失败的生产团队。这三类人现在就能做，不必等 1.12.0 进客户生产。 第一步是在 JDK 17 或 21 下对现有代码做一次全量编译，把 14 条删除命中点全部暴露出来，顺序是先改 spark 与 flink 子模块、再改公共模块。第二步按对照关系替换：DataReader 换成 PlannedDataReader；SparkFilters 换成 SparkV2Filters；HadoopFileIO(SerializableSupplier) 换成接收 Configuration 的构造路径；GenericAppenderFactory 与 BaseFileWriterFactory 换成对应的 FileWriterFactory 实现；Flink 的 RewriteDataFiles.Builder.filter(Expression) 改成不带 Expression 的调用方式。这一步做完再动配置，「前置部署」Forward Deployed Engineer（FDE）能省掉一半以上的现场返工。 第三步挑运行时 JAR，文件名可以直接照抄：Spark 3.5 用 iceberg-spark-runtime-3.5_2.12-1.12.0.jar 或 iceberg-spark-runtime-3.5_2.13-1.12.0.jar，Spark 4.0 用 iceberg-spark-runtime-4.0_2.13-1.12.0.jar，Spark 4.1 用 iceberg-spark-runtime-4.1_2.13-1.12.0.jar，Flink 用 iceberg-flink-runtime-2.1-1.12.0.jar 或 iceberg-flink-runtime-1.20-1.12.0.jar，对象存储侧配 iceberg-aws-bundle-1.12.0.jar。JAR 名字里的引擎版本与 Scala 版本两位都不能错，这是升级里最常见的失败点。 第四步是存量表迁移。在 Spark 里跑 migrate 与 snapshot 过程时加上 ignore_missing_files，先在一个非生产库上跑一遍，确认跳过的文件数量符合预期再放到生产。第五步是目录侧，如果客户用的是 REST catalog 且要求删除动作可审计，把 rest.catalog-purge 打开，让 DROP TABLE PURGE 下推到目录执行。第六步是流式入湖侧，升级 Kafka Connect 后接上部分提交失败的新指标并设警报，在此之前这类失败是不可见的。 适用条件是：表仍是 format-version 2 或 3、引擎至少是 Spark 3.5 或 Flink 1.20、构建与运行环境都落在 JDK 17 或 21。不满足其中任何一条，升级都不会成功，硬上只会浪费时间。 回滚与退出方式是：把运行时 JAR 换回 1.11.0 的对应文件即可，表数据与元数据不需要动。这条成立的前提是没有使用 1.12.0 才引入的能力、也没有把表升到 V4；一旦启用 V4，1.11.0 侧无法读取，回滚就没有退路。所以升级前的第一件事是备份表目录下的元数据文件与 metadata.json，并在客户现场把「回滚只换 JAR、不动表」写成验收条款，这是「前置部署」Forward Deployed Engineer（FDE）在交付评审里最容易争取到的一条安全边界。 原始来源： - https://github.com/apache/iceberg/releases/tag/apache-iceberg-1.12.0 - https://github.com/apache/iceberg/blob/apache-iceberg-1.12.0/gradle.properties - https://github.com/apache/iceberg/blob/apache-iceberg-1.12.0/build.gradle - https://iceberg.apache.org/releases/ - https://mail-archive.com/dev@iceberg.apache.org/msg15290.html - https://www.mail-archive.com/dev@iceberg.apache.org/msg15336.html - https://repo1.maven.org/maven2/org/apache/iceberg/iceberg-core/1.12.0/