使用 RisingWave 读写 Apache Iceberg 表:Sink 与 Source 连接器实战指南
使用 RisingWave 读写 Apache Iceberg 表:Sink 与 Source 连接器实战指南
Apache Iceberg 作为开放的表格式,需要各类计算引擎围绕它构建完整的流批一体读写链路。RisingWave 是一个 Postgres 兼容的流式 SQL 数据库,它通过内置的 Iceberg source 与 sink 连接器,支持对 Iceberg 表进行批量读取与流式写入,从而把实时流处理与湖上历史数据无缝衔接。本文以 site/docs/integrations/risingwave.md 为核心,结合仓库内 Iceberg 规范与配置文档,带你完整掌握用 RisingWave 创建 Iceberg sink(写入)与 source(读取)的 SQL 实战方法,以及其中涉及的 Catalog、仓库位置与参数约束。
RisingWave 与 Iceberg 的集成能力概览
RisingWave 是一款面向实时事件流数据处理、分析与管理的 Postgres 兼容 SQL 数据库,能够持续摄入并分析实时数据流,将流数据与历史表进行连续 Join,并对外提供新鲜的、一致性的查询结果。在与 Apache Iceberg 的集成上,RisingWave 通过其内置的 source 与 sink 连接器,实现了两类核心能力:
- 批量读取(Batch Read):通过 source 连接器,将 Iceberg 表作为可查询的数据源接入 RisingWave,支持实时分析场景下对湖表数据的即时查询;
- 流式写入(Streaming Write):通过 sink 连接器,把 RisingWave 中表或物化视图的结果持续写入 Iceberg 表,形成"实时入库、湖上沉淀"的典型链路。
仓库的 集成目录 与 供应商列表 均将 RisingWave 列为 Iceberg 生态的重要流式计算接入方。官方对 RisingWave 的定位是云原生流式数据库,可用于来自消息队列、数据库(通过 Change Data Capture)、数据湖和文件等来源的数据,并对 Iceberg 表实施高效的文件合并等维护操作。
表格式与仓库位置的硬性约束
在开始使用前,需要明确 RisingWave 接入 Iceberg 时当前版本的两项关键限制:
-
表格式(Table Format):仅支持 Iceberg V2 表格式。V2 是 Iceberg 规范中引入行级更新与删除能力的版本。仓库中的 格式规范 明确指出,Version 2 为分析型表的不可变文件增加了行级更新和删除能力,具体通过两类删除文件实现:
- 位置删除(Position deletes):按数据文件路径加行号标记被删除的行,编码在位置删除文件中;
- 等式删除(Equality deletes):按一个或多个列值(如
id = 5)标记被删除的行,编码在等式删除文件中。
这也意味着,如果目标 Iceberg 表是 V1 格式(不支持行级删除),则无法满足 RisingWave 基于主键的 upsert 写入需求。关于格式版本,仓库的 配置文档 显示
format-version的默认值自 Iceberg 1.4.0 起即为2,因此新建表默认即可满足该约束。 -
仓库位置(Warehouse Location):仅支持 S3 兼容对象存储 作为 Iceberg 数据仓库的存储位置,例如 MinIO、Ceph RGW、SeaweedFS 等 S3 兼容服务,以及各云厂商的 S3 协议对象存储。在连接参数中,仓库路径使用
s3a://前缀的 Hadoop S3A 协议表达,例如s3a://hummock001/demo。
支持的 Catalog 类型
RisingWave 的 Iceberg 连接器支持以下五种 Catalog,覆盖了从独立部署到云托管的主流场景:
| Catalog 类型 | 说明 |
|---|---|
rest |
通过 Iceberg REST Catalog 协议访问元数据,适合与各类 REST Catalog 服务对接 |
jdbc / sql |
通过 JDBC 驱动访问基于关系型数据库(如 PostgreSQL)存储元数据的 Catalog |
glue |
AWS Glue Catalog,适用于 AWS 生态 |
storage |
基于对象存储目录结构(Hadoop Catalog 风格)直接管理元数据 |
hive |
Hive Metastore Catalog,适用于已有 Hive 元数据体系的场景 |
在下面的两个实战示例中,均使用 catalog.type = 'storage',即直接以对象存储上的目录布局来组织和发现表元数据,无需额外部署元数据服务,是最便于本地验证与入门的方式。
实战一:通过 Sink 将数据写入 Iceberg 表
RisingWave 中向 Iceberg 表写入数据的方式是创建一个 sink。下面的示例将已有表或物化视图 t1 中的数据写入 Iceberg 表 t1(示例中源表写为 t1,目标表名为 t1,原文档以此示意"从现有表或物化视图 rw_data 写入 Iceberg 表 t1"的形态):
CREATE SINK sink_to_iceberg FROM t1 WITH (
connector = 'iceberg',
type = 'upsert',
primary_key = 'id',
database.name = 'demo_db',
table.name = 't1',
catalog.name = 'demo',
catalog.type = 'storage',
warehouse.path = 's3a://hummock001/demo',
s3.endpoint = 'http://127.0.0.1:9301',
s3.region = 'us-east-1',
s3.access.key = 'hummockadmin',
s3.secret.key = 'hummockadmin'
);
Sink 参数逐项说明
| 参数 | 取值示例 | 作用 |
|---|---|---|
connector |
'iceberg' |
声明使用 Iceberg 连接器 |
type |
'upsert' |
写入类型;结合 primary_key 实现按主键的行级 upsert(依赖 Iceberg V2 的行级删除能力) |
primary_key |
'id' |
用于 upsert 判断的主键列 |
database.name |
'demo_db' |
目标 Iceberg 表的数据库(命名空间)名 |
table.name |
't1' |
目标 Iceberg 表名 |
catalog.name |
'demo' |
Catalog 名称(自定义逻辑名) |
catalog.type |
'storage' |
Catalog 类型,可取 rest、jdbc/sql、glue、storage、hive |
warehouse.path |
's3a://hummock001/demo' |
Iceberg 仓库根路径,使用 S3A 协议表达 |
s3.endpoint |
'http://127.0.0.1:9301' |
S3 兼容存储的服务端点 |
s3.region |
'us-east-1' |
S3 区域 |
s3.access.key |
'hummockadmin' |
S3 访问密钥 Access Key |
s3.secret.key |
'hummockadmin' |
S3 访问密钥 Secret Key |
自动建表:从 RisingWave 2.1 起,可以在 sink 配置中加入 create_table_if_not_exists 参数,当目标 Iceberg 表不存在时自动创建,省去先建表的步骤:
CREATE SINK sink_to_iceberg FROM t1 WITH (
connector = 'iceberg',
type = 'upsert',
primary_key = 'id',
create_table_if_not_exists = 'true',
database.name = 'demo_db',
table.name = 't1',
catalog.name = 'demo',
catalog.type = 'storage',
warehouse.path = 's3a://hummock001/demo',
s3.endpoint = 'http://127.0.0.1:9301',
s3.region = 'us-east-1',
s3.access.key = 'hummockadmin',
s3.secret.key = 'hummockadmin'
);
底层原理佐证:upsert 写入之所以必须落在 V2 表格式上,根源在于 Iceberg 的不可变文件模型——数据文件一经写入不再修改,行级更新只能通过追加删除文件(position deletes / equality deletes)来表达,这正是 格式规范 中 V2 引入的两类删除编码。仓库中 Flink 侧的写入实践也遵循同样的约定,例如 Flink DDL 示例 在创建支持 upsert 的表时显式声明 'format-version'='2',与 RisingWave 的 V2 约束互为印证。
实战二:通过 Source 从 Iceberg 表读取数据
从 Iceberg 表读取数据的方式是创建一个 source。下面的示例从 Iceberg 表 t1 读取数据:
CREATE SOURCE iceberg_t1_source WITH (
connector = 'iceberg',
s3.endpoint = 'http://127.0.0.1:9301',
s3.region = 'us-east-1',
s3.access.key = 'hummockadmin',
s3.secret.key = 'hummockadmin',
s3.path.style.access = 'true',
catalog.type = 'storage',
warehouse.path = 's3a://hummock001/demo',
database.name = 'demo_db',
table.name = 't1'
);
Source 参数要点
相比 sink 配置,source 的关键差异在于:
- 新增
s3.path.style.access = 'true':启用 S3 的路径风格(path-style)访问方式。对于 MinIO、SeaweedFS 等自建 S3 兼容服务,路径风格访问是必须开启的选项,否则默认的虚拟主机风格(virtual-hosted-style)解析会导致访问失败; - 无需
type/primary_key:读取侧不需要 upsert 语义,因此不必声明写入类型与主键; - 无需
catalog.name:source 侧通过catalog.type、warehouse.path、database.name、table.name即可定位目标表。
source 创建完成后,即可用标准 SQL 查询 Iceberg 表中的数据:
SELECT * FROM iceberg_t1_source;
参数取值与组合建议
结合仓库内 Iceberg 的配置约定,补充几点在真实环境中的参数组合建议:
s3.endpoint与s3.path.style.access必须搭配使用:本地/私有 S3 兼容存储(如示例中的127.0.0.1:9301)几乎都需要开启 path-style;接入 AWS S3 官方服务时,endpoint 使用区域默认端点,通常无需开启;warehouse.path的s3a://前缀:对应 Hadoop S3A 文件系统协议,仓库路径指向 Iceberg 元数据与数据文件的根目录,需保证 RisingWave 运行环境对该桶具备读写权限;- Catalog 选择与元数据服务强相关:
storage类型无独立元数据服务、自包含于对象存储目录,适合快速验证;生产环境若有现成的 Hive Metastore、REST Catalog 或 AWS Glue,应分别选择hive、rest、glue,并补充对应的连接参数(如 REST 端点、JDBC URL 等,具体以 RisingWave 官方 Iceberg catalog 文档为准); - 表格式一致性:写入侧要求目标表为 V2 格式;若目标表由其他引擎创建,请确认其
format-version为2。仓库的 配置文档 显示 Iceberg 1.4.0 之后新表默认即 V2,一般无需额外处理。
小结
RisingWave 通过内置的 Iceberg source 与 sink 连接器,为流批一体的数据链路提供了便捷的 SQL 入口:一方面用 CREATE SINK 把实时计算结果以 upsert 语义持续写入 Iceberg V2 表,另一方面用 CREATE SOURCE 把湖上历史表直接接入流式查询。使用时需牢牢把握两个前提——Iceberg V2 表格式与 S3 兼容对象存储仓库位置,并根据目标元数据服务选择 rest、jdbc/sql、glue、storage、hive 五种 Catalog 之一。结合本文的完整参数示例与仓库规范佐证,你可以在本地 S3 兼容存储上快速搭建起 RisingWave ↔ Iceberg 的读写验证环境。