Apache Iceberg Flink 连接器指南:通过 `'connector'='iceberg'` 表属性直接映射底层 Iceberg 表

原创2026-10-11 12:20:111,377 阅读
文章标签:大数据数据湖OLAP数据存储

Apache Iceberg Flink 连接器指南:通过 'connector'='iceberg' 表属性直接映射底层 Iceberg 表

本文聚焦 Apache Iceberg 官方 Flink 连接器提供的一种轻量接入方式:在不显式创建 Flink Catalog 的前提下,直接在 Flink SQL 中用 CREATE TABLE ... WITH ('connector'='iceberg', ...) 把一张 Flink 表映射到由 Hive、Hadoop 或自定义 Catalog 管理的 Iceberg 表。读完本文,你将掌握 connector、catalog-name、catalog-type、catalog-impl、catalog-database、catalog-table 等表属性的完整语义与默认值,理解连接器在底层"自动建库建表"的实现原理,并能参照完整示例完成建表、写入与查询。

连接器表属性:不建 Catalog 也能使用 Iceberg

Apache Flink 支持在 Flink SQL 中不显式创建 Iceberg Catalog,直接通过指定表选项 'connector'='iceberg' 来创建 Iceberg 表,用法与 Flink 官方 Connector Table 的接入方式一致。其语义要点是:

  • 语句 CREATE TABLE test (..) WITH ('connector'='iceberg', ...) 会在当前 Flink Catalog(默认使用 GenericInMemoryCatalog)中创建一张 Flink 表;
  • 这张 Flink 表并不是由当前 Flink Catalog 直接维护的 Iceberg 表,而是映射到底层 Iceberg 表之上的"代理"——真正的表数据与元数据仍由你指定的 Iceberg Catalog 管理。

因此,连接器只需要几张关键表属性即可完成"定位底层表"的任务。官方文档给出的核心属性如下:

表属性 说明 默认值 / 约束
connector 连接器标识,取常量 iceberg 必填
catalog-name 用户指定的 Catalog 名称 必填,连接器没有默认值
catalog-type 内置 Catalog 类型:hive 或 hadoop;使用 catalog-impl 自定义实现时可不设置 默认 hive
catalog-impl 自定义 Catalog 实现的完全限定类名 当 catalog-type 未设置时必须指定;参见 添加 Catalog 的更多细节
catalog-database 底层 Catalog 中的 Iceberg 数据库名 默认使用当前 Flink 数据库名
catalog-table 底层 Catalog 中的 Iceberg 表名 默认使用 Flink CREATE TABLE 语句中的表名

源码视角:这些表属性如何被解析与消费

这些属性并不是文档层面的"约定",而是由连接器的动态表工厂严格解析的。在 FlinkDynamicTableFactory.java 中:

  • 工厂标识符 FACTORY_IDENTIFIER = "iceberg",这正是 'connector'='iceberg' 能被识别的入口(L47);
  • catalog-name 被定义为 ConfigOptions.key("catalog-name").noDefaultValue(),即无默认值、强制必填(L49-L53);
  • catalog-database 的默认值直接取常量 FlinkCatalogFactory.DEFAULT_DATABASE_NAME(值为 "default")(L61-L65);
  • catalog-table 同样无默认值,运行时回退到 Flink 表名(L67-L71)。

在 createTableLoader(ResolvedCatalogTable, Map, String databaseName, String tableName) 方法(L148-L202)中,解析顺序为:

  1. 取出 catalog-name,若为空直接抛 Preconditions.checkNotNull 异常——这是文档标注"必填"的代码级保证;
  2. catalogDatabase = flinkConf.getString(CATALOG_DATABASE, databaseName)——表属性优先,否则取当前 Flink 数据库名;
  3. catalogTable = flinkConf.getString(CATALOG_TABLE, tableName)——表属性优先,否则取 Flink 建表语句中的表名;
  4. 调用 FlinkCatalogFactory.createCatalog(catalogName, tableProps, hadoopConf) 按表属性构造出 FlinkCatalog;
  5. 最后通过 TableLoader.fromCatalog(flinkCatalog.getCatalogLoader(), TableIdentifier.of(catalogDatabase, catalogTable)) 封装成可序列化的加载器,供 Source/Sink 在集群侧获取 Iceberg Table 对象。

TableLoader 接口(见 TableLoader.java)的设计原因是:Flink 需要在集群侧(例如切分 Split 时)拿到 Iceberg Table,而不仅仅是客户端侧,因此必须有可序列化、可克隆的加载器。内置实现包括 HadoopTableLoader(按 location 加载)与 CatalogTableLoader(按 CatalogLoader + TableIdentifier 加载)。

