关于paimon-rust 数据写入链路

0 阅读17分钟

关于 paimon-rust 源码学习

本文基于 paimon-rust 源码整理,涵盖写入时序、Catalog / Database / Table 的创建与获取,以及两阶段提交的核心机制。

一、写入时序图

sequenceDiagram
    participant Caller as 调用方
    participant Cat as Catalog/FS
    participant Tbl as Table
    participant WB as WriteBuilder
    participant TW as TableWrite
    participant TC as TableCommit
    participant IO as FileIO/Parquet

    Note over Caller,IO: ① 准备阶段:Catalog 与表

    Caller->>Cat: create_catalog(warehouse)
    Note over Cat: FileSystemCatalog::new<br/>读 warehouse、构建 FileIO
    Cat-->>Caller: Catalog

    Caller->>Cat: create_database(&#34;my_db&#34;, true, {})
    Cat->>IO: mkdirs my_db.db/
    Cat-->>Caller: Ok

    Caller->>Caller: Schema::builder()<br/>.column(...)×5<br/>.build()

    Caller->>Cat: get_table(identifier)
    Cat->>IO: table_exists? (schema-0?)
    IO-->>Cat: false
    Cat-->>Caller: Err(TableNotExist)

    Caller->>Cat: create_table(identifier, schema, false)
    Cat->>IO: mkdirs table/
    Cat->>IO: write schema/schema-0
    Cat-->>Caller: Ok

    Caller->>Cat: get_table(identifier)
    Cat->>IO: load_latest_schema
    Cat->>Tbl: build_table
    Cat-->>Caller: Table

    Note over Caller,IO: ② 构造写入器与提交句柄

    Caller->>Tbl: new_write_builder()
    Tbl-->>Caller: WriteBuilder

    Caller->>WB: new_commit()
    WB->>TC: 构造 TableCommit
    TC-->>Caller: txn

    Caller->>WB: new_write()
    WB->>TW: 构造 TableWrite
    TW-->>Caller: writer

    Note over Caller,IO: ③ 写数据(数据文件落盘但不可见)

    Caller->>TW: write_arrow_batch(batch)
    Note over TW: 按分区/桶路由<br/>缓冲行数据<br/>达阈值后编码
    TW->>IO: 写 Parquet 数据文件
    Note over IO: 文件已存在<br/>但未被任何 Snapshot 引用
    TW-->>Caller: Ok

    Note over Caller,IO: ④ 两阶段提交

    Caller->>TW: prepare_commit()
    Note over TW: flush 残余缓冲<br/>收尾所有 writer<br/>生成 CommitMessage
    TW-->>Caller: msg

    Caller->>TC: commit(msg)
    Note over TC: 读最新快照<br/>乐观并发冲突检测<br/>构造新 Snapshot
    TC->>IO: 原子发布 snapshot-N (PutIfAbsent)
    Note over IO: 新快照出现<br/>数据文件瞬间可见
    TC-->>Caller: Ok

    Note over Caller,IO: 作用域结束时 writer / txn 自动释放

时序图说明

1. 准备阶段:Catalog、Database、Table
  • create_catalog 创建 Catalog,底层调用 FileSystemCatalog::new(options),根据 warehouse 路径构造 FileIO,最终得到 warehouse 内容并保留完整的 options;

  • create_database("database", true, ...) 在 warehouse 下创建 my_db.db/ 目录;

  • create_table 创建 table,不过该操作并不是原子性操作,分为两步来完成:先 mkdirs 建表目录,接着将序列化 Schema 写入 schema/schema-0。

    若是在创建 table 过程中目录创建成功,而并未完成 schema 写入,这意味着该 table 并未创建成功;在 get_table 探测其存在性时,就是以 schema 文件而非目录作为凭证的。

2. 构造写入器:Table.new_write_builder → WriteBuilder
  • TableCommit:WriteBuilder.new_commit()
  • TableWrite:WriteBuilder.new_write()

get_table 通过 fetch_table_schema 加载最新 schema 来 build_table,构造出持有 FileIO、表路径和 TableSchema 的 Table;

  • new_write_builder() 从 Table 派生 WriteBuilder;
  • new_commit 创建 TableCommit(在文件系统实现下通常包装 SnapshotCommit);
  • new_write 创建 TableWrite 并返回 write 句柄。

txn 和 writer 分别负责提交和写数据。

3. 写数据:write_arrow_batch

这里是写入路径中唯一调用 Parquet 编码的地方;TableWrite 接收 Arrow RecordBatch,按照 partition/bucket 路由行数据,缓存到内存,达到阈值后编码为 Parquet 数据文件并通过 FileIO 落盘。

此时文件已经存在了,但对任何 read 操作都是不可见的,因为它们没被任何 snapshot 引用。

4. 两阶段提交:prepare_commit → commit

prepare_commit 是写入和提交的边界,它主要完成:

  1. flush 所有未完成的 writer;
  2. 收尾 parquet 文件;
  3. 产出一组 CommitMessage,精确描述本次新增哪些文件以及删除、索引变更。

txn.commit(msg) 此时才真正让数据“可见”:SnapshotCommit 读取当前最新已提交快照作为基线,做乐观并发冲突检测,通过后构造新的 Snapshot,包含 baseManifestList/deltaManifest 引用,并以原子性原语在文件系统上尝试创建 snapshot-{new_id},依赖 PutIfAbsent 语义发布。一旦这个 Snapshot 文件存在,本次写入的所有 Parquet 文件瞬间对后续的读取可见。

补充说明

writer.write_arrow_batch(&batch) 通常只需调用一次,但在 prepare_commit 之前,数据并没有真正写完——若是 TableWrite 内部有缓冲区未达阈值,prepare_commit 会负责 flush。这意味着 write_arrow_batch 返回 Ok 只代表“数据已被接受并可能已落盘部分文件”,不代表提交会成功。真正的原子性只依赖最后的 commit 阶段的轻量级元数据指针切换。这也是为什么 prepare_commit 返回值与 commit 入参是同一个 msg,提交的语义完全由这份“文件增删描述”承载,而不是由数据文件本身决定。

二、Catalog 创建

在 paimon-rust 中通过 CatalogFactory 来创建 Catalog,主要是根据 “metastore” 选型来调用不同的 Catalog 实现;目前主要有 filesystem 和 rest 两种 Catalog 创建方式。

// 创建 filesystem 的 catalog: FileSystemCatalog
let mut options = Options::new();
options.set("metastore", "filesystem"); // 不提供默认使用:filesystem
options.set("warehouse", "/path/to/warehouse");

let catalog = CatalogFactory::create(options).await?;

// 创建 rest 的 catalog: RestCatalog
let mut options = Options::new();
options.set("metastore", "rest");
options.set("uri", "http://localhost:8080");
options.set("warehouse", "my_warehouse");
let catalog = CatalogFactory::create(options).await?;

采用工厂模式来实现创建 Catalog 的方式。当未指定 metastore 时,直接创建 FileSystemCatalog:

let metastore = options
    .get(CatalogOptions::METASTORE)
    .map(|s| s.as_str())
    .unwrap_or(METASTORE_FILESYSTEM); // 默认未指定 metastore 时创建 FileSystemCatalog

match metastore {
    METASTORE_FILESYSTEM => Self::create_filesystem_catalog(options).await,
    METASTORE_REST => Self::create_rest_catalog(options).await,
    _ => ConfigInvalidSnafu {
        message: format!(
            "Unknown metastore type: '{metastore}'. Available types: {METASTORE_FILESYSTEM}, {METASTORE_REST}"
        ),
    }
    .fail(),
}

2.1 创建 FileSystemCatalog

  • 创建接口:create_filesystem_catalog(options);这是一个 sync 函数,需要放到 Tokio blocking runtime 中运行;
  • 底层调用 FileSystemCatalog::new(options),主要完成如下内容:
    • 检查 warehouse 配置项是否正常;
    • 创建本地 cache;
    • 构建 FileIOBuilder,创建 catalog 关联的 FileIO。

2.2 创建 RestCatalog

  • 创建接口:create_rest_catalog(options);
  • 底层调用 RestCatalog::new(options),主要完成如下内容:
    • 构建 RestApi 用于后续“共享”使用,包括 RESTCatalog 本身、创建的 Table、RESTEnv,为了避免重复建链接池和认证状态;同时也是真正发起网络请求的地方,合并 options:服务端 defaults、overrides、以及传入的 options;
    • 验证是否需要 data token 数据令牌安全验证:由 DATA_TOKEN_ENABLED 配置项决定;该配置项需要结合客户端和服务端判断;
    • warehouse 的提取:不同于前面的 FileSystemCatalog 是需要手动指定的,在 RESTCatalog 中 warehouse 可由服务器端提供默认值;
    • 创建本地 cache,这里需要注意的是 options(客户端的配置,属于节点属性)和 api_options(客户端和服务端合并后的配置)两者是需要分离的,缓存物理行为归客户端操作,缓存逻辑身份归 catalog 管;
    • 构建 FileIOCacheContext(FileIO 层缓存上下文),不同于 LocalCache 直接缓存文件格式元数据,而不是原始字节块;
    • 构建 FUSE 路径解析器,将逻辑路径解析为 FUSE 挂载点下的实际路径。

2.3 FileSystemCatalog 与 RESTCatalog 对比

维度FileSystemCatalog::newRESTCatalog::new
同步性同步,无网络异步,RESTApi::new 发请求
warehouse必填,.context()?可选,.unwrap_or_default()
配置来源原始 options合并后的 api_options
缓存创建create_local_cache(同步)create_local_cache_with_namespace_async(异步,双 options)
额外状态无api、fuse_resolver、data_token_enabled、file_io_cache
错误来源本地配置 + 文件系统本地配置 + 网络 + 服务端响应

⚠️ 注意

在 RESTCatalog 中出现了三个 Arc:

  • Arc<RESTApi>:共享连接池和认证状态,避免每次建 Table 都重新握手;
  • Arc<LocalCache>(在 create_local_cache_with_namespace_async 内部):共享缓存数据,多个 Table 命中同一份块;
  • Arc<FusePathResolver>:共享纯配置解析结果,它本身不可变,Arc 只是为了避免重复构造。

三者都是“共享”,但共享的对象分别是网络资源、磁盘资源和内存配置。

三、Database

3.1 公共接口定义

/// 创建 database
/// @param name 数据库名称
/// @param ignore_if_exists 是否存在忽略
/// @param properties 数据库相关配置
async fn create_database(
    &self,
    name: &str,
    ignore_if_exists: bool,
    properties: HashMap<String, String>,
) -> Result<()>;

3.2 FileSystemCatalog 实现

  • 路径验证防护:database_path 对应路径 warehouse/{name}.db;若是提供的 name 是 "../escaped",则会拼出“逃出”warehouse 目录的路径;同时针对 /、\、.. 等路径分隔符或其他“逃出”warehouse 目录的名称等;
  • 验证 DB_LOCATION_PROP:主要解决 RESTCatalog 与 FileSystemCatalog 的不同——允许 RESTCatalog 中 database 指向自定义的存储位置,而 FileSystemCatalog 则是由 warehouse 和 name 来界定 {warehouse/{name}.db},不允许自定义位置;
  • 计算 database 路径并检查其是否存在:拼接纯字符串的路径,无 I/O;接着发起一次 I/O 查询(在对象存储上是 exists_dir 调用,在本地是目录 stat)进行 database exists 验证;
  • 在 database 路径检查完成后,还需要进行“幂等性检查”,验证 ignore_if_exists 和 database_exists 是否满足;
  • 接着在前面检查满足后,是否需要创建 database 的目录(mkdirs 在 OpenDAL 语义下是递归创建,会创建 warehouse 下所有缺失的父目录,甚至 warehouse 不存在,在这一步连同它一起创建)。

通过前面的步骤发现一个细节:database_exists 检查只看目录是否存在,不检查目录下是否有内容(换句话说,在 warehouse 下手动 mkdir database.db,此时调用 create_database("database", false, {}) 会返回 Database AlreadyExist)。

3.3 RESTCatalog 实现

基本实现步骤和 FileSystemCatalog “很像”,差异点在于:

  • database 名称合法验证:放在服务端进行,客户端不需要重复实现;
  • DB_LOCATION_PROP:同样存在这个属性,提交给服务端,由服务端决定是否支持;
  • 幂等性:不同于 FileSystemCatalog,RESTCatalog 不在本地做存在性预检,通过调用,再根据对应的错误类型来决定如何处理。

基于 Catalog trait,实现两种完全不同的路径:文件系统实现依赖“预检 + 条件创建”,REST 则是依赖“调用 + 错误映射”。

四、创建 Table

4.1 FileSystemCatalog.create_table

主要是通过 Catalog trait 中的 create_table 来完成创建 Table,在整个创建 Table 过程中都有一个明确的“失败模式”:路径有效性检查、类型不可加载、对象表规范化、幂等性、数据库不存在以及非原子创建的中间状态。

  • 名称验证——防止路径“穿越”:identifier.validate()?;
    • table_path(identifier) 会拼出 warehouse/{database}.db/{table};
    • 类似 table 路径 "../../table_escape" 会“逃出”warehouse,代码检测返回 IdentifierInvalid,确保在发生 I/O 之前,规避通过存在性来探测 warehouse 外的路径。
  • 解析并验证表类型——失败关闭:let declared = CoreOptions::new(creation.options()).table_type()?;
    • 此步骤是容易被低估的一步,通过 table_type() 从 schema 的 options 中读取 type,解析为 enum TableType(Table、ObjectTable、IcebergTable、LanceTable 等);
    • 此步骤的错误处理方式能够将非法类型不被持久化到 schema 文件;确保不用等到 get_table 读取时才发现无法加载,此时表已经“存在”,再进行清理就比较麻烦。
  • 对象表规范化:
    • ObjectTable 有固定的 schema(存储 BLOB、向量等非结构化数据结构),同时其数据路径可能独立于表路径;
    • normalize_creation 把用户传入的任意字段替换为 ObjectTable::fields(),并在用户未显式指定 path 时,将表路径填入 PATH_OPTION;
    • 此步骤必须在写入 schema 之前完成,否则持久化就是未规范化的原始 schema,会导致后续的 load_table 读取的字段和路径不对。
  • 表存在性检查与幂等性:
    • table_exists 检查表是否存在,主要是依据 schema 文件(schema-0 或 schema 下任意的 schema-*)是否存在,而不是依据表目录是否存在;一个只有目录 + 没有 schema 文件的“空壳”不算表;
    • 建表的操作不是原子性的。
  • 数据库存在性检查:
    • 这一步为什么还要进行 database 是否存在?并且该检查位于表存在性检查之后:1)若是表存在,也就隐含了数据库存在;2)只有表不存在时,才需要确认数据库是否存在。
  • 非原子创建 Table——mkdirs + 写 schema:
    • 本步骤存在两步操作:1)mkdirs(&table_path) 创建表目录;2)save_table_schema 序列化 TableSchema::new(0, &creation) 并写入 schema/schema-0;
    • 但这两个操作不是原子的,会存在创建一个有目录、无 schema 的“残留”;
    • table_exists 检查采用的“schema 凭证”让非法的“残留”不可见。

