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

文档中心

ByteHouse云数仓版

外表

Iceberg 外表

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

背景信息

Iceberg 数据映射方式

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

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

费用说明

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

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

使用限制

细分项	限制说明
Schema Evolution	ByteHouse 支持查询存在 Schema Evolution 的表，但对源表的 schema 操作类型有所限制：支持的源表操作：新增列、删除列、修改列类型，ByteHouse 可正常查询不支持的操作：修改列名，ByteHouse 查询会报错
Time Travel	目前的实现方式是将版本信息藏在 table 名称中，即 `tbl$version$<identifier>`。当前并不支持 Iceberg 原生支持的其他多种类型的版本描述符，比如：时间戳（字符串，例如 2024-12-01） snapshotId（整数）分支名或者 tag 名，可以是任意的 string 内容采用当前 ByteHouse 支持的这种版本描述符的传入方式，那么 `<identifer>` 只能是： snapshotId（整数）符合标识符命名规则的字符串
自动感知表结构变化	Database 方式：可以自动感知表结构变化，以及增加删除表 Table 方式：可以自动感知表结构变化

细分项

限制说明

Schema Evolution

ByteHouse 支持查询存在 Schema Evolution 的表，但对源表的 schema 操作类型有所限制：

支持的源表操作：新增列、删除列、修改列类型，ByteHouse 可正常查询
不支持的操作：修改列名，ByteHouse 查询会报错

Time Travel

目前的实现方式是将版本信息藏在 table 名称中，即 tbl$version$<identifier>。当前并不支持 Iceberg 原生支持的其他多种类型的版本描述符，比如：

时间戳（字符串，例如 2024-12-01）
snapshotId（整数）
分支名或者 tag 名，可以是任意的 string 内容

采用当前 ByteHouse 支持的这种版本描述符的传入方式，那么 <identifer> 只能是：

snapshotId（整数）
符合标识符命名规则的字符串

自动感知表结构变化

Database 方式：可以自动感知表结构变化，以及增加删除表
Table 方式：可以自动感知表结构变化

创建 Iceberg 外部数据库

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

Iceberg on HDFS

CREATE DATABASE test_iceberg_db_hdfs
ENGINE = Iceberg('hadoop', '{warehouse}', '{icebergDatabaseName}')
SETTINGS enable_schema_covert_fault_tolerance = 1;

参数

配置说明

数据库描述

自定义外部数据库名称。

引擎参数（Engine）

hadoop：固定配置为 hadoop。
warehouse：配置为 Iceberg 的数仓连接的地址，例如：hdfs://haruna/home/byte_flink_test/table_store/ByteHouse_test。
注意
这里填写的是 Iceberg 的顶层目录。
IcebergDatabaseName：指定 Iceberg 中的数据库。

设置参数（SETTINGS）

enable_schema_covert_fault_tolerance：控制自动推导类型不存在的处理方式。
当 Iceberg 中的类型无法在 ByteHouse 中找到兼容类型时：取值 1 表示忽略；0 表示报错；

默认值是 1。
当设置成 0 时，那些存在类型兼容问题的 Table 将无法展示出来。

Iceberg on S3

CREATE DATABASE {databaseName}
ENGINE = Iceberg('hadoop', '{warehouse}', '{icebergDatabaseName}')
SETTINGS
endpoint='{endpoint}', 
ak_id='{accessKey}', 
ak_secret='{accessSecretKey}',
s3_extra_options='s3.paging.maximum=1000';

参数	配置说明
数据库描述	自定义外部数据库名称。
引擎参数（Engine）	hadoop：固定配置为 hadoop。 warehouse：配置为 Iceberg 的数仓连接的地址，例如：`tos://test-dev-hcf/iceberg`。注意这里填写的是 Iceberg 的顶层目录。如果 Iceberg 的数据存储文件系统是火山引擎 TOS，此处可配置为 `tos://` 开头或 `s3://` 开头的域名。例如，外部数据源的存储路径复制后为：`bhlasinfo/Iceberg`。则，拼接后待配置的地址可以是：`tos://bhlasinfo/Iceberg`、`s3://bhlasinfo/Iceberg`。 IcebergDatabaseName：指定 Iceberg 中的数据库。
设置参数（SETTINGS）	enable_schema_covert_fault_tolerance：控制自动推导类型不存在的处理方式。当Iceberg中的类型无法在 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 帮助文档。

