通过插件读取 Paimon 表

本文介绍 OceanBase AI 数据库读取 Paimon 格式数据的使用方法、相关配置参数和外表插件机制。Paimon 读取能力以 .so 动态库形式接入，无需将 Paimon SDK 静态编译到 OceanBase AI 数据库中，不改变 OceanBase AI 数据库的部署架构，不影响未使用插件的其他功能，也不引入升级混部兼容性风险。

读取能力概述

OceanBase AI 数据库通过外部 Catalog 访问 Paimon 格式数据，支持创建 Paimon 外部 Catalog，从 Catalog 获取数据库和表信息，并使用 SELECT 语句查询 Paimon 表。查询支持无过滤查询、列裁剪、比较条件、AND 组合条件和 IS NULL 条件，也支持湖表并行裁剪和并行查询。

前提条件

使用 Paimon 读取特性前，应满足以下条件：

1. 每台 OBServer 均已部署 lib_ob_paimon.so。
2. 动态库位于每台 OBServer 的 LD_LIBRARY_PATH、OBServer 同目录或 _ob_additional_lib_path 指定的目录中；也可通过 ext_plugin_config 配置绝对路径。
3. 各 OBServer 的插件配置和动态库布局保持一致，避免部分节点无法加载插件。
4. OceanBase AI 数据库可访问 Paimon Warehouse 对应的文件系统或对象存储路径，并已配置所需访问权限。
5. 当前操作账号具有查看参数、修改参数、创建外部 Catalog 和查询外表所需的权限。

Paimon 插件采用懒加载机制，配置完成并重启 OBServer 后，在首次使用相关功能时自动加载。

配置插件

确认环境满足前提条件后，下一步是配置插件的加载方式。

查看当前配置

SHOW PARAMETERS LIKE 'ext_plugin_config';

默认配置声明加载 Paimon 插件：

[{"name":"paimon"}]

未显式指定 path 时，系统按照 lib_ob_<name>.so 规则解析动态库名称，并在 LD_LIBRARY_PATH或 _ob_additional_lib_path 指定的目录中查找。Paimon 插件对应 lib_ob_paimon.so。

指定插件配置

按默认动态库搜索路径加载 Paimon 插件：

ALTER SYSTEM SET ext_plugin_config = '[{"name":"paimon"}]';

通过绝对路径加载 Paimon 插件：

ALTER SYSTEM SET ext_plugin_config = '[{"name":"paimon","path":"/home/admin/oceanbase/lib/lib_ob_paimon.so"}]';

修改 ext_plugin_config 后，必须重启全部 OBServer。重启完成后，可通过以下语句检查插件加载状态：

SELECT * FROM __all_virtual_ext_plugin_info;

单个插件加载失败时，其他插件仍可正常加载。失败原因可通过该视图的 error_msg 字段和 OBServer 日志查看。

创建外部 Catalog

插件加载成功后，需要创建一个外部 Catalog 作为访问 Paimon 数据的入口。以下示例创建名为 hms_catalog 的 HMS Catalog，通过 Hive Metastore 获取 Paimon 表的元数据：

CREATE EXTERNAL CATALOG IF NOT EXISTS `hms_catalog`
PROPERTIES (
    TYPE = 'HMS',
    URI = 'thrift://hms.example.com:9083'
);

查看数据库和表

Catalog 创建完成后，即可浏览其中的数据库和表。

进入已创建的外部 Catalog 后，可查看其中的数据库：

SHOW DATABASES;

选择目标数据库并查看表：

USE paimon_test_data_db;
SHOW TABLES;

Catalog 和数据库的切换方式应以目标 OceanBase AI 数据库版本支持的客户端语法为准。

查询 Paimon 数据

数据入口建好之后，可以直接用 SQL 查询 Paimon 表中的数据。下面按查询复杂度从低到高给出示例。

无过滤查询

SELECT *
FROM all_primitive_types
LIMIT 1;

AND 和 NULL 条件过滤

SELECT COUNT(*) AS cnt
FROM all_primitive_types
WHERE col_bool IS NULL
  AND col_int IS NULL;

列裁剪和比较条件过滤

SELECT col_bool, col_int, col_string, col_date
FROM all_primitive_types
WHERE col_int = 50000;

