Paimon 外部表

概述

ClickZetta Lakehouse 支持通过外部表（External Table）直接读取存储在对象存储上的 Apache Paimon 格式数据，无需导入数据即可进行查询分析。

已验证版本：Paimon 0.5.0、0.6.0、0.6.1、0.7.0、0.8.x（全部兼容）
已验证云厂商：阿里云 OSS（其他云厂商配置方式相同，见下文）

前提条件

已有 Paimon 格式数据存储在对象存储（OSS / COS / S3）上
在 ClickZetta Lakehouse 中已创建对应的存储 Connection

第一步：创建存储 Connection

Connection 用于授权 Lakehouse 访问你的对象存储。每个云厂商创建方式如下。

阿里云 OSS

CREATE CONNECTION conn_oss TYPE OSS PROPERTIES ( 'ACCESS_ID' = '<your-access-key-id>', 'ACCESS_KEY' = '<your-access-key-secret>', 'ENDPOINT' = 'oss-cn-hangzhou.aliyuncs.com' -- 替换为 bucket 所在 region 的 endpoint );

常用 OSS Endpoint 参考：

Region	Endpoint（公网）	Endpoint（内网，Lakehouse 同 region 推荐）
华东 2（上海）	`oss-cn-shanghai.aliyuncs.com` oss-cn-shanghai.aliyuncs.com	`oss-cn-shanghai-internal.aliyuncs.com` oss-cn-shanghai-internal.aliyuncs.com
华东 1（杭州）	`oss-cn-hangzhou.aliyuncs.com` oss-cn-hangzhou.aliyuncs.com	`oss-cn-hangzhou-internal.aliyuncs.com` oss-cn-hangzhou-internal.aliyuncs.com
华北 2（北京）	`oss-cn-beijing.aliyuncs.com` oss-cn-beijing.aliyuncs.com	`oss-cn-beijing-internal.aliyuncs.com` oss-cn-beijing-internal.aliyuncs.com

腾讯云 COS

CREATE CONNECTION conn_cos TYPE COS PROPERTIES ( 'ACCESS_ID' = '<your-secret-id>', 'ACCESS_KEY' = '<your-secret-key>', 'ENDPOINT' = 'cos.ap-shanghai.myqcloud.com' -- 替换为 bucket 所在 region 的 endpoint );

常用 COS Endpoint 参考：

Region	Endpoint
上海	`cos.ap-shanghai.myqcloud.com` cos.ap-shanghai.myqcloud.com
北京	`cos.ap-beijing.myqcloud.com` cos.ap-beijing.myqcloud.com
广州	`cos.ap-guangzhou.myqcloud.com` cos.ap-guangzhou.myqcloud.com

AWS S3

CREATE CONNECTION conn_s3 TYPE S3 PROPERTIES ( 'ACCESS_ID' = '<your-access-key-id>', 'ACCESS_KEY' = '<your-secret-access-key>', 'ENDPOINT' = 's3.cn-north-1.amazonaws.com.cn' -- 替换为 bucket 所在 region 的 endpoint );

常用 S3 Endpoint 参考：

Region	Endpoint
中国（北京）	`s3.cn-north-1.amazonaws.com.cn` s3.cn-north-1.amazonaws.com.cn
中国（宁夏）	`s3.cn-northwest-1.amazonaws.com.cn` s3.cn-northwest-1.amazonaws.com.cn

注意：Connection 创建后可通过

DESCRIBE CONNECTION <name>

DESCRIBE CONNECTION <name>

确认配置，

SHOW CONNECTIONS

SHOW CONNECTIONS

查看所有已有 Connection。

第二步：创建 Paimon 外部表

基本语法

方式一：自动推断 schema（推荐）

无需手动指定列定义，Lakehouse 直接从 Paimon 表的

schema/

schema/

元数据中读取：

CREATE EXTERNAL TABLE <table_name> USING PAIMON LOCATION '<object-storage-path>' CONNECTION <connection_name>;

