Iceberg 外部表
概述
ClickZetta Lakehouse 支持通过外部 Catalog 方式读取存储在对象存储上的 Apache Iceberg 格式数据。与 Paimon 外部表不同，Iceberg 需要通过 Catalog Connection 接入，不支持直接指定表目录路径。
已验证版本：Iceberg format v1、v2
已验证云厂商：阿里云 OSS
前提条件
- 已有 Iceberg 格式数据存储在对象存储上，且通过 Iceberg Catalog 服务管理
- Iceberg Catalog 服务可从 Lakehouse 计算节点访问（需公网或内网可达）
- 在 Lakehouse 中已创建存储 Connection（用于读取数据文件）
支持的 Catalog 类型
| Catalog 类型 | 说明 |
|---|
ICEBERG_REST
ICEBERG_REST | Iceberg REST Catalog（推荐，标准化接口） |
HMS
HMS | Hive Metastore（兼容 Hive 管理的 Iceberg 表） |
注意：Iceberg 不支持像 Paimon 那样直接通过
LOCATION 'oss://...'
LOCATION 'oss://...'
指定表目录路径读取，必须通过 Catalog 服务管理表元数据。
第一步：创建存储 Connection
参考 Paimon 文档，创建 OSS / COS / S3 的存储 Connection：
-- 阿里云 OSS
CREATE CONNECTION conn_oss
TYPE OSS
PROPERTIES (
'ACCESS_ID' = '<your-access-key-id>',
'ACCESS_KEY' = '<your-access-key-secret>',
'ENDPOINT' = 'oss-cn-hangzhou-internal.aliyuncs.com'
);
第二步：创建 Catalog Connection
Iceberg REST Catalog
CREATE CATALOG CONNECTION conn_iceberg_rest
TYPE ICEBERG_REST
URI = 'https://<your-iceberg-rest-catalog-host>'
STORAGE_CONNECTION = '<oss_connection_name>';
Iceberg REST Catalog 部署选项：
| 方案 | 说明 |
|---|
| Apache Polaris | 云原生 Iceberg REST Catalog，支持多云存储 |
| Nessie | 开源，支持版本控制 |
| Tabular REST Server | 参考实现（tabulario/iceberg-rest Docker 镜像） |
| 自建 | 任何兼容 Iceberg REST OpenAPI spec 的服务 |
CREATE CATALOG CONNECTION conn_hive
TYPE HMS
HIVE_METASTORE_URIS = 'thrift://<hms-host>:9083'
STORAGE_CONNECTION = '<oss_connection_name>';
第三步：创建外部 Catalog
CREATE EXTERNAL CATALOG <catalog_name> CONNECTION <catalog_connection_name>;
示例：
CREATE EXTERNAL CATALOG iceberg_catalog CONNECTION conn_iceberg_rest;
第四步：查询 Iceberg 数据
通过三段式命名
catalog.schema.table
catalog.schema.table
直接查询，无需额外建表：
-- 查看 catalog 下的所有 schema
SHOW SCHEMAS IN iceberg_catalog;
-- 查看 schema 下的所有表（自动发现 Iceberg 元数据）
SHOW TABLES IN iceberg_catalog.test_db;
-- 查看表结构（自动推断 Iceberg schema）
DESC TABLE iceberg_catalog.test_db.orders;
-- 查询数据
SELECT * FROM iceberg_catalog.test_db.orders LIMIT 10;
-- 带分区过滤
SELECT * FROM iceberg_catalog.test_db.orders WHERE dt = '2024-01-01';
数据类型兼容性
以下类型经过实测验证（Iceberg format v2，阿里云 OSS，含边界值和 NULL 测试）：
| Iceberg 类型 | Lakehouse 推断类型 | 验证状态 | 备注 |
|---|
integer
integer | INT
INT | ✅ 支持 | 含 NOT NULL |
long
long | BIGINT
BIGINT | ✅ 支持 | |
float
float | FLOAT
FLOAT | ✅ 支持 | |
double
double | DOUBLE
DOUBLE | ✅ 支持 | |
boolean
boolean | BOOLEAN
BOOLEAN | ✅ 支持 | 含 NULL |
string
string | STRING
STRING | ✅ 支持 | 含中文、空串、NULL |
date
date | DATE
DATE | ✅ 支持 | 范围 1970-01-01 ~ 2099-12-31 |
timestamp
timestamp | TIMESTAMP_NTZ
TIMESTAMP_NTZ | ✅ 支持 | 无时区，微秒精度 |
decimal(p,s)
decimal(p,s) | DECIMAL(p,s)
DECIMAL(p,s) | ✅ 支持 | 含正/负/零/NULL |
binary
binary | BINARY
BINARY | ✅ 支持 | |
list<T>
list<T> | ARRAY<T>
ARRAY<T> | ✅ 支持 | 含 null 元素 |
map<K,V>
map<K,V> | MAP<K NOT NULL, V>
MAP<K NOT NULL, V> | ✅ 支持 | key 自动推断为 NOT NULL |
struct<...>
struct<...> | STRUCT<...>
STRUCT<...> | ✅ 支持 | 含 null 字段，支持中文值 |
分区表：支持 identity 分区，分区字段自动出现在
DESC TABLE
DESC TABLE
的 Partition Information 中。
验证示例
-- Schema 自动推断（无需手动指定列）
SHOW TABLES IN iceberg_catalog.test_db;
-- 返回：basic_types, complex_types, orders
DESC TABLE iceberg_catalog.test_db.basic_types;
-- 自动推断出：id int not null, c_int int, c_long bigint, c_float float,
-- c_double double, c_boolean boolean, c_string string, c_date date,
-- c_ts timestamp_ntz, c_decimal decimal(18,4), c_binary binary
SELECT * FROM iceberg_catalog.test_db.basic_types ORDER BY id;
SELECT * FROM iceberg_catalog.test_db.complex_types ORDER BY id;
SELECT * FROM iceberg_catalog.test_db.orders WHERE dt = '2024-01-01';
与 Paimon 外部表的区别
| 特性 | Paimon 外部表 | Iceberg 外部 Catalog |
|---|
| 接入方式 | CREATE EXTERNAL TABLE ... USING PAIMON LOCATION ...
CREATE EXTERNAL TABLE ... USING PAIMON LOCATION ... | CREATE EXTERNAL CATALOG ... CONNECTION ...
CREATE EXTERNAL CATALOG ... CONNECTION ... |
| 元数据服务 | 无需额外服务，直接读取 Paimon schema 文件 | 需要 Catalog 服务（HMS / REST） |
| 访问语法 | SELECT * FROM ext_table
SELECT * FROM ext_table | SELECT * FROM catalog.schema.table
SELECT * FROM catalog.schema.table |
| 建表操作 | 需要 CREATE EXTERNAL TABLE
CREATE EXTERNAL TABLE | 无需建表，通过 Catalog 自动发现 |
| 数据文件路径 | oss://
oss:// 协议 | oss://
oss:// 协议（metadata.json 中需正确配置） |
注意事项
- 只读：当前版本仅支持 SELECT 查询，不支持 INSERT / UPDATE / DELETE。
- Catalog 可达性：Iceberg REST Catalog 或 HMS 服务必须能从 Lakehouse 的计算节点访问（需配置公网访问或内网打通）。
- 元数据路径：Iceberg metadata.json 中记录的数据文件路径需使用
oss://
oss://
（而非 s3://
s3://
或 file://
file://
），否则 Lakehouse 无法读取。
- Catalog 生命周期：外部 Catalog 与 Catalog Connection 绑定，修改 Connection 配置后需重建 Catalog。
- Connection 复用：同一存储账号的多个 Iceberg 表可共用同一 Catalog Connection。
