Paimon 外表--ByteHouse云数仓版-火山引擎

文档中心

ByteHouse云数仓版

外表

Paimon 外表

ByteHouse 云数仓版支持使用外表的方式进行联邦查询，用户无需通过数据导入，可以直接进行通过 Paimon 外表查询 Paimon 中的数据，从而提供了数据处理的灵活性和方便性。本文将介绍如何在 ByteHouse 中使用 Paimon 外表。

背景信息

Paimon 数据映射方式

对于 Paimon 数据表，当前 ByteHouse 支持创建 Paimon 外表、创建 Paimon 数据库、创建 Paimon 外部 Catalog 三种方式实现 ByteHouse 与 Paimon 的数据映射。

数据映射方式	数据映射说明
创建 Paimon 外部表	在表维度建立 ByteHouse 表到 Paimon 表的映射。源表 schema 变更不会直接同步，如果有变更，需删除 ByteHouse 中的外表重新创建一个外表。
创建 Paimon 外部数据库	在 Database 维度建立 ByteHouse Database 到 Paimon Database 的映射。建立库映射之后不需要再手动建立表映射，可自动同步数据库下的表映射，可以感知 Paimon 表的新增和删除，源表 schema 变更可直接同步至 ByteHouse 中。
创建 Paimon 外部 Catalog	在数据目录（Catalog）唯独建立 ByteHouse Catalog 到 Paimon Catalog 的映射。建立 Catalog 映射之后不需要再手动建立库、表映射，可自动同步 Catalog 下的库、表映射，可以感知 Paimon 库、表的新增和删除，源表 schema 变更可直接同步至 ByteHouse 中。创建 Paimon 外部 Catalog 的操作详情请参见 Paimon Catalog。

费用说明

外部表的功能旨在提供除 ByteHouse 内部表以外的其他数据的处理能力。通过一条简单的 DDL 语句，即可在 ByteHouse 上创建一张外部表，建立 ByteHouse 表与外部数据源的关联。

外部表在 ByteHouse 侧只会产生计算费用，遵循 ByteHouse 计算资源计费规则。
使用外部表功能时，外部表的数据不会复制一份存在 ByteHouse 上并产生存储费用。存储费用请关注外部数据源存储侧计费规则。
使用 ByteHouse 外部表访问外部数据源时，外部数据源可能会产生计算、访问、数据传输等费用，具体以外部数据源计费方式为准，请关注相应产品的说明。

使用限制

细分项	限制说明
Alter 操作	当前无法对 Bytehouse 外表，Bytehouse DB 进行 Alter 操作，例如，外表不支持增加列、删除列、改列名等操作；外部表数据库不支持`RENAME DATABASE`。
Time Travel	目前的实现方式是将版本信息藏在 table 名称中，即`tbl$version$<identifier>`。当前并不支持 Paimon 原生支持的其他多种类型的版本描述符，比如：时间戳（字符串，例如 2024-12-01） snapshotId（整数）分支名或者 tag 名，可以是任意的 string 内容在 ByteHouse 中，`<identifer>`只能是： snapshotId（整数）符合标识符命名规则的字符串
自动感知表结构变化	Database 方式：可以自动感知表结构变化，以及增加删除表 Table 方式：可以自动感知表结构变化
复杂数据类型	当前不支持复杂数据类型为 Nullable。

创建 Paimon 外部表

通过创建 ByteHouse 外部表，在表维度建立 ByteHouse 表到 Paimon 表的映射。Paimon 的数据可以存放在不同的分布式存储系统上，例如 HDFS、S3。下面具体介绍不同分布式存储系统上的建表语句：

Paimon on HDFS

创建外表时，您需指定关联的外表库表信息，当前支持指定外表的列信息，或不指定列信息通过自动推导获取对应的列信息。

指定列信息：要求所有指定的列名，在对应的 Paimon 表中都存在，并且类型等价或者兼容，否则会报错。
不指定列信息，自动推导对应的列信息：可以通过enable_schema_covert_fault_tolerance参数控制自动推导类型不存在的处理方式，当 Paimon 中的类型无法在 Bytehouse 中找到兼容类型时：取值1表示忽略；0表示报错；默认值是1。

