企业官网建设流程全解析

• 数据湖
• 大数据
• 数据存储

Apache Iceberg 社区于 2026 年 5 月 19 日正式发布 1.11.0 版本。本文基于本仓库发布的官方发布说明（site/docs/blog/posts/2026-05-19-iceberg-1.11.0-release.md），逐项拆解该版本在 REST Catalog 协议、OpenAPI 规范、Table Format V4 地基、加密、性能与各引擎集成方面的核心变化，并结合仓库源码验证关键实现，帮助读者完整掌握 1.11.0 的能力边界、升级影响与落地方式。

版本概况与社区规模

Apache Iceberg 1.11.0 是社区自 REST 目录协议引入以来推进最显著的版本之一，凝聚了超过1,000 次提交、200+ 贡献者的成果。仓库的 site/docs/releases.md 同样记录了本次发布：1.11.0 于 2026 年 5 月 19 日发布，包含大量缺陷修复与新特性，完整变更清单可在发布说明中查看。

从版本定位看，1.11.0 是一份"协议级 + 地基级"的发布：一方面把 REST Catalog 从"可用"推向"更完整"，另一方面为 Table Format V4 的演进提前铺设抽象层，同时在各主流引擎（Spark、Flink、Hive、Kafka Connect）与云厂商（AWS、Azure、GCP、Aliyun）上落地了大量实用能力。

REST Catalog：协议走向完整

远程扫描规划（Remote Scan Planning）

1.11.0 最显著的变化是远程扫描规划。此前，每个客户端都需要自行拉取 manifest list 与 manifest 来确定要读取的文件；而远程扫描规划允许目录服务端直接规划表扫描，并把文件扫描任务（file scan tasks）流式返回给客户端。客户端只拿到与查询相关的扫描任务，从而：

• 显著降低驱动端（driver）内存压力；
• 让服务端优化对查询引擎透明生效。

本次发布将远程扫描规划进一步扩展覆盖两类场景：

• 增量扫描（incremental scans）：面向 Structured Streaming 工作负载（#14661）；
• 元数据表（metadata tables）：如history、snapshots等（#14881）。

同时提供了**按表覆盖（per-table override）**机制（#15572）中可以看到PlanTableScanResponse、FetchPlanningResultResponse等响应体结构，它们是远程扫描规划在协议层的落点。

基于 ETag 的新鲜度感知表加载

Freshness-aware table loading 为表元数据引入了基于 ETag 的缓存。当客户端加载一张已持有元数据的表时，服务端可以直接返回304 Not Modified，而无需重发完整元数据载荷。这对紧密的读循环（tight read loops）和交互式工作负载收益明显——减少了大量不必要的往返请求。

与之配套，OpenAPI 规范为CommitTableResponse增加了 ETag 支持（#14760），使客户端能够检测"加载表之后、提交之前"是否有并发写改变了表，与LoadTableResult上已有的 ETag 形成互补。

幂等键（Idempotency Key）

Idempotency key support 为变更类目录操作引入了标准的Idempotency-Key请求头。重试的写操作——提交（commit）、建表（create）、删表（drop）——现在保证不会执行两次，从而避免网络超时导致的重复快照与状态损坏。

仓库核心实现（core/src/main/java/org/apache/iceberg/rest/RESTUtil.java）中定义了IDEMPOTENCY_KEY_HEADER = "Idempotency-Key"，并提供基于 UUIDv7 的键生成逻辑：UUIDUtil.generateUuidV7().toString()，确保每次重试使用稳定且唯一的幂等键，服务端可以据此去重。

Register View：补齐视图生命周期

Register View 让视图像表一样可以从元数据位置注册（#14870）。此前视图生命周期在 REST 目录中是不完整的——表可以从其 metadata location 注册，视图却不行。现在视图也可以通过 REST API 注册，支持跨目录迁移，以及重新挂接"孤儿"视图元数据。