创建 Iceberg 外部表

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

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

Iceberg 的数据可以存放在不同的文件系统上，例如 HDFS、S3。下面具体介绍不同文件系统上的建表语句：

Iceberg on HDFS

手动指定列信息

CREATE TABLE `{tableName}` (
    `col_boolean` BOOLEAN,
    `col_integer` Int32,
    `col_long` Int64,
    `col_float` Float32,
    `col_double` Float64,
    `col_decimal` DECIMAL(10, 2),
    `col_date` DATE32,
    `col_timestamp` DateTime64(3),
    `col_uuid` UUID,
    `col_string` String,
    `col_fixed` FixedString(50),
    `col_binary` String,
    `col_list_integer` Array(Int32),
    `col_map` Map(String, Int32),
    `col_struct` Tuple(`field_integer` Int32, `field_string` String, `field_timestamp` DateTime64(3), `field_decimal` DECIMAL(28, 6), `field_binary` String)
) 
ENGINE = CnchIceberg('hadoop', '{warehouse}', '{icebergDatabaseName}', '{icebergTableName}');

参数

配置说明

建表描述

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

说明

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

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

引擎参数（Engine）

hadoop：固定配置为 hadoop。
warehouse：配置为Iceberg的数仓连接的地址，例如：hdfs://haruna/home/byte_flink_test/table_store/ByteHouse_test。
注意
这里填写的是 Iceberg 的顶层目录。
IcebergDatabaseName：指定 Iceberg 中的数据库。
IcebergTableName：指定 Iceberg 中的表。

自动推导列信息

CREATE TABLE `{tableName}`
ENGINE = CnchIceberg('hadoop', '{warehouse}', '{icebergDatabaseName}', '{icebergTableName}')
SETTINGS enable_schema_covert_fault_tolerance = 1;

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

参数

配置说明

建表描述

Iceberg 表的列名和类型，以及 Partition By key，将会在建表的时候自动推导建立列类型映射规则见下文的 列类型映射 章节。

引擎参数（Engine）

hadoop：固定配置为 hadoop。
warehouse：配置为 Iceberg 的数仓连接的地址，例如：hdfs://haruna/home/byte_flink_test/table_store/ByteHouse_test。
注意
这里填写的是 Iceberg 的顶层目录。
IcebergDatabaseName：指定 Iceberg 中的数据库。
IcebergTableName：指定 Iceberg 中的表。

设置参数（SETTINGS）

默认值是 1。
当设置成 0 时，那些存在类型兼容问题的 Table 将无法展示出来。

Iceberg on S3（TOS）

手动指定列信息

CREATE TABLE `{tableName}` (
    `col_boolean` BOOLEAN,
    `col_integer` Int32,
    `col_long` Int64,
    `col_float` Float32,
    `col_double` Float64,
    `col_decimal` DECIMAL(10, 2),
    `col_date` DATE32,
    `col_timestamp` DateTime64(3),
    `col_uuid` UUID,
    `col_string` String,
    `col_fixed` FixedString(50),
    `col_binary` String,
    `col_list_integer` Array(Int32),
    `col_map` Map(String, Int32),
    `col_struct` Tuple(`field_integer` Int32, `field_string` String, `field_timestamp` DateTime64(3), `field_decimal` DECIMAL(28, 6), `field_binary` String)
) 
ENGINE = CnchIceberg('hadoop', '{warehouse}', '{icebergDatabaseName}', '{icebergTableName}')
SETTINGS
endpoint='{endpoint}', 
ak_id='{accessKey}', 
ak_secret='{accessSecretKey}',
s3_extra_options='s3.paging.maximum=1000';