在整个 create table 过程中,整个过程不是原子性的,同时没有并发时的“锁保证”:两个并发的 create_table 正常的操作,最终会出现“谁后写,将另外一个的 schema 覆盖”。但对此过程“加锁”,却不是容易的。FileSystemCatalog 属于无状态服务对象,没有合适的锁载体;同时对象存储上也没有跨进程级的原子锁原语。真正解决方案最好是依赖底层存储的原子创建语义(比如 PutIfAbsent 或 rename),在 Catalog 层加进程内锁,也只是防住同进程的并发操作,并不能解决多进程或多节点。这也是导致现在 create_table 依赖 save_table_schema 底层写入的原子性。

4.2 RESTCatalog.create_table

不同于 FileSystemCatalog.create_table,在 RESTCatalog 中:

  • 验证:REST 侧不做本地表名验证、不做本地类型验证,全部委托服务端;
  • 存在性:REST 侧不做预检,直接调用 RESTApi 相关接口,再根据 AlreadyExists 错误决定如何处理;
  • 原子性:REST 侧保证原子性,客户端不再需要关心“目录建了但 schema 没写”的中间状态;
  • 错误处理:REST 侧把 map_rest_error_for_table 来把 HTTP 404/409 翻译为领域错误;文件系统侧直接产生领域错误。