配套地，OpenAPI 规范新增了/register-viewREST 端点（#14869），将视图注册作为一项可独立授权的目录能力。服务端可以把它作为可选扩展实现，不会影响现有客户端。

自定义表与视图操作

Custom Table and View Operations 允许用户向 REST 目录注入自定义的TableOperations与ViewOperations，在不 fork 目录实现的前提下扩展或覆盖默认行为。这为云服务商与内部平台团队提供了"钩子"机制，可以插入自定义逻辑（如审计、缓存、权限校验）。

协议级新语义（小结）

除上述主能力外，REST 协议还新增了若干协议级语义：

• added-rows字段恢复：快照元数据中恢复added-rows（#14048），引擎与监控工具无需扫描数据文件即可获得每个快照的行数；
• referenced-by字段：loadTable响应新增referenced-by字段（#13810），列出依赖该表的视图与其他对象，使依赖追踪下沉到协议层；
• scan-planning-mode字段：LoadTableResult中服务端可通告其偏好的扫描规划模式（#14867），客户端无需探测即可决定采用远程还是本地规划；
• 404 语义：/v1/config在请求的 warehouse 不存在时返回 404（#15746），替代此前含糊的错误响应。

OpenAPI 规范更新

1.11.0 在 OpenAPI 层面收紧客户端与服务端的契约，主要更新包括：

仓库中的 open-api/rest-catalog-open-api.yaml 即为本次协议更新的具体载体，读者可对照该文件查看各端点与字段的完整定义。

Spec 更新：SQL UDF 与地理空间类型

SQL UDF 规范

SQL UDF Specification）。UDF 具备以下特性：

• 版本化：函数可以有多个版本；
• 多 SQL 方言支持：同一函数可适配不同引擎的 SQL 方言；
• 跨引擎可移植：函数管理首次进入目录层，摆脱了"每个引擎各自管理函数"的碎片化现状。

地理空间边界框类型

Geospatial bounding box types 目录即为该能力在 API 层的实现所在。

性能与可靠性

LIMIT 下推

LIMIT pushdown to scan 使得查询包含LIMIT子句时，扫描到足够行即停止，而不再读取所有匹配文件。对探索式查询而言，I/O 量可能下降若干个数量级。

向量化读取覆盖更多 Parquet 编码

向量化读取新增覆盖以下 Parquet 编码，消除逐行回退（row-at-a-time fallback）：

• BYTE_STREAM_SPLIT（#15373）；
• DELTA_LENGTH_BYTE_ARRAY与DELTA_BYTE_ARRAY（#15362）。

这对使用 float/double 列且采用BYTE_STREAM_SPLIT编码的科学计算与机器学习数据集尤为受益。实现位于 parquet/src/main/java/org/apache/iceberg/parquet 模块。

快照过期清理模式

Snapshot expiration cleanup modes 引入新的cleanupModeAPI，让用户对快照过期时的清理范围拥有更细粒度控制——例如可以决定是否删除孤儿数据文件、是否保留特定文件。

唯一表位置（Unique Table Locations）

Unique table locations 通过新的目录属性在表存储路径上追加 UUID，防止DeleteOrphanFiles误删改名表文件的灾难性数据丢失场景，同时支持按表的存储生命周期策略与成本归因。

该属性在源码中定义于 core/src/main/java/org/apache/iceberg/CatalogProperties.java：

/** * Requests that the catalog provide unique locations for new tables. * * <p>Relevant only for catalogs which support unique table locations. */ public static final String UNIQUE_TABLE_LOCATION = "unique-table-location"; public static final boolean UNIQUE_TABLE_LOCATION_DEFAULT = false;

即默认关闭，需要在支持该能力的目录上显式开启：

unique-table-location=true

定时凭据刷新与 GCS 分析加速