参数	配置说明
建表描述	Iceberg 表的列名和类型，列类型映射规则见下文的列类型映射章节。说明指定列名和类型，以及分区键等描述时：列名需要与 Iceberg 表一一对应；列的顺序不需要一一对应创建外表时，外表列可以只选择 Iceberg 表中的部分列，但分区列必须要全部包含。外表列的分区需要通过 partition by 语句指定，同时需要与普通列一样定义到描述列表中。
引擎参数（Engine）	hadoop：固定配置为 hadoop。 warehouse：配置为 Iceberg 的数仓连接的地址，例如：`tos://test-dev-hcf/iceberg`。注意这里填写的是 Iceberg 的顶层目录。如果 Iceberg 的数据存储文件系统是火山引擎 TOS，此处可配置为 `tos://` 开头或 `s3://` 开头的域名。例如，外部数据源的存储路径复制后为：`bhlasinfo/Iceberg`。则，拼接后待配置的地址可以是：`tos://bhlasinfo/Iceberg`、`s3://bhlasinfo/Iceberg`。 IcebergDatabaseName：指定 Iceberg 中的数据库。 IcebergTableName：指定 Iceberg 中的表。
设置参数（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 = CnchIceberg('hadoop', '{warehouse}', '{icebergDatabaseName}', '{icebergTableName}')
SETTINGS
endpoint='{endpoint}', 
ak_id='{accessKey}', 
ak_secret='{accessSecretKey}',
s3_extra_options='s3.paging.maximum=1000';

参数	配置说明
建表描述	自定义外部数据表名称。Iceberg 表的列名和类型，以及 Partition By key，将会在建表的时候自动推导建立。列类型映射规则见下文的列类型映射章节。
引擎参数（Engine）	hadoop：固定配置为 hadoop。 warehouse：配置为 Iceberg 的数仓连接的地址，例如：`tos://test-dev-hcf/iceberg`。注意这里填写的是 Iceberg 的顶层目录。如果 Iceberg 的数据存储文件系统是火山引擎 TOS，此处可配置为 `tos://` 开头或 `s3://` 开头的域名。例如，外部数据源的存储路径复制后为：`bhlasinfo/Iceberg`。则，拼接后待配置的地址可以是：`tos://bhlasinfo/Iceberg`、`s3://bhlasinfo/Iceberg`。 IcebergDatabaseName：指定 Iceberg 中的数据库。
设置参数（SETTINGS）	enable_schema_covert_fault_tolerance：控制自动推导类型不存在的处理方式。当 Iceberg 中的类型无法在 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_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;

查询表的元信息

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

snapshots：记录数据集的所有快照信息，用于追踪和恢复数据的历史版本。
refs：包含指向快照的引用（分支和标签），支持并行开发和标记重要版本。
history：记录数据集的变更历史，帮助审计和回溯数据的变化。
files：提供数据集中实际物理存储的数据文件的相关信息，便于数据管理和性能优化。
properties：Schema相关的配置属性。

select * from tbl$metadata$snapshots;
select * from tbl$metadata$refs;
select * from tbl$metadata$history;
select * from tbl$metadata$files;
select * from tbl$metadata$properties;

参考：数据类型映射

Iceberg 类型	ByteHouse 类型
Boolean	UInt8
Integer	Int32
Long	Int64
Float	Float32
Double	Float64
Date	Date32
Time	不支持
Timestamp	DateTime64(UTC)
String	String
UUID	UUID
Fixed	FixedString
Binary	String
Decimal	Deciaml
Struct	Tuple
List	Array
Map	Map

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

这个页面对您有帮助吗？

有用

无用

ByteHouse云数仓版

Iceberg 数据映射方式 #

费用说明 #

Iceberg on HDFS #

Iceberg on S3 #

Iceberg on HDFS #

手动指定列信息 #

自动推导列信息 #

Iceberg on S3（TOS） #

手动指定列信息 #

自动推导列信息 #

INSERT INTO #

INSERT OVERWRITE #

Iceberg 数据映射方式

费用说明

Iceberg on HDFS

Iceberg on S3

Iceberg on HDFS

手动指定列信息

自动推导列信息

Iceberg on S3（TOS）

手动指定列信息

自动推导列信息

INSERT INTO

INSERT OVERWRITE