FileSystemCatalog 采用“预检 + 条件写入 + 容忍中间状态”来解决非原子性,RESTCatalog 则实现“调用 + 错误映射”把原子性责任交给服务端;前者的复杂度在本地状态管理,后者的复杂度在协议错误映射翻译。

五、获取 Catalog Table:get_table

5.1 FileSystemCatalog.get_table

在 paimon-rust 中获取 table,一般分为两个步骤:

  • 步骤一:定位与加载元数据 fetch_table_schema

    • 验证 database 与 table,以及阻断路径“穿越”;
    • 计算 table_path({warehouse}/{db}.db/{table});
    • 检查表是否存在 table_exists,不存在时则返回 Error::TableNotExists;
    • 加载最新的 schema(load_latest_table_schema),返回 TableSchema。
  • 步骤二:构建 Table build_table

    首先解析 schema 中的 type 选项,如果声明的表类型需要外部类型(iceberg-table、lance-table 等),不会尝试用 Paimon 去解释其他格式的数据,直接拒绝。

注意:get_table 与 load_table 的差异

get_table:需要给一个可以直接读写 Paimon 表,若不是,直接报错;用于常规的读写路径。

load_table:告知这张表是什么类型,并提供一个可路由的表示,最后返回一个外部类型的元数据,但不保证可读;用于路由和类型探测。