手动指定列信息

CREATE TABLE `{tableName}` (
    `col_boolean` BOOLEAN,
    `col_tinyint` Int8,
    `col_smallint` Int16,
    `col_int` Int32,
    `col_bigint` Int64,
    `col_float` Float32,
    `col_double` Float64,
    `col_decimal` DECIMAL(10, 2),
    `col_date` DATE32,
    `col_time` DateTime,
    `col_timestamp` DateTime64(6),
    `col_char` FixedString(10),
    `col_varchar` String,
    `col_binary` FixedString(50),
    `col_varbinary` String,
    `col_array_int` Array(Int32),
    `col_map` Map(String, Int32),
    `col_struct` Tuple(`field_smallint` Int16, `field_varchar` String, `field_time` DateTime, `field_decimal` DECIMAL(28, 6), `field_varbinary` String)
) 
ENGINE = CnchPaimon('filesystem', '{warehouse}', '{paimonDatabaseName}', '{paimonTableName}');

参数	配置说明
建表描述	Paimon 表的列名和类型，列类型映射规则见下文的列数据类型映射章节。说明指定列名和类型，以及分区键等描述时：列名需要与 Paimon 表一一对应；列的顺序不需要一一对应。创建外表时，外表列可以只选择 Paimon 表中的部分列，但分区列必须要全部包含。外表列的分区需要通过 partition by 语句指定，同时需要与普通列一样定义到描述列表中。
引擎参数（Engine）	`filesystem`：固定参数。 warehouse：配置为 Paimon 的数仓连接的地址，例如：`hdfs://haruna/home/byte_flink_test/table_store/bytehouse_test`。注意这里填写的是 Paimon 的顶层目录。 paimonDatabaseName：指定 Paimon 中的数据库。 paimonTableName：指定 Paimon 中的表。

参数

配置说明

建表描述

Paimon 表的列名和类型，列类型映射规则见下文的列数据类型映射章节。

说明

指定列名和类型，以及分区键等描述时：

列名需要与 Paimon 表一一对应；列的顺序不需要一一对应。
创建外表时，外表列可以只选择 Paimon 表中的部分列，但分区列必须要全部包含。
外表列的分区需要通过 partition by 语句指定，同时需要与普通列一样定义到描述列表中。

引擎参数（Engine）

filesystem：固定参数。
warehouse：配置为 Paimon 的数仓连接的地址，例如：hdfs://haruna/home/byte_flink_test/table_store/bytehouse_test。
注意
这里填写的是 Paimon 的顶层目录。
paimonDatabaseName：指定 Paimon 中的数据库。
paimonTableName：指定 Paimon 中的表。

（推荐）自动推导列信息

CREATE TABLE `{tableName}`
ENGINE = CnchPaimon('filesystem', '{warehouse}', '{paimonDatabaseName}', '{paimonTableName}')
SETTINGS enable_schema_covert_fault_tolerance = 0;

参数	配置说明
建表描述	tableName：外表名称。Paimon 表的列名和类型，以及 Partition By key，将会在建表的时候自动推导建立。列类型映射规则见下文的数据类型映射章节。
引擎参数（Engine）	`filesystem`：固定参数。 warehouse：配置为 Paimon 的数仓连接的地址，例如：`hdfs://haruna/home/byte_flink_test/table_store/bytehouse_test`。注意这里填写的是 Paimon 的顶层目录。 paimonDatabaseName：指定 Paimon 中的数据库。 paimonTableName：指定 Paimon 中的表。
设置参数（SETTINGS）	enable_schema_covert_fault_tolerance：控制自动推导类型不存在的处理方式。当 Paimon 中的类型无法在 ByteHouse 中找到兼容类型时：取值`1`表示忽略；`0`表示报错；默认值是`1`。

Paimon on S3

手动指定列信息

