> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Paimon 表引擎

> 该引擎以只读方式集成现有 Apache Paimon 表，这些表可存储在亚马逊 S3、Azure、HDFS 或本地。

该引擎以只读方式集成现有 Apache [Paimon](https://paimon.apache.org/) 表，这些表可存储在亚马逊 S3、Azure、HDFS 或本地。
它支持快照读取、增量读取，以及由该引擎提供的基础分区裁剪。

## 创建表

请注意，Paimon 表必须已存在于存储中；此命令不接受用于创建新表的 DDL 参数。
创建 `Paimon*` 表受 `allow_experimental_paimon_storage_engine` 控制 (默认禁用) ，因此请先启用它，再运行 `CREATE TABLE`。

```sql theme={null}
SET allow_experimental_paimon_storage_engine = 1;

CREATE TABLE paimon_table_s3
    ENGINE = PaimonS3(url, [, access_key_id, secret_access_key] [,format] [,compression])

CREATE TABLE paimon_table_azure
    ENGINE = PaimonAzure(connection_string|storage_account_url, container_name, blobpath, [,account_name], [,account_key] [,format] [,compression_method])

CREATE TABLE paimon_table_hdfs
    ENGINE = PaimonHDFS(path_to_table, [,format] [,compression_method])

CREATE TABLE paimon_table_local
    ENGINE = PaimonLocal(path_to_table, [,format] [,compression_method])
```

## 引擎参数

这些参数的说明分别与 `S3`、`AzureBlobStorage`、`HDFS` 和 `File` 表引擎中的参数说明一致。
`format` 表示 Paimon 表中数据文件的格式。

可以通过 [命名集合](https://clickhouse.com/docs/zh/concepts/features/configuration/server-config/named-collections.md) 指定引擎参数

### 示例

```sql theme={null}
CREATE TABLE paimon_table ENGINE=PaimonS3('http://test.s3.amazonaws.com/clickhouse-bucket/test_table', 'test', 'test')
```

使用命名集合：

```xml theme={null}
<clickhouse>
    <named_collections>
        <paimon_conf>
            <url>http://test.s3.amazonaws.com/clickhouse-bucket/</url>
            <access_key_id>test</access_key_id>
            <secret_access_key>test</secret_access_key>
        </paimon_conf>
    </named_collections>
</clickhouse>
```

```sql theme={null}
CREATE TABLE paimon_table ENGINE=PaimonS3(paimon_conf, filename = 'test_table')
```

## 功能

* 从最新的表快照读取。
* 启用时，可基于已提交的快照 ID 进行增量读取。
* 启用 `use_paimon_partition_pruning` 时支持分区裁剪。
* 配置后可选择在后台刷新元数据。
* 使用 Atomic/Replicated 数据库时，表 UUID 会保持稳定，因此可在 Keeper 路径中使用 `{uuid}` 宏。

## 主键表

由于尚未实现读时合并 (merge-on-read) ，**无法读取主键表**：读取器返回的是该快照所有数据文件的原始并集，其中仍包含已被后续 upsert 取代的旧版本行。因此，读取 schema 中声明了 `primary-key` 的表时会抛出异常。

## 带有删除向量的表

删除向量不会被应用，因此**无法读取带有删除向量的快照**：否则结果中仍会
包含后续 `DELETE` 和 `UPDATE` 语句已删除的行。因此，如果某个快照的 index manifest 中列出了
删除向量，读取该快照时会抛出异常，即使已关闭 `deletion-vectors.enabled` 也是如此。

在 Paimon 中执行一次完整合并整理 (`compact_strategy => 'full'`) 会应用删除向量，此后
创建的快照即可再次读取。

增量读取会在第一个尚未消费且带有删除向量的快照处停止，即使之后执行了完整合并整理，也仍会停在该处，
因为截至该次合并整理的每个快照都列出了相同的删除向量。此时游标不会前移。
只有当 Paimon 使这些快照过期，或者将游标移动到完整合并整理对应的快照以放弃这些快照后，读取才会恢复；
后一种方式会删除截至该快照的所有尚未消费的快照 (参见
[快照无法读取时](#when-a-snapshot-cannot-be-read)) ：

```bash theme={null}
clickhouse-keeper-client -q "set '<paimon_keeper_path>/committed_snapshot' '<snapshot id of the full compaction>'"
```

无论哪种情况，这些删除向量所删除的行，仍会保留在增量读取此前已输出的数据中。

## 设置

该引擎使用与相应对象存储引擎相同的设置，并额外提供了 Paimon 特有的设置：

* `allow_experimental_paimon_storage_engine` — 启用创建 `Paimon`、`PaimonS3`、`PaimonAzure`、`PaimonHDFS` 和 `PaimonLocal` 表引擎。默认值：`0` (禁用) 。
* `use_paimon_metadata_files_cache` — 启用 Paimon 元数据文件缓存 (缓存已反序列化的 manifest 列表和 manifest) 。设置为 `1` 表示启用，`0` 表示禁用。默认值：`0`。该设置在表函数和持久表引擎中的生效方式不同——请参见下方说明。
* `paimon_incremental_read` — 启用增量读取模式。
* `paimon_metadata_refresh_interval_sec` — 后台元数据刷新间隔 (单位：秒) 。当设置为大于 0 的值时，后台任务会定期从对象存储拉取最新的快照和 schema。默认值：30。
* `paimon_keeper_path` — 增量读取状态对应的 Keeper 路径。必须设置，且每个表唯一；支持 `{database}`、`{table}`、`{uuid}` 等宏。
* `paimon_replica_name` — 增量读取状态对应的副本名称。必须设置，且每个副本唯一；支持 `{replica}` 等宏。

示例 (启用 Experimental Paimon 引擎和元数据文件缓存) ：

```sql theme={null}
SET allow_experimental_paimon_storage_engine = 1;
SET use_paimon_metadata_files_cache = 1;

CREATE TABLE paimon_cached
ENGINE = PaimonS3(paimon_conf, filename = 'paimon_all_types');
```

> [!NOTE]
>
> `use_paimon_metadata_files_cache` 的生效方式取决于访问 Paimon 表的方式：
>
> * **表函数** (例如 `SELECT ... FROM paimonS3(...)`) ：缓存决策会按每个查询分别评估，因此你可以直接在 `SELECT` 中传入 `SETTINGS use_paimon_metadata_files_cache = 1`。
> * **持久表引擎** (`PaimonS3`、`PaimonAzure`、`PaimonHDFS`、`PaimonLocal` 以及 `Paimon` 别名) ：缓存决策只会在表元数据初始化时锁定一次，并存储在不可变的持久组件中；元数据更新路径刻意不会重新读取该设置。因此，对于已初始化的持久表，在 `SELECT` 中传入 `SETTINGS use_paimon_metadata_files_cache = 1` 不会产生任何效果——系统仍会继续使用先前锁定的决策。要更改它，请在表元数据初始化之前设置 `use_paimon_metadata_files_cache`，或者先对该表执行 `DROP`，再使用所需值重新 `CREATE`。
>
> 服务器级缓存容量 (`paimon_metadata_files_cache_size`) *不会*被锁定：它是一个运行时设置，可以通过 `SYSTEM RELOAD CONFIG` 更改，并且即使对于已初始化的表也会立即生效。

## 增量读取示例

基于 Keeper 状态的增量读取：

```sql theme={null}
CREATE TABLE paimon_inc
ENGINE = PaimonS3(paimon_conf, filename = 'paimon_all_types')
SETTINGS
    paimon_incremental_read = 1,
    paimon_keeper_path = '/clickhouse/{database}/{uuid}',
    paimon_replica_name = '{replica}';
```

### 增量读取的查询级设置

以下设置属于**查询级** (通过 `SELECT ... SETTINGS` 传递，而不是在 `CREATE TABLE` 中设置) 。它们用于控制增量读取在每次查询中的行为：

* `paimon_target_snapshot_id` — 仅读取指定快照的增量。Keeper 中已提交的 watermark **不会**推进，因此同一个快照可以重复读取任意次数。默认值：`-1` (禁用) 。
* `max_consume_snapshots` — 单次增量读取可消费的快照数量上限。当源端累积了大量尚未读取的快照时，该参数会限制每次查询消费的数量，以控制批次大小。`0` 表示不限制。默认值：`0`。

**定向快照读取** — 无论当前 watermark 如何，始终返回快照 1 的增量：

```sql theme={null}
SELECT count()
FROM paimon_inc
SETTINGS paimon_target_snapshot_id = 1;
```

**限制每个批次的快照数** — 如果有三个新快照待处理，则每次查询最多消费两个：

```sql theme={null}
SELECT count()
FROM paimon_inc
SETTINGS max_consume_snapshots = 2;
```

### 回退仓库

位于 `paimon_keeper_path` 的 Keeper 游标记录了 stream 已消费到的位置，而增量读取的前提是仓库只会向前推进——Paimon 快照 id 单调递增，且永不复用。清理过期的旧快照没有问题：这只是移除一段前缀，其后的 id 不受影响。

而将仓库*向后*回退则会打破这一前提。从较旧的备份恢复仓库、使用其他引擎回滚仓库，或在同一路径下删除并重建 Paimon 表，都会导致快照 id 回退，随后写入器会复用游标已经消费过的 id。

**回退仓库时，必须在同一操作中重置游标。** 一旦 id 被复用，ClickHouse 就无法还原消费者已接收过哪些快照，因此如果回退后游标未被重置，数据投递行为将是未定义的：位于复用 id 上的快照可能会被跳过。

如果回退后游标指向的位置超出了仓库的最新快照，读取将以 `INVALID_STATE` 失败，而不是报告没有新数据，同时错误信息中会给出用于恢复的命令。此时不会读取任何数据，游标也保持不变，因此在问题解决之前，后续每次轮询都会以同样的方式失败：

```
clickhouse-keeper-client -q "set '<paimon_keeper_path>/committed_snapshot' '<latest snapshot id>'"
```

不要通过删除 `committed_snapshot` 节点来进行恢复。游标不存在意味着“从未消费过”，这会导致下一次读取对整张表进行完整重读，而不是从断点继续。

在重置游标之前，请暂停所有共享 `paimon_keeper_path` 的消费者 (包括可刷新materialized view) ，并等待所有在传输中的读取完成。

每次读取的提交都以其所观察到的游标为前提。如果游标在观察之后、提交之前发生了变化，该读取将以 `INVALID_STATE` 失败，不会交付任何数据，并保留您设置的值。已经提交的读取在游标重置后仍可能交付其批次；此时若回退游标，可能导致该批次被重复交付。

不要手动删除或替换 `processing_lock`。它是由正在执行增量读取的 ClickHouse Keeper 会话所持有的临时节点；其生命周期并非供运维人员执行恢复操作的接口。

### 当快照无法读取时

已被 Paimon 过期的快照会被自动跳过：过期操作会移除快照 ID 的一段前缀，因此凡是早于该仓库最早快照的快照，都可以确定已不存在，游标会直接越过它们。

读取快照时发生的其他任何失败 (例如暂时性的对象存储错误或已损坏的快照文件) 都会导致查询失败，游标则保持原位。系统有意不提供容忍此类失败的设置。跳过未读取的快照意味着永久丢弃其中已提交的数据，而常驻的“容忍错误”开关会让今后的每一次网络抖动都悄无声息地造成数据丢失。由于游标保持不变，暂时性错误完全无需人工干预：下一次轮询会重新读取同一范围并顺利完成。

如果某个快照确实无法读取，而 stream 又必须继续推进，请显式放弃该快照。错误消息中会给出相应的命令，但请注意其代价：失败的读取没有返回任何数据，因此将游标移动到无法读取的快照，会放弃截至该快照 (含该快照) 的**所有**尚未消费的快照，而不仅仅是那个无法读取的快照。

假设游标位于 1，快照 2、3、4 处于待处理状态，其中快照 3 无法读取：

```bash theme={null}
# Abandons snapshots 2 and 3; the next read resumes at 4.
clickhouse-keeper-client -q "set '/clickhouse/tables/<uuid>/committed_snapshot' '3'"
```

如需保留可读取的快照，请先排空到无法读取的快照为止。每次轮询会消费一个快照并推进游标，直到抵达无法读取的那个快照：

```sql theme={null}
-- Delivers snapshot 2 and advances the cursor to 2; the next poll fails on 3 again.
SELECT * FROM paimon_inc SETTINGS max_consume_snapshots = 1;
```

```bash theme={null}
# Now only snapshot 3 is abandoned.
clickhouse-keeper-client -q "set '/clickhouse/tables/<uuid>/committed_snapshot' '3'"
```

无论哪种情况，该决定都会作为运维人员的一次显式操作记录下来，而不是根据某项设置推断得出。

## 通过可刷新materialized view 将 Paimon 同步到 MergeTree

你可以构建一条端到端管道，使用 `APPEND` 模式的可刷新materialized view，持续将数据从 Paimon 表同步到 MergeTree 表。每个刷新周期只会从 Paimon 读取新增的增量数据，并将其追加到目标表。

**步骤 1 — 创建启用了增量读取和元数据刷新的 Paimon 源表。**

下面的示例使用 `PaimonLocal`。请根据你的存储后端，将 引擎 替换为 `PaimonS3`、`PaimonAzure`、`PaimonHDFS`，或可自动检测的 `Paimon` 引擎：

```sql theme={null}
SET allow_experimental_paimon_storage_engine = 1;

-- Local storage
CREATE TABLE paimon_mv_source
ENGINE = PaimonLocal('/path/to/paimon/table')
SETTINGS
    paimon_incremental_read = 1,
    paimon_keeper_path = '/clickhouse/tables/{uuid}',
    paimon_replica_name = '{replica}',
    paimon_metadata_refresh_interval_sec = 1;

-- S3 storage (the `Paimon` engine defaults to the S3 implementation when no `disk` is specified)
CREATE TABLE paimon_mv_source
ENGINE = Paimon('http://minio:9000/bucket/path/to/table', 'access_key', 'secret_key')
SETTINGS
    paimon_incremental_read = 1,
    paimon_keeper_path = '/clickhouse/tables/{uuid}',
    paimon_replica_name = '{replica}',
    paimon_metadata_refresh_interval_sec = 1;
```

`paimon_metadata_refresh_interval_sec` 用于设置后台元数据刷新间隔 (以秒为单位) 。当该值大于 0 时，后台任务会定期从对象存储中拉取最新的快照和 schema，这样 MV 的刷新周期无需等待查询触发元数据更新，就能看到新提交的数据。默认值为 30。在大量表上启用时请谨慎，以避免对象存储和 Keeper I/O 开销过大。

**步骤 2 — 创建 MergeTree 目标表 (schema 克隆自 Paimon 表) ：**

```sql theme={null}
CREATE TABLE paimon_mv_dest AS paimon_mv_source
ENGINE = MergeTree()
ORDER BY tuple();
```

**步骤 3 — 创建可刷新 materialized view：**

```sql theme={null}
CREATE MATERIALIZED VIEW paimon_mv
REFRESH EVERY 10 SECOND
APPEND
TO paimon_mv_dest
AS SELECT * FROM paimon_mv_source;
```

MV 每 10 秒执行一次 `SELECT * FROM paimon_mv_source`，该查询只会返回自上一个已提交快照以来新增的行，并将其追加到 `paimon_mv_dest`。

**清理：**

```sql theme={null}
SYSTEM STOP VIEW paimon_mv;
DROP VIEW IF EXISTS paimon_mv SYNC;
DROP TABLE IF EXISTS paimon_mv_dest SYNC;
DROP TABLE IF EXISTS paimon_mv_source SYNC;
```

> [!NOTE]
>
> 删除 MV 前请先将其停止，以免后台刷新阻塞 DDL 操作。

## 限制

* 增量读取要求已配置 Keeper (ZooKeeper) 。
* 增量读取要求设置 `paimon_keeper_path`，且每个表的该值必须唯一。
* 在同一 Keeper 路径下，`paimon_replica_name` 对每个副本都必须唯一。
* 增量读取采用至多一次投递语义：已提交快照会在收集数据文件时向前推进，此时数据实际上尚未被消费。如果查询在文件收集后失败，重试时不会重新读取这些被跳过的快照。
* 该表引擎为只读；不支持修改数据。
* 增量读取不会处理来自 Paimon 源端的历史数据删除。如果上游 Paimon 数据被删除或更新，已写入 ClickHouse MergeTree 目标表的对应行不会被自动删除。你必须在 MergeTree 表上手动执行 `ALTER TABLE ... DELETE` 来清理过时数据。
* 如果底层 Paimon 表在同一对象存储路径下被删除并重新创建 (例如通过 Flink 或 Spark) ，你必须对相应的 ClickHouse 表执行 `DROP` 并重新 `CREATE`。ClickHouse 会通过比较 schema-0 的创建时间戳来检测这种重建，并报错；在重新创建之前，这个过时的 ClickHouse 表无法使用。

## 别名

`Paimon` 表引擎会根据 `disk` 设置自动检测存储后端，并相应分派到 `PaimonS3`、`PaimonAzure` 或 `PaimonLocal`。如果未指定 `disk`，则默认使用 `PaimonS3` 实现。

## 虚拟列

* `_path` — 文件路径。类型：`LowCardinality(String)`。
* `_file` — 文件名。类型：`LowCardinality(String)`。
* `_size` — 文件大小 (以字节为单位) 。类型：`Nullable(UInt64)`。如果文件大小未知，则值为 `NULL`。
* `_time` — 文件的最后修改时间。类型：`Nullable(DateTime)`。如果时间未知，则值为 `NULL`。
* `_etag` — 文件的 etag。类型：`LowCardinality(String)`。如果 etag 未知，则值为 `NULL`。

## 支持的数据类型

| Paimon 数据类型 | ClickHouse 数据类型 |
| - | - |
| BOOLEAN | Bool |
| TINYINT | Int8 |
| SMALLINT | Int16 |
| INTEGER | Int32 |
| BIGINT | Int64 |
| FLOAT | Float32 |
| DOUBLE | Float64 |
| STRING,VARCHAR,BYTES,VARBINARY | String |
| DATE | Date |
| TIME(p),TIME | Time('UTC') |
| TIMESTAMP(p) WITH LOCAL TIME ZONE | DateTime64 |
| TIMESTAMP(p) | DateTime64('UTC') |
| CHAR | FixedString(1) |
| BINARY(n) | FixedString(n) |
| DECIMAL(P,S) | Decimal(P,S) |
| ARRAY | Array |
| MAP | Map |

## 支持的分区键

Paimon 分区键支持的数据类型：

* `CHAR`
* `VARCHAR`
* `BOOLEAN`
* `DECIMAL`
* `TINYINT`
* `SMALLINT`
* `INTEGER`
* `DATE`
* `TIME`
* `TIMESTAMP`
* `TIMESTAMP WITH LOCAL TIME ZONE`
* `BIGINT`
* `FLOAT`
* `DOUBLE`
