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

Paimon 的数据支持通过自包含的形式存储在存储介质上，ByteHouse 访问 Paimon 集群时，需具备对存储介质的访问权限。当前 ByteHouse 支持存储在 S3 兼容对象存储服务中的 Paimon 数据。
请根据您的 Paimon 集群使用的 S3 兼容对象存储获取以下权限和连接信息。

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

本节将介绍如何创建存储在 S3 兼容对象存储上的 Paimon Catalog。

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

查看您创建的所有 Catalog。

SHOW EXTERNAL CATALOGS;

查看指定 Catalog 的 Schema 信息。

SHOW CREATE EXTERNAL CATALOG your_catalog_name;

假设您已经创建了一个名为 paimon_s3 的外部 Catalog，您可通过以下命令查询该 Catalog 中的数据。

查询 Paimon Catalog 中的表 #

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

SELECT * FROM paimon_catalog.paimon_db_name.paimon_table_name;

您也可以使用该方式访问 ByteHouse 云数仓版原生的 CnchMergeTree 表。其中，cnch（cloud-native-clickhouse 的缩写）为 ByteHouse 云数仓版默认 Catalog 的名字。

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

跨 Catalog 查询 #

利用外部 Catalog，您可以直接将 Paimon 外表和 ByteHouse 的 CnchMergeTree 表实现联合查询（如 UNION ALL 操作）。

SELECT * FROM paimon_s3.paimon_db.paimon_table
UNION ALL
SELECT (1) FROM cnch.cnch_db.cnch_table;

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

列出 Catalog 中的数据库名。

SHOW DATABASES FROM catalog_name;

列出数据库中的表名。

SHOW TABLES FROM catalog_name.database_name;

获取表的创建语句。

SHOW CREATE TABLE catalog_name.database_name.table_name;

切换 Catalog #

您可以使用如下 SQL 来切换查询的 Catalog：

SWITCH CATALOG catalog_name;

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

SELECT * FROM paimon_db.paimon_table;

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

# 方式 1
SWITCH CATALOG default;

# 方式 2
SWITCH CATALOG cnch;

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

USE paimon_s3.paimon_db;

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

USE cnch.cnch_database_name;

查询当前使用的 Catalog #

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

SELECT currentCatalog();

查询 Paimon Catalog 元信息 #

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

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

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

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

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

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

DROP EXTERNAL CATALOG [IF EXISTS] catalog_name;

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

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

使用 Paimon 外表 #

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