创建表
请注意,Paimon 表必须已存在于存储中;此命令不接受用于创建新表的 DDL 参数。 创建Paimon* 表受 allow_experimental_paimon_storage_engine 控制 (默认禁用) ,因此请先启用它,再运行 CREATE TABLE。
引擎参数
这些参数的说明分别与S3、AzureBlobStorage、HDFS 和 File 表引擎中的参数说明一致。
format 表示 Paimon 表中数据文件的格式。
可以通过 命名集合 指定引擎参数
示例
功能
- 从最新的表快照读取。
- 启用时,可基于已提交的快照 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 使这些快照过期,或者将游标移动到完整合并整理对应的快照以放弃这些快照后,读取才会恢复;
后一种方式会删除截至该快照的所有尚未消费的快照 (参见
快照无法读取时) :
设置
该引擎使用与相应对象存储引擎相同的设置,并额外提供了 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}等宏。
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 状态的增量读取:增量读取的查询级设置
以下设置属于查询级 (通过SELECT ... SETTINGS 传递,而不是在 CREATE TABLE 中设置) 。它们用于控制增量读取在每次查询中的行为:
paimon_target_snapshot_id— 仅读取指定快照的增量。Keeper 中已提交的 watermark 不会推进,因此同一个快照可以重复读取任意次数。默认值:-1(禁用) 。max_consume_snapshots— 单次增量读取可消费的快照数量上限。当源端累积了大量尚未读取的快照时,该参数会限制每次查询消费的数量,以控制批次大小。0表示不限制。默认值:0。
回退仓库
位于paimon_keeper_path 的 Keeper 游标记录了 stream 已消费到的位置,而增量读取的前提是仓库只会向前推进——Paimon 快照 id 单调递增,且永不复用。清理过期的旧快照没有问题:这只是移除一段前缀,其后的 id 不受影响。
而将仓库向后回退则会打破这一前提。从较旧的备份恢复仓库、使用其他引擎回滚仓库,或在同一路径下删除并重建 Paimon 表,都会导致快照 id 回退,随后写入器会复用游标已经消费过的 id。
回退仓库时,必须在同一操作中重置游标。 一旦 id 被复用,ClickHouse 就无法还原消费者已接收过哪些快照,因此如果回退后游标未被重置,数据投递行为将是未定义的:位于复用 id 上的快照可能会被跳过。
如果回退后游标指向的位置超出了仓库的最新快照,读取将以 INVALID_STATE 失败,而不是报告没有新数据,同时错误信息中会给出用于恢复的命令。此时不会读取任何数据,游标也保持不变,因此在问题解决之前,后续每次轮询都会以同样的方式失败:
committed_snapshot 节点来进行恢复。游标不存在意味着“从未消费过”,这会导致下一次读取对整张表进行完整重读,而不是从断点继续。
在重置游标之前,请暂停所有共享 paimon_keeper_path 的消费者 (包括可刷新materialized view) ,并等待所有在传输中的读取完成。
每次读取的提交都以其所观察到的游标为前提。如果游标在观察之后、提交之前发生了变化,该读取将以 INVALID_STATE 失败,不会交付任何数据,并保留您设置的值。已经提交的读取在游标重置后仍可能交付其批次;此时若回退游标,可能导致该批次被重复交付。
不要手动删除或替换 processing_lock。它是由正在执行增量读取的 ClickHouse Keeper 会话所持有的临时节点;其生命周期并非供运维人员执行恢复操作的接口。
当快照无法读取时
已被 Paimon 过期的快照会被自动跳过:过期操作会移除快照 ID 的一段前缀,因此凡是早于该仓库最早快照的快照,都可以确定已不存在,游标会直接越过它们。 读取快照时发生的其他任何失败 (例如暂时性的对象存储错误或已损坏的快照文件) 都会导致查询失败,游标则保持原位。系统有意不提供容忍此类失败的设置。跳过未读取的快照意味着永久丢弃其中已提交的数据,而常驻的“容忍错误”开关会让今后的每一次网络抖动都悄无声息地造成数据丢失。由于游标保持不变,暂时性错误完全无需人工干预:下一次轮询会重新读取同一范围并顺利完成。 如果某个快照确实无法读取,而 stream 又必须继续推进,请显式放弃该快照。错误消息中会给出相应的命令,但请注意其代价:失败的读取没有返回任何数据,因此将游标移动到无法读取的快照,会放弃截至该快照 (含该快照) 的所有尚未消费的快照,而不仅仅是那个无法读取的快照。 假设游标位于 1,快照 2、3、4 处于待处理状态,其中快照 3 无法读取:通过可刷新materialized view 将 Paimon 同步到 MergeTree
你可以构建一条端到端管道,使用APPEND 模式的可刷新materialized view,持续将数据从 Paimon 表同步到 MergeTree 表。每个刷新周期只会从 Paimon 读取新增的增量数据,并将其追加到目标表。
步骤 1 — 创建启用了增量读取和元数据刷新的 Paimon 源表。
下面的示例使用 PaimonLocal。请根据你的存储后端,将 引擎 替换为 PaimonS3、PaimonAzure、PaimonHDFS,或可自动检测的 Paimon 引擎:
paimon_metadata_refresh_interval_sec 用于设置后台元数据刷新间隔 (以秒为单位) 。当该值大于 0 时,后台任务会定期从对象存储中拉取最新的快照和 schema,这样 MV 的刷新周期无需等待查询触发元数据更新,就能看到新提交的数据。默认值为 30。在大量表上启用时请谨慎,以避免对象存储和 Keeper I/O 开销过大。
步骤 2 — 创建 MergeTree 目标表 (schema 克隆自 Paimon 表) :
SELECT * FROM paimon_mv_source,该查询只会返回自上一个已提交快照以来新增的行,并将其追加到 paimon_mv_dest。
清理:
删除 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 分区键支持的数据类型:CHARVARCHARBOOLEANDECIMALTINYINTSMALLINTINTEGERDATETIMETIMESTAMPTIMESTAMP WITH LOCAL TIME ZONEBIGINTFLOATDOUBLE