维度get_tableload_table
返回类型TableLoadedTable(枚举)
ObjectTable拒绝(requires_table_engine() 含 ObjectTable?需看实现)构造 LoadedTable::Object
外部引擎类型拒绝(Unsupported)构造 LoadedTable::External,交由上层引擎处理
原生 Paimon 表构造 Table构造 LoadedTable::Paimon

fetch_table_schema 只检查表是否存在 schema 文件,并不做检查数据库是否存在。若是 database 目录不存在,table_exists 找不到 schema 文件返回 false,最终输出 TableNotExists,而不会输出 DatabaseNotExists。不同于 create_table 在表不存在时显式检查数据库存在性,会返回 DatabaseNotExists,get_table 调用方只关心表是否存在,不关心失败是由于表还是数据库。

5.2 RESTCatalog.get_table

直接将所有上下文(API 客户端、配置、token 开关、缓存、FUSE 解析器)打包传给 RESTEnv::load_table 来完成远程元数据和 Table 构造。由于需要网络交互,不同于 FileSystemCatalog.get_table 分为“获取元数据”和“构建 Table”两个操作。

六、Paimon-rust 数据写入

在进行 paimon-rust 写入时,要经历构造写入器到原子提交。

6.1 构建写入构建器,接着完成写入和提交两个独立的句柄

