---
title: "通过插件读取 Paimon 表 - OceanBase AI 数据库 V4.6.2 | OceanBase 文档中心"
description: 通过插件读取 Paimon 表 本文介绍 OceanBase AI 数据库读取 Paimon 格式数据的使用方法、相关配置参数和外表插件机制。Paimon 读取能力以 .so 动态库形式接入，无需将 Paimon SDK 静态编译到 OceanBase AI 数据库中，不改变 OceanBase AI 数据库的部署架…
image: https://mdn.alipayobjects.com/huamei_22khvb/afts/img/A*OSPzQ6GUQF4AAAAAQHAAAAgAeiGDAQ/original
---
切换语言

- 中文站 - 简体中文
- International - English
- 日本站 - 日本語

文档反馈![](https://mdn.alipayobjects.com/huamei_22khvb/afts/img/A*w3cwQYKZAJwAAAAAHhAAAAgAeiGDAQ/original) OceanBase AI 数据库V 4.6.2

# 通过插件读取 Paimon 表

更新时间：2026-09-15 17:00:16

[编辑](https://github.com/oceanbase/oceanbase-database-ai/edit/V4.6.2/zh-CN/300.data-pipeline/200.data-delivery/300.data-lake/200.data-lake-integration/250.data-lake-paimon.md)  

本文介绍 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 后，在首次使用相关功能时自动加载。

## 配置插件

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

### 查看当前配置

```sql
SHOW PARAMETERS LIKE 'ext_plugin_config';

```

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

```json
[{"name":"paimon"}]

```

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

### 指定插件配置

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

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

```

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

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

```

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

```sql
SELECT * FROM __all_virtual_ext_plugin_info;

```

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

## 创建外部 Catalog

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

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

```

## 查看数据库和表

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

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

```sql
SHOW DATABASES;

```

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

```sql
USE paimon_test_data_db;
SHOW TABLES;

```

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

## 查询 Paimon 数据

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

### 无过滤查询

```sql
SELECT *
FROM all_primitive_types
LIMIT 1;

```

### AND 和 NULL 条件过滤

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

```

### 列裁剪和比较条件过滤

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

```

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

## 并行裁剪配置

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

启用并行裁剪：

```sql
ALTER SYSTEM SET enable_parallel_iceberg_pruning = true;

```

设置湖表裁剪线程数：

```sql
ALTER SYSTEM SET lake_table_pruning_thread_count = 8;

```

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

## 配置参数说明

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

| 参数名 | 类型 | 默认值 | 取值范围 | 级别 | 生效方式 | 引入版本 | 说明 |
| --- | --- | --- | --- | --- | --- | --- | --- |
| [`ext_plugin_config`](https://www.oceanbase.com/docs/common-oceanbase-database-ai-1000000007050813) | String | `[{"name":"paimon"}]` | JSON 数组，最多 256 项 | 集群级 | 重启生效 | V4.6.2.1 | 声明需要加载的外表 C++ 格式插件及其动态库位置。 |
| [`enable_lake_table_parallel_resolving`](https://www.oceanbase.com/docs/common-oceanbase-database-ai-1000000007050814) | BOOL | `True` | `True`、`False` | 租户级 | 立即生效 | V4.6.2.1 | 控制是否开启 lake table 并行裁剪。 |
| [`lake_table_pruning_thread_count`](https://www.oceanbase.com/docs/common-oceanbase-database-ai-1000000007050815) | INT | `4` | `[1, 64]` | 租户级 | 立即生效 | V4.6.2.1 | 设置湖表租户级裁剪线程池的线程数量，适用于 Iceberg 和 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 数据库提供以下能力：

| 能力 | 说明 |
| --- | --- |
| 元数据读取 | 从外部数据源获取表结构信息，包括列名、数据类型、精度等属性。 |
| 类型映射 | 自动完成外部数据类型、Arrow 类型与 OceanBase AI 数据库内部类型之间的转换，支持嵌套类型（如 ARRAY、MAP）。 |
| 数据批量读取 | 通过 Arrow C Data Interface 以列式批量方式返回数据，兼顾性能和兼容性。 |
| 谓词下推 | 将查询中的过滤条件传递到插件侧执行，减少数据传输量。支持比较、`IN`、`IS NULL`、`AND`/`OR`/`NOT` 等条件。无法下推的条件由 OceanBase AI 数据库继续执行，保证结果正确性。 |
| 统计信息采集 | 提供表级和列级统计信息（行数、NULL 值数量、不同值数量、最小值、最大值），供查询优化器生成更优的执行计划。 |
| 只读文件访问 | 插件通过 OceanBase AI 数据库提供的文件系统接口访问外部存储，仅支持读取操作。 |

### ext_plugin_config 配置规则

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

```json
[
  {
    "name": "&lt;plugin&gt;",
    "path": "&lt;/abs/lib.so&gt;"
  }
]

```

配置规则如下：

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

### ext_plugin_config 使用示例

同时声明多个插件：

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

```

关闭全部外表插件：

```sql
ALTER SYSTEM SET ext_plugin_config = '[]';

```

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

### 注意事项

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

 上一篇 下一篇 ![有帮助](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*y6ocSqN8cqsAAAAAAAAAAAAAARQnAQ)![无帮助](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*BG9IQJyLHF8AAAAAAAAAAAAAARQnAQ)![反馈](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*eTWdQKCRKHwAAAAAAAAAAAAAARQnAQ)[AI](https://www.oceanbase.com/obi) 咨询热线