场景一:表由 Hive Catalog 管理

执行下述 SQL 前,请先按照 Flink 快速上手文档 正确配置 Flink SQL Client(含 Hive 依赖,详见后文"前置准备")。

下面的语句会在当前 Flink Catalog 中创建一张 Flink 表,映射到 Iceberg Catalog 中由 Hive 管理的 Iceberg 表 default_database.flink_table:

CREATE TABLE flink_table (
    id   BIGINT,
    data STRING
) WITH (
    'connector'='iceberg',
    'catalog-name'='hive_prod',
    'uri'='thrift://localhost:9083',
    'warehouse'='hdfs://nn:8020/path/to/warehouse'
);

其中 uri 是 Hive Metastore 的 Thrift 地址(必填),warehouse 指定仓库路径;由于未设置 catalog-type,连接器按默认值 hive 解析——这一点在 FlinkCatalogFactory.java 中由 properties.getOrDefault(ICEBERG_CATALOG_TYPE, ICEBERG_CATALOG_TYPE_HIVE) 保证。

映射到 Hive 中不同的库表

如果希望 Flink 表映射到 Hive Catalog 中另一张不同的 Iceberg 表(例如 Hive 中的 hive_db.hive_iceberg_table),则通过 catalog-database 与 catalog-table 显式指定目标:

CREATE TABLE flink_table (
    id   BIGINT,
    data STRING
) WITH (
    'connector'='iceberg',
    'catalog-name'='hive_prod',
    'catalog-database'='hive_db',
    'catalog-table'='hive_iceberg_table',
    'uri'='thrift://localhost:9083',
    'warehouse'='hdfs://nn:8020/path/to/warehouse'
);

提示:底层 Catalog 中的数据库(上例中的 hive_db)若不存在,在向该 Flink 表写入记录时会自动创建。这一行为对应源码 L172-L184:连接器先检查 flinkCatalog.databaseExists(catalogDatabase),不存在则以 ignoreIfExists = true 调用 createDatabase 自动创建。

场景二:表由 Hadoop Catalog 管理

下面的语句在当前 Flink Catalog 中创建 Flink 表,映射到 Hadoop Catalog 管理的 Iceberg 表 default_database.flink_table:

CREATE TABLE flink_table (
    id   BIGINT,
    data STRING
) WITH (
    'connector'='iceberg',
    'catalog-name'='hadoop_prod',
    'catalog-type'='hadoop',
    'warehouse'='hdfs://nn:8020/path/to/warehouse'
);

与 Hive 场景的关键差异是:必须显式声明 'catalog-type'='hadoop'(否则按默认值走 Hive 分支),且不需要 uri,但 warehouse 是 Hadoop Catalog 定位表文件的必需配置。源码中 catalog-type 分支支持 hive、hadoop、rest 三类内置类型(见 FlinkCatalogFactory.java),遇到未知类型会抛出 UnsupportedOperationException。

场景三:表由自定义 Catalog 管理

如果底层是自行实现的 Catalog(例如 com.my.custom.CatalogImpl),则通过 catalog-impl 指定其完全限定类名,并不设置 catalog-type:

CREATE TABLE flink_table (
    id   BIGINT,
    data STRING
) WITH (
    'connector'='iceberg',
    'catalog-name'='custom_prod',
    'catalog-impl'='com.my.custom.CatalogImpl',
     -- 更多自定义 Catalog 所需的表属性
    'my-additional-catalog-config'='my-value',
     ...
);

从源码看,createCatalogLoader 首先检查 properties.get(CatalogProperties.CATALOG_IMPL)(L89-L99):一旦设置了 catalog-impl,若同时设置 catalog-type 会直接抛出 IllegalArgumentException("Cannot create catalog, both catalog-type and catalog-impl are set")。因此自定义 Catalog 场景下 catalog-type 必须留空,其余配置项原样传给 CatalogLoader.custom(...) 供自定义实现消费。各内置/自定义实现的列表可查看本仓库 Integrations 标签页下的对应集成文档。

底层库表的自动创建机制

除了上文提到的"写入时自动创建数据库",连接器在建表解析阶段还会自动创建底层 Iceberg 表。源码 L186-L198 的逻辑是:

  1. 检查 flinkCatalog.tableExists(objectPath),其中 objectPath = new ObjectPath(catalogDatabase, catalogTable);
  2. 若不存在,调用 flinkCatalog.createIcebergTable(objectPath, resolvedCatalogTable, true),将 Flink 表的结构(TableSchemaUtils.getPhysicalSchema)转换为 Iceberg 表结构并创建。