// WriteBuilder 会持有表路径、FileIO、TableSchema 等写入所需的上下文
let builder = table.new_write_builder();

// 接下来会将提交句柄和写入器分开构建

// 提交句柄
// 主要负责提交——提取最新的快照、做冲突检测、构造并发布新的 snapshot,不需要管数据怎么编码
let txn = builder.new_commit();

// 写入器
// 主要负责写数据——接收 RecordBatch、缓存、编码为 parquet、落盘;不关心快照和如何提交
let mut writer = builder.new_write()?;

从上面的源码可以看到提交句柄和写入器职责分离,是为了满足 paimon-rust 的两阶段提交的需求。一旦合并为一个对象,在写入过程就必须持有提交锁或者在提交逻辑中需要知道写入器的内部缓冲状态,导致并发控制变得复杂;一旦分开可以持有多个 writer 并行写入数据,在最后 commit 采用串行化。

6.2 Arrow schema 构造

确保 Arrow 层面的 schema 必须与创建表时的 paimon-rust schema 字段名称、类型、可空性逐一对应,来构造 RecordBatch。

// Arrow schema
// Arc<Schema> 用 Arc 将 Arrow Schema 包裹起来,因为一个 schema 可以被多个 batch 共享,避免不必要的重复分配
ArrowSchema::new(vec![
    Field::new("id", ArrowDataType::Int32, false),
    Field::new("name", ArrowDataType::Utf8, false),
    Field::new("city", ArrowDataType::Utf8, false),
    Field::new("age", ArrowDataType::Int32, false),
    Field::new("score", ArrowDataType::Int32, false),
])

// Paimon-rust schema
vec![
    Arc::new(Int32Array::from(vec![1, 2, 3, 4, 5])),
    Arc::new(StringArray::from(vec!["Alice", "Bob", "Paul", "Diana", "Ethan"])),
    Arc::new(StringArray::from(vec!["New York", "San Francisco", "Bengaluru", "Amsterdam", "Berlin"])),
    Arc::new(Int32Array::from(vec![28, 34, 22, 31, 27])),
    Arc::new(Int32Array::from(vec![95, 82, 91, 88, 76])),
]