方式二：手动指定 schema

适用于只读取部分列，或需要显式控制类型映射的场景：

CREATE EXTERNAL TABLE <table_name> ( <col1> <type1>, <col2> <type2>, ... ) USING PAIMON LOCATION '<object-storage-path>' CONNECTION <connection_name>;

参数说明

参数	说明
`table_name` table_name	Lakehouse 中的外部表名称
列定义	与 Paimon 表 schema 对应，类型映射见下文
`LOCATION` LOCATION	Paimon 表在对象存储上的路径，需指向具体表目录（包含 `schema/` schema/ 、 `snapshot/` snapshot/ 子目录）
`CONNECTION` CONNECTION	第一步创建的 Connection 名称

数据类型兼容性

以下类型经过实测验证（Paimon 0.8.x，阿里云杭州环境，含边界值和 NULL 测试）：

Paimon 类型	Lakehouse 建表类型	验证状态	备注
`TINYINT` TINYINT	`TINYINT` TINYINT	✅ 支持	范围 -128 ~ 127
`SMALLINT` SMALLINT	`SMALLINT` SMALLINT	✅ 支持	范围 -32768 ~ 32767
`INT` INT	`INT` INT	✅ 支持
`BIGINT` BIGINT	`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(6)` TIMESTAMP(6)	`TIMESTAMP` TIMESTAMP	✅ 支持	微秒精度
`DECIMAL(p, s)` DECIMAL(p, s)	`DECIMAL(p, s)` DECIMAL(p, s)	✅ 支持	含正/负/零/NULL
`CHAR(N)` CHAR(N)	—	❌ 不支持	Lakehouse reader 报 `Unsupported type: CHAR` Unsupported type: CHAR ，改用 `STRING` STRING
`VARCHAR(N)` VARCHAR(N)	—	❌ 不支持	同上，改用 `STRING` STRING
`ARRAY<T>` ARRAY<T>	`ARRAY<T>` ARRAY<T>	✅ 支持	含 null 元素；T 为基础类型
`MAP<K, V>` MAP<K, V>	`MAP<K, V>` MAP<K, V>	✅ 支持	Paimon schema 中 key 需为 `NOT NULL` NOT NULL （如 `STRING NOT NULL` STRING NOT NULL ）；建外部表时填写普通 `MAP<K,V>` MAP<K,V> 即可，类型由 Paimon schema 驱动
`ROW / STRUCT` ROW / STRUCT	`STRUCT<f1:T1, f2:T2>` STRUCT<f1:T1, f2:T2>	✅ 支持	含 null 字段，支持中文字段值

重要：

Paimon 表中如有
```
CHAR(N)
```
CHAR(N)
或
```
VARCHAR(N)
```
VARCHAR(N)
类型列，Lakehouse 读取时会报错
```
Unsupported type: CHAR
```
Unsupported type: CHAR
。建表时应统一使用
```
STRING
```
STRING
类型替代。
```
MAP
```
MAP
类型的 key 在 Paimon schema 中必须标注为
```
NOT NULL
```
NOT NULL
（如
```
MAP<STRING NOT NULL, INT>
```
MAP<STRING NOT NULL, INT>
），否则 Lakehouse C++ reader 报错。建外部表时 DDL 填写普通
```
MAP<K,V>
```
MAP<K,V>
即可，key NOT NULL 约束来自 Paimon 数据本身的 schema。

示例一：主键表（含分区）

-- Paimon 主键表，按 dt 分区，bucket=2 CREATE EXTERNAL TABLE ext_paimon_orders ( order_id INT, user_id INT, product_name STRING, amount DOUBLE, status STRING, dt STRING ) USING PAIMON LOCATION 'oss://your-bucket/catalog/test_db.db/orders' CONNECTION conn_oss;

示例二：Append-only 表