这意味着即使 catalog-database / catalog-table 指向尚不存在的库表,连接器也能在首次使用时完成"映射 + 自动建表",无需预先把表建好。这一点在测试 TestIcebergConnector.java 中有系统覆盖:参数化组合包含 hadoop/hive 两种 Catalog、catalog-table 指向 not_existing_table、catalog-database 指向 not_existing_db 等场景,均验证了创建后 databaseExists 与 tableExists 为真,并完成 INSERT 后查询数据的一致性校验(L66-L167)。

该机制同样适用于匿名表(Anonymous Table)场景:测试 TestFlinkAnonymousTable.java 展示了不写 CREATE TABLE,直接用 TableDescriptor.forConnector("iceberg") 配合 catalog-name / catalog-type / catalog-database / catalog-table / warehouse 构造目标表,然后 table.insertInto(descriptor) 完成写入,最终在 warehouse/test_db/test 路径下确认表真实落盘。

完整示例:建表、写入与查询

以 Hive Catalog 为例,一条完整的连接器使用链路如下:

CREATE TABLE flink_table (
    id   BIGINT,
    data STRING
) WITH (
    'connector'='iceberg',
    'catalog-name'='hive_prod',
    'uri'='thrift://localhost:9083',
    'warehouse'='file:///path/to/warehouse'
);

INSERT INTO flink_table VALUES (1, 'AAA'), (2, 'BBB'), (3, 'CCC');

SET execution.result-mode=tableau;
SELECT * FROM flink_table;

+----+------+
| id | data |
+----+------+
|  1 |  AAA |
|  2 |  BBB |
|  3 |  CCC |
+----+------+
3 rows in set

写入走的是 INSERT INTO(流式、批式任务均支持),IcebergTableSink 会将 RowData 以 Iceberg 的 Append 语义落盘;查询则由 IcebergTableSource 读取底层表并返回结果。该完整流程与测试 TestIcebergConnector.testCreateConnectorTable()(L221-L240)中"建表 → INSERT 三行 → 查询断言 → 删表重建后再次查询"的步骤一一对应。

前置准备:如何加载连接器

使用连接器表属性前,需要把打包好的 iceberg-flink-runtime 放到 Flink 环境中,详见 Flink 快速上手文档:

  • 仓库按 Flink 主版本维护多个模块:flink/v1.18、flink/v1.19、flink/v1.20(各版本依赖见 gradle/libs.versions.toml,分别对应 Flink 1.18.1、1.19.0、1.20.0);构建项目后会在 flink-runtime/build/libs 下生成捆绑 jar;
  • Iceberg 编译 iceberg-flink-runtime 时使用 Scala 2.12,建议搭配捆绑 Scala 2.12 的 Flink 发行版使用;
  • 使用 Hive Catalog 时,还需加载 Hive 相关 jar(Flink 官方提供了 flink-sql-connector-hive 捆绑包),并保证 HADOOP_CLASSPATH 已导出;
  • Flink 1.16 及以上版本存在通过 -j 选项加载外部 jar 的回归问题(见 FLINK-30035),需把 iceberg-flink-runtime-<版本>.jar 放入 flink/lib 目录后再启动 SQL Client。

边界与限制

  • 不能在 Iceberg Catalog 中使用连接器表属性:测试 TestIcebergConnector.testConnectorTableInIcebergCatalog()(L259-L294)验证了在已创建 Iceberg Catalog 下再使用 'connector'='iceberg' 会抛出 IllegalArgumentException,提示应"在非 Iceberg Catalog 中创建带 connector 属性的表,或在 Iceberg Catalog 中创建不带 connector 相关属性的表"。
  • catalog-type 与 catalog-impl 互斥:二者同时设置会直接报错,自定义实现必须放弃 catalog-type。
  • catalog-name 必填:缺少该属性时,FlinkDynamicTableFactory 的 requiredOptions() 校验会直接失败。
  • 更丰富的读写能力(流式读、增量快照读取、INSERT OVERWRITE、DataStream API 读写、类型转换映射表等)仍建议优先使用显式创建的 Iceberg Catalog,参见 Flink 文档、Flink DDL、Flink 查询、Flink 写入 与 Flink 配置。
登录后查看全文
iceberg