6.3 构建 RecordBatch

RecordBatch::try_new 来检验提供的每个数组的类型和长度是否与 schema 匹配——列数、每列元素个数以及数据类型(该操作在内存完成,不进行任何 I/O)。

另外一个 vector 中每一项都是 Arc<dyn Array>(Arrow 的动态数据表示),比如代码中的 Int32Array 和 StringArray 都会转为 ArrayRef,进而使得同一个 Vec 可以容纳不同类型的列。

6.4 写入数据

writer.write_arrow_batch(&batch).await?;

该步骤是唯一接触 parquet 编码的调用。TableWrite 接收到 RecordBatch 后:

  • 按分区/桶路由:若是表存在分区键或桶键,行数据会被拆分到不同的目标文件;
  • 缓冲:行数据先进入内存缓冲区,不立即编码;
  • 达到阈值后编码:当缓冲区达到 page 大小或行数阈值,才编码为 parquet 数据文件并落盘。

注意

write_arrow_batch 返回 Ok 只是代表“数据已被接受并可能已落盘部分文件”,并不代表提交会成功。此时只是文件存在了,但对任何读取者都不可见(没被任何 snapshot 引用)。若是此刻进程崩溃,这些文件就会成为“孤儿”,但不会影响表的当前状态。

&mut writer 是在写入时需要修改 writer 内部缓冲状态。

6.5 prepare_commit:写入与提交的边界

let msg = writer.prepare_commit().await?;

prepare_commit 需要完成三件事:

  1. flush 所有未完成的 writer:把缓冲区中未达到阈值的行编码为 parquet 文件,确保没有数据留在内存里;
  2. 收尾所有 parquet 文件:写入 footer、关闭文件;
  3. 生成 CommitMessage:精确描述本次写入新增了哪些文件、删除了哪些文件(包括索引、changelog 等变更)。

此时返回的 msg 是一个纯数据描述,不会持有 writer 和文件句柄,从此刻起,writer 任务完成了。

6.6 commit:原子发布

txn.commit(msg).await?;

TableCommit::commit 接收到 msg 后,将执行如下内容:

  • 读取当前最新已提交快照作为基线;
  • 乐观并发冲突检测:若是存在另一个 writer 已基于旧快照提交了冲突的变更,本次提交被拒绝,需要重试;
  • 构造新的 snapshot:包含 baseManifestList/deltaManifestList 引用、schemaId、commitKind 等字段;
  • 原子发布:在文件系统上通常是尝试创建 snapshot-{new_id},依赖 PutIfAbsent 语义保证只有一个写入者成功。

一旦这个 snapshot 文件存在,本次写入的所有 Parquet 文件瞬间对后续的读取可见。这就是 paimon-rust ACID 保证的最终落点:数据文件先落盘但不可见,可见性由一次轻量级的元数据指针切换决定。

  • writer 和 txn 的生命周期是独立的。txn 在 new_commit() 时被创建,但直到 commit(msg) 才真正发挥作用。中间 writer 写多少数据,txn 并不关心——只认 msg。也就是 msg 是 writer 和 txn 间唯一的信息载体,一旦 msg 失败或损坏,commit 则无法正确进行。
  • commit 失败时已产生的数据文件则不会自动清理,若是冲突检查失败或原子发布失败,commit 返回 Err,但已经落盘的 parquet 文件仍存在,并成为“孤儿文件”,不被任何 snapshot 引用,最终由独立的清理机制(基于快照过期策略)回收。这也是“先写文件,后提交”的模式固有代价:用少量的存储浪费换取提交路径的轻量化和原子性。

相对来说,在 RESTCatalog 中,txn.commit(msg) 虽有相同的语义,却实现不同。RESTSnapshotCommit 会把 msg 和提交标识(比如 uuid)一同发给服务端,再由服务端做冲突检测和原子发布。客户端其他的部分代码则完全不变:writer.write_arrow_batch、prepare_commit、txn.commit 的调用顺序与 FileSystemCatalog 一致,主要的差异在 TableCommit 的具体实现封装。