CREATE TABLE `{tableName}` (
    `col_boolean` BOOLEAN,
    `col_tinyint` Int8,
    `col_smallint` Int16,
    `col_int` Int32,
    `col_bigint` Int64,
    `col_float` Float32,
    `col_double` Float64,
    `col_decimal` DECIMAL(10, 2),
    `col_date` DATE32,
    `col_time` DateTime,
    `col_timestamp` DateTime64(6),
    `col_char` FixedString(10),
    `col_varchar` String,
    `col_binary` FixedString(50),
    `col_varbinary` String,
    `col_array_int` Array(Int32),
    `col_map` Map(String, Int32),
    `col_struct` Tuple(`field_smallint` Int16, `field_varchar` String, `field_time` DateTime, `field_decimal` DECIMAL(28, 6), `field_varbinary` String)
)
ENGINE = CnchPaimon('filesystem', '${warehouse}', '{paimonDatabaseName}', '{paimonTableName}')
SETTINGS
endpoint='{endpoint}', 
ak_id='{accessKey}', 
ak_secret='{accessSecretKey}',
s3_extra_options='fs.s3a.connection.maximum=1000';

参数	配置说明
建表描述	Paimon 表的列名和类型，列类型映射规则见下文的列类型映射章节。
引擎参数（Engine）	`filesystem`：固定参数。 warehouse：配置为 Paimon 的数仓连接的地址，例如：`s3://test-dev-hcf/paimon`。注意这里填写的是 Paimon 的顶层目录。如果 Paimon 的数据分布式存储系统是火山引擎 TOS，此处也需配置为`s3://`开头的域名。例如，外部数据源的存储路径复制后为：`bhlasinfo/paimon`。则，拼接后待配置的地址为：`s3://bhlasinfo/paimon`。 paimonDatabaseName：指定 Paimon 中的数据库。 paimonTableName：指定 Paimon 中的表。
设置参数（SETTINGS）	endpoint: 外部数据源的连接地址，例如，如果您使用的是火山引擎对象存储服务 TOS，可登录 TOS 控制台，通过桶列表>桶名称>概览>访问域名路径，查看所需 endpoint，如下图所示，endpoint 为`tos-s3-cn-beijing.volces.com`。 ak_id/ak_secrent，具有 S3 访问权限的密钥。
S3 参数设置	s3_extra_options：可选参数，用于设置 S3 调优参数，您可参考以下格式设置调优参数： `s3_extra_options='s3.xxx=value1,s3.yyy=value2,s3.zzz=value3'` `fs.s3a.connection.maximum`是常见的调优参数（默认值为 500），用于设置与 S3 存储服务建立连接时，连接池的最大大小；全部参数请参考 Hadoop 帮助文档。

（推荐）自动推导列信息

CREATE TABLE `{tableName}`
ENGINE = CnchPaimon('filesystem', '${warehouse}', '{paimonDatabaseName}', '{paimonTableName}')
SETTINGS
endpoint='{endpoint}', 
ak_id='{accessKey}', 
ak_secret='{accessSecretKey}',
s3_extra_options='fs.s3a.connection.maximum=1000',
enable_schema_covert_fault_tolerance = 0;

参数	配置说明
建表描述	自定义 Paimon 外表名称。表的列名和类型，以及 Partition By key，将会在建表的时候自动推导建立。列类型映射规则见下文的列类型映射章节。
引擎参数（Engine）	`filesystem`：固定参数。 warehouse：配置为 Paimon 的数仓连接的地址，例如：`s3://test-dev-hcf/paimon`。注意这里填写的是 Paimon 的顶层目录。如果 Paimon 的数据分布式存储系统是火山引擎 TOS，此处也需配置为`s3://`开头的域名。例如，外部数据源的存储路径复制后为：`bhlasinfo/paimon`。则，拼接后待配置的地址为：`s3://bhlasinfo/paimon`。 paimonDatabaseName：指定 Paimon 中的数据库。 paimonTableName：指定 Paimon 中的表。
设置参数（SETTINGS）	enable_schema_covert_fault_tolerance：控制自动推导类型不存在的处理方式。当 Paimon 中的类型无法在 ByteHouse 中找到兼容类型时：取值`1`表示忽略；`0`表示报错；默认值是`1`。 endpoint：外部数据源的连接地址，例如，如果您使用的是火山引擎对象存储服务 TOS，可登录 TOS 控制台，通过桶列表>桶名称>概览>访问域名路径，查看所需 endpoint，如下图所示，endpoint 为`tos-s3-cn-beijing.volces.com`。 ak_id/ak_secrent，具有 S3 访问权限的密钥。
S3 参数设置	s3_extra_options：可选参数，用于设置 S3 调优参数，您可参考以下格式设置调优参数： `s3_extra_options='s3.xxx=value1,s3.yyy=value2,s3.zzz=value3'` `fs.s3a.connection.maximum`是常见的调优参数（默认值为 500），用于设置与 S3 存储服务建立连接时，连接池的最大大小；全部参数请参考 Hadoop 帮助文档。

