Apache Iceberg Flink 连接器指南:通过 `'connector'='iceberg'` 表属性直接映射底层 Iceberg 表
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)中,解析顺序为:
- 取出
catalog-name,若为空直接抛Preconditions.checkNotNull异常——这是文档标注"必填"的代码级保证; catalogDatabase = flinkConf.getString(CATALOG_DATABASE, databaseName)——表属性优先,否则取当前 Flink 数据库名;catalogTable = flinkConf.getString(CATALOG_TABLE, tableName)——表属性优先,否则取 Flink 建表语句中的表名;- 调用
FlinkCatalogFactory.createCatalog(catalogName, tableProps, hadoopConf)按表属性构造出 FlinkCatalog; - 最后通过
TableLoader.fromCatalog(flinkCatalog.getCatalogLoader(), TableIdentifier.of(catalogDatabase, catalogTable))封装成可序列化的加载器,供 Source/Sink 在集群侧获取 IcebergTable对象。
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 的逻辑是:
- 检查
flinkCatalog.tableExists(objectPath),其中objectPath = new ObjectPath(catalogDatabase, catalogTable); - 若不存在,调用
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 配置。