• AWS S3FileIO（#15678）与GCS FileIO（#15696）新增定时凭据刷新：在凭据过期前主动轮换，消除长期运行的 Spark/Flink 作业中因初始凭据租约过期而导致的瞬时故障。
• GCSAnalyticsCore 库（#14333）集成进 GCSFileIO，为 Google Cloud Storage 带来分析优化 I/O，提升大规模分析工作负载的读吞吐，与 S3 上的 AWS Analytics Accelerator 集成形成对应。

Format V4 地基

1.11.0 开始为 Table Format V4 铺设基础。

自适应元数据树基础类型

新增的基础类型——TrackedFile、TrackingInfo、ContentInfo、ManifestStats（#15049）——是 V4 自适应元数据树（adaptive metadata tree）的构建块，定义了 Iceberg 在规模化场景下如何追踪文件。相关实现（#15854）、构建器（#16092）与分区支持（#16253）在整个发布周期中迭代添加。

FormatModel 抽象

新的 FormatModel 抽象 用可插拔接口取代硬编码的文件格式处理。Parquet（#15253）、ORC（#15255）、Avro 与 Arrow 各自实现了FormatModel契约，使新增格式或定制读写行为更加简单。

仓库中的核心接口定义在 core/src/main/java/org/apache/iceberg/formats/FormatModel.java：

public interface FormatModel<D, S> { /** The file format which is read/written by the object model. */ FileFormat format(); /** Return the row type class for the object model implementation processed by this factory. */ Class<? extends D> type(); /** Return the schema type class for the object model implementation processed by this factory. */ Class<S> schemaType(); /** Creates a writer builder for data files. */ ModelWriteBuilder<D, S> writeBuilder(EncryptedOutputFile outputFile); /** Creates a file reader builder for the specified input file. */ ReadBuilder<D, S> readBuilder(InputFile inputFile); }

接口的 Javadoc 明确说明：FormatModel充当存储格式（FileFormat）与预期输入/输出数据结构之间的桥接，通过免中间表示的直转优化性能；处理引擎可以定义自己的对象模型并实现该接口，通过 FormatModelRegistry 注册到 Iceberg。各格式的实现包括：

• parquet/src/main/java/org/apache/iceberg/parquet/ParquetFormatModel.java
• orc/src/main/java/org/apache/iceberg/orc/ORCFormatModel.java
• core/src/main/java/org/apache/iceberg/avro/AvroFormatModel.java
• arrow/src/main/java/org/apache/iceberg/arrow/vectorized/ArrowFormatModels.java

同时 Spark、Flink 等引擎侧也有对应模型（如 spark/v4.2/spark/src/main/java/org/apache/iceberg/spark/source/SparkFormatModels.java、flink/v2.3/flink/src/main/java/org/apache/iceberg/flink/data/FlinkFormatModels.java），并配有 data/src/test/java/org/apache/iceberg/data/ReadFormatModelTests.java 等测试用例验证读写闭环。

加密

1.11.0 让表级加密真正对用户可用：

• Hive 表加密激活：Encryption integration and test 通过包含表主密钥 ID 的表属性激活 Hive 表的加密机制；
• Manifest list 加密（#7770）：将加密覆盖扩展到 manifest list 文件，确保快照级元数据与数据文件一同受到保护；
• 自动密钥轮换（#14396）：支持无需人工介入地轮换密钥加密密钥（KEK）；
• 云 KMS 支持（#15272）：通过统一的encryption.kms-type属性覆盖 AWS、Azure、GCP；
• Hive 目录元数据完整性校验（#14685）：加密表的元数据完整性检查。

源码中的属性定义同样位于 core/src/main/java/org/apache/iceberg/CatalogProperties.java：