创建 Paimon 外部数据库

通过创建 ByteHouse 外部数据库，在 Database 维度建立 ByteHouse Database 到 Paimon Database 的映射。建立库映射之后不需要再手动建立表映射，可自动同步数据库下的表映射。
Paimon 的数据可以存放在不同的分布式存储系统上，例如 HDFS、S3。下面具体介绍不同分布式存储系统上的建表语句：

Paimon on HDFS

CREATE DATABASE {databaseName}
ENGINE = Paimon('filesystem', '{warehouse}', '{paimonDatabaseName}')
SETTINGS enable_schema_covert_fault_tolerance = 1;

参数	配置说明
数据库描述	自定义外部数据库名称。
引擎参数（Engine）	`filesystem`：固定参数。 warehouse：配置为 Paimon 的数仓连接的地址，例如：`hdfs://haruna/home/byte_flink_test/table_store/bytehouse_test`。注意这里填写的是 Paimon 的顶层目录。 paimonDatabaseName：指定 Paimon 中的数据库。
设置参数（SETTINGS）	enable_schema_covert_fault_tolerance：控制自动推导类型不存在的处理方式。当 Paimon 中的类型无法在 ByteHouse 中找到兼容类型时：取值`1`表示忽略；`0`表示报错；默认值是`1`。当设置成`0`时，那些存在类型兼容问题的 Table 将无法展示出来。

Paimon on S3

CREATE DATABASE {databaseName}
ENGINE = Paimon('filesystem', '{warehouse}', '{paimonDatabaseName}')
SETTINGS
endpoint='{endpoint}', 
ak_id='{accessKey}', 
ak_secret='{accessSecretKey}',
s3_extra_options='fs.s3a.connection.maximum=1000';

参数	配置说明
数据库描述	自定义外部数据库名称。
引擎参数（Engine）	`filesystem`：固定参数。 warehouse：配置为 Paimon 的数仓连接的地址，例如：`s3://test-dev-hcf/paimon`。注意这里填写的是 Paimon 的顶层目录。如果 Paimon 的数据分布式存储系统是火山引擎 TOS，此处也需配置为`s3://`开头的域名。例如，外部数据源的存储路径复制后为：`bhlasinfo/paimon`。则，拼接后待配置的地址为：`s3://bhlasinfo/paimon`。 paimonDatabaseName：指定 Paimon 中的数据库。
设置参数（SETTINGS）	enable_schema_covert_fault_tolerance：控制自动推导类型不存在的处理方式。当 Paimon 中的类型无法在 ByteHouse 中找到兼容类型时：取值`1`表示忽略；`0`表示报错；默认值是`1`。当设置成`0`时，那些存在类型兼容问题的 Table 将无法展示出来。 endpoint: 外部数据源的连接地址，例如，如果您使用的是火山引擎对象存储服务 TOS，可登录 TOS 控制台，通过桶列表>桶名称>概览>访问域名路径，查看所需 endpoint，如下图所示，endpoint 为`tos-s3-cn-beijing.volces.com`。 ak_id/ak_secrent，具有 S3 访问权限的密钥。
S3 参数设置	s3_extra_options：可选参数，用于设置 S3 调优参数，您可参考以下格式设置调优参数： `s3_extra_options='s3.xxx=value1,s3.yyy=value2,s3.zzz=value3'` `fs.s3a.connection.maximum`是常见的调优参数（默认值为 500），用于设置与 S3 存储服务建立连接时，连接池的最大大小；全部参数请参考 Hadoop 帮助文档。

