Bytehouse 云数仓版支持接入 Iceberg Catalog，您无需手动创建外部数据库、表，可通过 Iceberg Catalog 直接查询 Iceberg 中的数据。本文将介绍如何创建和使用 Iceberg Catalog。

Iceberg 支持多种不同的元数据存储形式，包括以下形式：

• 自包含的形式存储在存储介质（如 S3 兼容对象存储服务）
• 开源的 Hive metastore
• 火山引擎 AI 数据湖服务 LAS

ByteHouse Iceberg 外部 Catalog 当前支持的 Iceberg 元数据存储形式包括 S3 兼容对象存储服务和 LAS，Iceberg 外部 Catalog 创建方式随使用的元数据存储服务不同而有所差异，您可根据实际使用的服务选择对应的创建方式。

请根据您的 Iceberg 集群使用的元数据存储形式获取以下权限和连接信息。

• 暂不支持在 Iceberg Catalog 内手动新增数据库、表，以及相关的 ALTER 操作。
• Iceberg Catalog 要求 ByteHouse 引擎版本为 2.3.2.0 及以上。使用前请确认您的引擎版本满足此要求，可通过 ByteHouse 控制台的租户管理 > 基本信息页面查看当前引擎版本。如果您的引擎版本不符合要求，可提交工单，联系 ByteHouse 团队升级引擎。

Iceberg 使用的元数据服务不同，对应的参数配置也会不同。本节将按元数据服务的类型，介绍 Iceberg Catalog 的创建方法。

S3 #

CREATE EXTERNAL CATALOG `{catalogName}`
PROPERTIES type='iceberg',
metastore_type='hadoop', 
warehouse='{warehouse}', 
endpoint='{endpoint}', 
ak_id='{accessKey}', 
ak_secret='{accessSecretKey}';

LAS #

CREATE EXTERNAL CATALOG `{catalogName}` 
PROPERTIES
type='iceberg',
metastore_type='lf',
endpoint='{endpoint}', 
ak_id='{accessKey}', 
ak_secret='{accessSecretKey}', 
lf_metastore_ak_id='{lasAccessKey}',
lf_metastore_ak_secret='{lasAccessSecretKey}',
lf_metastore_catalog='{lasCatalogName}',
lf_metastore_region='{lasEndpoint}',
lf_metastore_url = '{lasUri}';

假设您已经创建了一个名为 iceberg_s3 的外部 Catalog。

查看 Iceberg Catalog #

查看所有 Catalog，将列出所有已创建的外部 Catalog。

SHOW EXTERNAL CATALOGS;

查看某个 Catalog 的 Schema 信息。

SHOW CREATE EXTERNAL CATALOG catalog_name;

查询 Iceberg Catalog 中的表 #

用户可以通过 catalog_name.db_name.table_name 这种三段式命名方式直接访问 Iceberg Catalog 中的表，例如

SELECT * FROM iceberg_s3.iceberg_db_name.iceberg_table_name;

ByteHouse 原生的 CnchMergeTree 表也可以用如下 SQL 访问。其中，cnch（cloud-native-clickhouse 的缩写）被用作了 Bytehouse CDW 默认 Catalog 的名字。

SELECT * FROM cnch.cnch_db_name.cnch_db_name;
-- 等同于 SELECT * FROM cnch_db_name.cnch_db_name; 

跨 Catalog 查询 #

利用外部 Catalog，您可以直接将 Iceberg 外表和 ByteHouse 的 CnchMergeTree 表做 join。

SELECT * FROM iceberg_s3.iceberg_db.iceberg_table 
UNION ALL 
SELECT (1) FROM cnch.cnch_db.cnch_table;

列出 Iceberg Catalog 中的数据库、表 #

列出 Iceberg Catalog 中的数据库名。

SHOW DATABASES FROM catalog_name;

列出数据库中的表名。

SHOW TABLES FROM catalog_name.database_name;

获取表的创建语句。

SHOW CREATE TABLE catalog_name.database_name.table_name;

Switch Catalog #

您可以使用如下 SQL 来改变默认的 Catalog，执行后，后续查询会默认使用该 Catalog 下的数据库和表：

SWITCH CATALOG catalog_name;

此时再运行查询语句，ByteHouse 会从 Iceberg Catalog 下的指定的数据库、表中读取数据。

SELECT * FROM iceberg_db.iceberg_table;

如果需切换回 ByteHouse 默认的 Catalog，您可以使用以下任意一条命令：

# 方式 1
SWITCH CATALOG default;

# 方式 2
SWITCH CATALOG cnch;

您也可以使用以下命令，直接将默认的数据库切换到 Iceberg Catalog 下的指定数据库：

USE iceberg_s3.iceberg_db;

如需切换回 ByteHouse 内表，可使用以下命令：

USE cnch.cnch_database_name;

查询当前使用的 Catalog #

您可通过 currentCatalog() 函数查询当前 Catalog。

SELECT currentCatalog();

查询 Iceberg Catalog 元信息 #

您可通过以下语句查询 Iceberg Catalog 中的数据库、表、分区的元信息，包括数据库名称、存储路径、属性等信息。

• 查询 Iceberg Catalog 中数据库表的元信息

  SELECT * FROM catalog_name.database_name.table_name$metadata$properties
  

• 查询 Iceberg Catalog 中数据表的分区的元信息

  SELECT * FROM {catalog_name.}database_name.table_name$metadata$partitions
  

删除 Iceberg Catalog #

您可以使用如下命令删除 Iceberg Catalog。

DROP EXTERNAL CATALOG [IF EXISTS] catalog_name;

通过 ByteHouse 云数仓版控制台使用 Iceberg Catalog #

ByteHouse 云数仓版也支持通过 ByteHouse 云数仓版控制台创建和使用 Iceberg Catalog，详情请参见管理外部 Catalog。

使用 Iceberg 外表 #

除了通过 Iceberg Catalog 访问 Iceberg 数据外，ByteHouse 也支持通过外表方式查询、写入 Iceberg 数据，详情请参见 Iceberg 外表。