-- Paimon append-only 表，bucket=-1（unaware 模式） CREATE EXTERNAL TABLE ext_paimon_products ( product_id INT, name STRING, category STRING, price DOUBLE, stock INT ) USING PAIMON LOCATION 'oss://your-bucket/catalog/test_db.db/products' CONNECTION conn_oss;

LOCATION 路径说明：路径需指向 Paimon 表目录本身，不是 catalog 或 database 目录。例如 Paimon warehouse 为

oss://bucket/catalog/

oss://bucket/catalog/

，数据库为

test_db

test_db

，表为

orders

orders

，则 LOCATION 填写

oss://bucket/catalog/test_db.db/orders

oss://bucket/catalog/test_db.db/orders

。

第三步：查询验证

-- 查看表结构 DESC TABLE ext_paimon_orders; -- 全量查询 SELECT * FROM ext_paimon_orders LIMIT 10; -- 带分区过滤（利用 Paimon 分区裁剪） SELECT * FROM ext_paimon_orders WHERE dt = '2024-01-01'; -- 聚合查询 SELECT status, COUNT(*) AS cnt, SUM(amount) AS total FROM ext_paimon_orders GROUP BY status ORDER BY total DESC; -- 多表 JOIN SELECT o.order_id, o.product_name, o.amount, p.category, p.stock FROM ext_paimon_orders o JOIN ext_paimon_products p ON o.product_name = p.name WHERE o.status = 'paid' ORDER BY o.order_id;

腾讯云 / AWS 完整示例

以下以腾讯云 COS 为例，AWS S3 仅替换 Connection 类型和 LOCATION 路径前缀即可。

-- 腾讯云：创建 Connection CREATE CONNECTION conn_cos TYPE COS PROPERTIES ( 'ACCESS_ID' = '<secret-id>', 'ACCESS_KEY' = '<secret-key>', 'ENDPOINT' = 'cos.ap-shanghai.myqcloud.com' ); -- 腾讯云：创建外部表 CREATE EXTERNAL TABLE ext_paimon_orders ( order_id INT, user_id INT, product_name STRING, amount DOUBLE, status STRING, dt STRING ) USING PAIMON LOCATION 'cos://your-bucket/catalog/test_db.db/orders' CONNECTION conn_cos;

-- AWS：创建 Connection CREATE CONNECTION conn_s3 TYPE S3 PROPERTIES ( 'ACCESS_ID' = '<access-key-id>', 'ACCESS_KEY' = '<secret-access-key>', 'ENDPOINT' = 's3.cn-north-1.amazonaws.com.cn' ); -- AWS：创建外部表 CREATE EXTERNAL TABLE ext_paimon_orders ( order_id INT, user_id INT, product_name STRING, amount DOUBLE, status STRING, dt STRING ) USING PAIMON LOCATION 's3://your-bucket/catalog/test_db.db/orders' CONNECTION conn_s3;

注意事项

只读（当前版本限制）：外部表当前版本仅支持 SELECT 查询，不支持 INSERT / UPDATE / DELETE / MERGE 写入操作。如需写入 Paimon 数据，请通过 Paimon 原生 SDK（如 pypaimon、Flink、Spark）直接写入对象存储，再通过外部表读取。
Schema 一致性：手动指定列定义时，需与 Paimon 表实际 schema 一致，类型不匹配会导致查询报错。推荐使用 schema 自动推断（不指定列定义）。
LOCATION 精度：路径需指向表级目录（含
```
schema/
```
schema/
、
```
snapshot/
```
snapshot/
子目录），不能指向更上层的 catalog 或 database 目录。
Endpoint 选择：Lakehouse 与对象存储在同一 region 时，使用内网 Endpoint 可获得更低延迟和更高带宽。
Connection 复用：同一存储账号下的多张 Paimon 外部表可共用同一个 Connection。
IF NOT EXISTS：建议在 DDL 中加上
```
IF NOT EXISTS
```
IF NOT EXISTS
，避免重复执行时报错。

联系我们