写入外部表

您可使用 INSERT INTO 或 INSERT OVERWRITE 方式写入外部表。

INSERT INTO

您可以使用基础的 INSERT INTO 语句写入数据。

# 方式 1
INSERT INTO database.table VALUES (val1, val2, ...), (val1, val2, ...), ...;

# 方式 2
INSERT INTO database.table SELECT [col1, col2, ... | *] FROM source_db.source_table;

参数	配置说明
数据库及表描述	database.table：指定需查询的数据库和表名称。如果您在执行该语句前，已执行 `USE database_name`，此时 database 可不填写。
写入参数描述	VALUES：填写需插入的数值，填写格式为 `(val1, val2, ...), (val1, val2, ...),...`，示例如下： `INSERT INTO example_table VALUES (1, 'a', '2021-07-27'), (2, 'b', '2021-07-27')` SELECT：使用 SELECT 查询的结果写入数据，可按照 SELECT 语句的语法填写，示例如下： `# SELECT 源表中的所有数据插入目标表 INSERT INTO example_table SELECT * FROM example_table # SELECT 源表中的指定数据插入目标表 INSERT INTO example_table SELECT s,d,n FROM example_table`

参数

配置说明

数据库及表描述

database.table：指定需查询的数据库和表名称。如果您在执行该语句前，已执行 USE database_name，此时 database 可不填写。

写入参数描述

VALUES：填写需插入的数值，填写格式为 (val1, val2, ...), (val1, val2, ...),...，示例如下：
```
INSERT INTO example_table VALUES (1, 'a', '2021-07-27'), (2, 'b', '2021-07-27')
```

SELECT：使用 SELECT 查询的结果写入数据，可按照 SELECT 语句的语法填写，示例如下：

# SELECT 源表中的所有数据插入目标表
INSERT INTO example_table SELECT * FROM example_table

# SELECT 源表中的指定数据插入目标表
INSERT INTO example_table SELECT s,d,n FROM example_table

INSERT OVERWRITE

该语句的功能是重写表。

# 方式 1
INSERT OVERWRITE database.table VALUES (val1, val2, ...), (val1, val2, ...), ...;

# 方式 2
INSERT OVERWRITE database.table SELECT [col1, col2, ... | *] FROM source_db.source_table;

参数	配置说明
数据库及表描述	database.table：指定需查询的数据库和表名称。如果您在执行该语句前，已执行 `USE database_name`，此时 database 可不填写。
写入参数描述	VALUES：填写需插入的数值，填写格式为 `(val1, val2, ...), (val1, val2, ...),...`，示例如下： `INSERT OVERWRITE example_table VALUES (1, 'a', '2021-07-27'), (2, 'b', '2021-07-27')` SELECT：使用 SELECT 查询的结果写入数据，可按照 SELECT 语句的语法填写，示例如下： `# SELECT 源表中的所有数据插入目标表 INSERT OVERWRITE example_table SELECT * FROM example_table # SELECT 源表中的指定数据插入目标表 INSERT OVERWRITE example_table SELECT s,d,n FROM example_table`

参数

配置说明

数据库及表描述

database.table：指定需查询的数据库和表名称。如果您在执行该语句前，已执行 USE database_name，此时 database 可不填写。

写入参数描述

VALUES：填写需插入的数值，填写格式为 (val1, val2, ...), (val1, val2, ...),...，示例如下：
```
INSERT OVERWRITE example_table VALUES (1, 'a', '2021-07-27'), (2, 'b', '2021-07-27')
```

SELECT：使用 SELECT 查询的结果写入数据，可按照 SELECT 语句的语法填写，示例如下：

# SELECT 源表中的所有数据插入目标表
INSERT OVERWRITE example_table SELECT * FROM example_table