public static final String ENCRYPTION_KMS_TYPE = "encryption.kms-type"; public static final String ENCRYPTION_KMS_TYPE_AWS = "aws"; public static final String ENCRYPTION_KMS_TYPE_AZURE = "azure"; public static final String ENCRYPTION_KMS_TYPE_GCP = "gcp"; public static final String ENCRYPTION_KMS_IMPL = "encryption.kms-impl"; public static final String ENCRYPTION_KMS_IMPL_AWS = "org.apache.iceberg.aws.AwsKeyManagementClient"; public static final String ENCRYPTION_KMS_IMPL_AZURE = "org.apache.iceberg.azure.keymanagement.AzureKeyManagementClient"; public static final String ENCRYPTION_KMS_IMPL_GCP = "org.apache.iceberg.gcp.GcpKeyManagementClient";

可以看到，三种云厂商的 KMS 客户端实现类均已在仓库中落地（分别位于 aws、azure、gcp 模块），使用时只需配置：

encryption.kms-type=<aws|azure|gcp>

详细用法可参考 docs/docs/encryption.md。

新 API

• Content Stats API（#13933）：引入文件级统计类——min/max 值、null 计数等，为查询规划器提供更丰富的信息，以做出更好的文件跳过（file skipping）与连接排序（join-ordering）决策；
• Partition Stats Scan API（#14640）：以可组合、可过滤的接口取代旧的单次分区统计读取器，与 Iceberg 其余 Scan API 保持一致风格；
• Overwrite-aware 表注册（#15525）与Scan API 中的 FileIO 访问（#15561）补全了本版本其余 API 增补。

引擎更新

Spark

• Spark 4.1 支持（#14155）：
  • MERGE INTO schema 演进：初始支持合并写入期间的 schema 变更（#14970），并可通过表属性控制（#15825）；
  • Shredded Variant 写入（#14297）：读取由行式 Parquet 读取器的ArrayData.getVariant支撑（#14349）；
  • 异步微批规划器（#15299）：Structured Streaming 中异步规划下一个微批，降低调度开销；
  • 自适应 split 大小（#16088）：会话级配置可调 split 大小与并行度。
• 异步微批规划器（#15876）、自适应 split 大小（#16344）与 shredded Variant 写入（#16241）同样在 Spark 4.0 可用。
• Spark 3.4 支持在本版本标记弃用（#14099）。

Flink

• Flink 2.1 支持（#13714），Flink 1.19 被移除。
• 行谱系（Row lineage）：支持读取_row_id与_last_updated_sequence_number（#14148），并且行谱系在RewriteDataFiles中得以保留（#14149），使行身份在压缩后依然存活。
• Flink Dynamic Sink 重大改进：
  • 删除向量（Deletion vector）支持（#14414）：无需重写数据文件即可实现高效行级删除；
  • Variant 类型支持（#15265）：Flink 2.1 中支持半结构化数据摄取与处理；
  • Schema 演进：支持删列（#14728）与大小写不敏感字段匹配（#14729）；
  • SQL 可配置选项：Dynamic Sink 选项可通过 Flink SQL 配置（#15279），本版本又新增更多 SQL 选项（#15780）；
  • 提交后维护（#15566）：可通过 IcebergSink Builder 注册任意维护任务，无需单独管道。
• TableMaintenance 协调器锁（#15151）：防止分布式部署中并发维护操作冲突，并可从 Flink SQL 访问（#15459）。
• 维护能力增强：RewriteDataFiles支持动态过滤器（#15865）用于定向压缩；分支支持（#15672）允许针对特定分支运行维护任务。
• 纳秒时间戳精度（#15475）：匹配 Iceberg 时间戳规范的完整范围，满足 IoT、金融与科学工作负载需求；UUID 类型支持（#16097）加入 Avro 与 Parquet 读写器。

Hive Catalog

• 视图替换现在会同步更新 HMS 中存储的查询（#14831），保持视图定义变更时 Hive Metastore 同步；
• 注册表时检测同名视图是否已存在（#15010），防止意外覆盖；
• 快照过程（snapshot procedure）正确处理含 Variant 列的表（#15964）。

Kafka Connect