查询仅返回指定列，并对 col_int 应用等值过滤。可下推的过滤条件会通过插件谓词接口传递到 Paimon 读取端；无法下推的条件仍由 OceanBase AI 数据库执行，以保证结果正确性。

并行裁剪配置

当查询的表数据量较大时，元数据遍历本身可能成为瓶颈。湖表并行裁剪通过多线程并行处理数据分片和元数据，缩短大表查询的计划生成时间。该能力由租户级参数控制，并由租户级线程池提供执行资源。

启用并行裁剪：

ALTER SYSTEM SET enable_parallel_iceberg_pruning = true;

设置湖表裁剪线程数：

ALTER SYSTEM SET lake_table_pruning_thread_count = 8;

不同版本中并行裁剪开关的命令名称可能存在差异，应以目标版本实际支持的参数名称为准。线程数应根据租户 CPU 和并发负载进行设置，避免裁剪任务占用过多计算资源。

配置参数说明

下表汇总了 Paimon 读取特性涉及的主要配置参数。

外表插件机制

OceanBase AI 数据库采用动态插件机制接入 Paimon、ODPS 等外表能力。外表功能以独立的 .so 动态库形式提供，OceanBase AI 数据库主程序在运行时按需加载，无需将第三方 SDK 静态编译到 OceanBase AI 数据库中。插件化设计的核心优势在于：

• 隔离第三方依赖，避免不同组件之间的库版本冲突。
• 插件独立部署和升级，不影响 OceanBase AI 数据库主程序。
• 未使用的插件不会被加载，不产生额外资源开销。

插件加载流程

插件加载由 ext_plugin_config 参数驱动，整体流程如下：

1. OBServer 启动后，根据 ext_plugin_config 中声明的插件列表，在首次使用外表功能时加载对应的动态库。
2. 加载过程中，系统按插件名称解析动态库路径，并完成版本和接口校验。
3. 加载成功的插件在 OBServer 进程生命周期内常驻，不会被卸载。
4. 单个插件加载失败不影响其他插件的正常使用。

插件名称匹配不区分大小写。插件可根据自身需要继续加载其依赖的动态库，例如 lib_ob_paimon.so 会自动加载 Paimon 读取所需的后续依赖。

插件能力

外表插件为 OceanBase AI 数据库提供以下能力：

ext_plugin_config 配置规则

ext_plugin_config 的值为 JSON 数组，每个元素对应一个外表插件：

[
  {
    "name": "<plugin>",
    "path": "</abs/lib.so>"
  }
]

配置规则如下：

• name 为必填字段，表示插件名称。名称非空、长度不超过 64 个字符，大小写不敏感，内部按小写处理。
• path 为可选字段，表示插件动态库的绝对路径。
• 配置 path 时，系统直接通过该路径加载动态库。
• 未配置 path 或配置为空时，系统按 lib_ob_<name>.so 解析动态库，并从动态库搜索路径中查找。
• 空数组 [] 表示不加载任何外表插件。
• 数组最多包含 256 项。超出限制的条目会被截断并记录日志。
• name 和 path 应符合 JSON 转义规则，例如反斜杠应写为 \\。
• 非法 JSON 或非数组配置会导致本次加载不加载任何插件，并记录错误日志。
• 配置在单个 OBServer 进程生命周期内仅读取一次。运行期间修改参数不会改变已加载的插件集合。
• 单个插件发生 dlopen、dlsym、ABI 校验或文件查找错误时，仅跳过该插件，不影响其他插件。

ext_plugin_config 使用示例

同时声明多个插件：

ALTER SYSTEM SET ext_plugin_config = '[{"name":"paimon"},{"name":"odps","path":"/abs/lib_ob_odps.so"}]';

关闭全部外表插件：

ALTER SYSTEM SET ext_plugin_config = '[]';

上述修改均需重启全部 OBServer 后生效。

注意事项

1. 配置修改需重启生效。 ext_plugin_config 修改后，必须重启全部 OBServer 才能使新配置生效。运行中修改参数不会改变已加载的插件集合。
2. 各节点配置和部署必须保持一致。 插件列表顺序、动态库版本和依赖库布局应在所有 OBServer 上保持一致，否则可能出现查询在部分节点失败的情况。
3. 插件仅提供只读能力。 当前外表插件仅支持读取外部数据，不支持通过插件写入或修改外部数据源。