# SELECT 源表中的指定数据插入目标表
INSERT OVERWRITE example_table SELECT s,d,n FROM example_table

查询外部表

外表的查询和普通表的查询操作一致。

通用方式。
```
SELECT * FROM  t WHERE xxx;
```

删除外部库表

外部库表的删除操作和普通表的删除操作一致。

删除外部数据库。
注意
删除外部数据库后，外部数据库下的所有外部表也将同时被删除，请谨慎操作。
```
DROP DATABASE example_db
```
删除外部数据表。
```
DROP TABLE example_db.example_table
```

快照查询

-- 指定snapshotId=123456789
SELECT * FROM tbl$version$123456789;

-- 指定branch名称=branch_1
SELECT * FROM tbl$version$branch_1;

-- 指定tag名称=tag_1
SELECT * FROM tbl$version$tag_1;

查询表的元信息

以下为当前支持查询的所有 Paimon 表的元信息：

manifests：包含关于数据文件清单的信息，用于追踪数据的实际物理存储位置。
snapshots：提供快照级别的信息，允许用户查看数据在不同时间点的状态。
options：包含建表时的配置选项或参数设置。
schemas：描述数据集的结构，包括列名、数据类型等信息。
partitions：如果数据是分区存储的，这个表会提供有关分区的信息。
audit_log：记录对数据执行的操作日志，可用于审计目的。
files：包含实际存储的数据文件的相关信息。
tags：标记特定的重要数据状态，方便快速定位和回滚到特定版本。
branches：提供分支信息，用于支持并行开发或实验不同的数据集版本。
consumers：可能涉及数据订阅者或使用者的信息，尤其是在流式数据处理环境中。
ro：优化读取性能。
aggregation_fields：与聚合字段相关的信息，有助于理解或操作汇总数据。
statistics：提供关于数据集的各种统计信息，如大小、分布等，这对于优化查询性能非常有用。

SELECT * FROM tbl$metadata$manifests;
SELECT * FROM tbl$metadata$snapshots;
SELECT * FROM tbl$metadata$options;
SELECT * FROM tbl$metadata$schemas;
SELECT * FROM tbl$metadata$partitions;
SELECT * FROM tbl$metadata$audit_log;
SELECT * FROM tbl$metadata$files;
SELECT * FROM tbl$metadata$tags;
SELECT * FROM tbl$metadata$branches;
SELECT * FROM tbl$metadata$consumers;
SELECT * FROM tbl$metadata$ro;
SELECT * FROM tbl$metadata$aggregation_fields;
SELECT * FROM tbl$metadata$statistics;

参考：数据类型映射

说明

您可以通过enable_schema_covert_fault_tolerance参数控制当映射数据的数据类型不支持时处理方式。当 Paimon 中的类型无法在 Bytehouse 中找到兼容类型时：取值1表示忽略；0表示报错；默认值是1。

Paimon 类型	ByteHouse 类型
Boolean	UInt8
TinyInt	Int8
SmallInt	Int16
Int	Int32
BigInt	Int64
Float	Float32
Double	Float64
Date	Date32
Time	不支持
Timestamp Wihtout TZ	DateTime64(UTC)
Timestamp With Local TZ	DateTime64(local time zone)
Char	FixedString
Varchar	String
Binary	FixedString
VarBinary	String
Decimal	Deciaml
Array	Array
Map	Map
Row	Tuple

最近更新时间：2026.01.08 15:53:45

这个页面对您有帮助吗？

有用

无用

ByteHouse云数仓版

Paimon 数据映射方式 #

费用说明 #

Paimon on HDFS #

手动指定列信息 #

（推荐）自动推导列信息 #

Paimon on S3 #

手动指定列信息 #

（推荐）自动推导列信息 #

Paimon on HDFS #

Paimon on S3 #

INSERT INTO #

INSERT OVERWRITE #

Paimon 数据映射方式

费用说明

Paimon on HDFS

手动指定列信息

（推荐）自动推导列信息

Paimon on S3

手动指定列信息

（推荐）自动推导列信息

Paimon on HDFS

Paimon on S3

INSERT INTO

INSERT OVERWRITE