• Variant 类型摄取（#15283）：半结构化 JSON 数据可直接摄入 Iceberg 的 Variant 类型；
• 提交时表 UUID 校验（#14979）：提交时验证表身份，防止写入过期或被替换的表；
• SMT offset 追踪修复（#15880）：修复 Single Message Transform 修改记录 topic 时可能导致的重复记录问题。

云集成

AWS

• KMS 端点可配置：通过kms.endpoint属性（#14246）连接自定义或私有 KMS 端点；
• S3 请求分块编码可配置（#15242）：适合需要控制数据流向 S3 方式的工作负载；
• 自定义凭据提供器优先（#15249）：配置自定义凭据提供器时，优先于默认提供器链，明确认证顺序；
• 代理配置（#15506）：HTTP 客户端可通过系统属性与环境变量配置代理；
• 重试策略（#15094）：应用于 Glue 与 DynamoDB 客户端，提升高吞吐目录操作的可靠性。

Azure

• Azure Key Vault 的 KeyManagementClient 实现（#13186）：为 Iceberg 信封加密提供原生 Azure KMS 支持；
• Token 凭据提供器支持（#14136）：可指定自定义 token 凭据提供器类，支持托管身份与服务主体等 Azure 认证流。

GCP

• BigQueryMetastoreCatalog 服务账号模拟（#14447）：基础服务账号可模拟另一个账号访问 BigQuery 元数据；
• 新属性gcp.auth.credentials-key（#14713）：允许直接在目录配置中传入 base64 编码的服务账号密钥；
• BigQueryMetastoreCatalog ETag 冲突检测（#14940）：提交表更新时消除冗余表加载，防止并发写下的更新丢失。

Aliyun

• OSS 的 RRSA 认证（#14443）：为阿里云 OSS 上的 Iceberg 表带来细粒度 IAM 风格访问控制。

仓库实现位于 aliyun/src/main/java/org/apache/iceberg/aliyun/AliyunClientFactories.java：检测到 RRSA 环境变量（RRSA 即 RAM Roles for Service Accounts，允许 pod 通过服务账号角色访问不同云服务）后，基于 RRSA 凭据构建 OSS 客户端，代码如下：

// Check if RRSA environment is available if (rrsaEnabled) { LOG.debug("Detected RRSA environment variables, creating OSS client with RRSA credentials for endpoint: {}", endpoint); // Getting credentials using RRSA return new OSSClientBuilder().build(endpoint, ossCredProvider); }

Breaking Changes

升级 1.11.0 前需要关注以下破坏性变更：

依赖更新

本版本的主要依赖版本变化如下：

新增支持 Spark 4.1（4.1.1）与 Flink 2.1（2.1.0）。

升级与参与

• 升级路径：若当前使用 Spark 3.4，请规划迁移到 Spark 3.5 或 4.x（Spark 3.4 已弃用）；若使用 Flink 1.19，请升级到 Flink 1.20 或 2.x；同时确认运行环境满足 Java 17 最低要求。
• REST 目录用户：1.11.0 引入的远程扫描规划、幂等键与 ETag 能力均需要目录服务端（如支持这些扩展的 REST catalog 实现）配合，客户端可渐进式启用（如通过 per-table override 按表退出远程规划）。
• 进一步阅读：本仓库中可继续阅读 docs/docs/rest-catalog.md、docs/docs/rest-protocol.md 与 docs/docs/encryption.md；完整的协议定义见 open-api/rest-catalog-open-api.yaml；发布历史总览见 site/docs/releases.md。

Apache Iceberg 1.11.0 在协议完备性、格式演进地基与引擎集成三个维度同时取得实质进展。无论是正在搭建 REST 目录服务的平台团队，还是运行 Spark/Flink 大规模作业的数据工程团队，都可以从本版本中获得直接收益——而 Format V4 的早期铺垫，则预示着未来元数据树与文件格式处理将迎来更深层的变化。

• 数据湖
• 大数据
• 数据存储