关于 Paimon-Rust 的写操作(细节)

0 阅读21分钟

在 paimon-rust 中的写操作主要围绕一个核心契约构建:数据文件先落盘但不可见,其可见性由一次轻量级的快照元数据发布决定。定义了 WriteBuilder、TableWrite、TableCommit 让他们各自完成自己的职责,这样使得“写数据”和“让数据可见”在并发场景能够独立推进、完成,只在最后汇总:WriteBuilder 是配置与工厂层,TableWrite 是数据路由与编码层,TableCommit 是提交与并发控制层。三者通过 CommitMessage 这一纯数据载体衔接,而 RecordBatch 是贯穿始终的列式数据单位。


🗂️ 理论定义:两阶段提交与可见性边界

Paimon 写操作的核心契约是:数据文件先落盘但不可见,可见性由一次原子性的快照指针切换决定。这拆成两个阶段:

Write 阶段

TableWrite::write_arrow_batch 接收 RecordBatch,按分区和桶路由,缓冲后编码为 Parquet 文件落盘。此时文件物理存在,但没有任何 Snapshot 引用它们,读取者完全看不到。

说明

write_arrow_batch 是整个写链路中能够接收用户数据的“唯一入口”,它主要完成将一批 arrow 行数据拆分成按照分区/桶分组成子批,再交给桶级 writer。而真正完成 parquet 编码、缓冲、文件收尾等都在 write_bucket 中。但是“数据何时可见”则不归属该函数来完成。

定义

函数签名:

pub async fn write_arrow_batch(&mut self, batch: &RecordBatch)

由于写入操作是具有状态的:TableWrite 内部持有桶级 writer、缓冲状态、written 标记、动态桶的路由状态等,每次调用可能修改这些状态,故而需要持有这个引用——独占借用 &mut self;

batch: &RecordBatch 这里采用借用,主要是因为在写入完成后还需要进行比如统计行数、记录日志,同时后续的派生操作会基于这个 batch 进行过滤、规范化、路由,只在必要时才会产生新的 RecordBatch。

源码分解

1. Format Table 特殊处理

if let Some(writer) = self.format_writer.as_mut() {
    return writer.write(batch).await;
}

format_writer 存在则意味着这张表是 Format Table(如 Mosaic 等非 Paimon 原生格式)。Format Table 的写入路径和 Paimon 表完全不同:不经过分区/桶路由,也不走 CommitMessage 两阶段提交,是由格式写入器自己管理数据布局与文件生命周期。在 WriteBuilder::new 时 table.is_format_table 判断构造的是 FormatWriteBuilder 还是 PaimonWriteBuilder,在这里也会通过 format_writer 字段再次分流。

self.format_writer.as_mut() 而非 as_ref() 是因为 write 需要修改 writer 的状态。由于 Format Table 有自己的状态机和语义,故而将短路操作放在前面;这样就可以绕过后续所有的 Paimon 特有的检查(ensure_active、过滤、规范化、路由)。

2. enusure_active:writer 的生命周期检查

  • 主要检查 writer 是否处于可写状态。
  • 一个 TableWrite 不可写:1、已经 close 了;2、本身处于失败状态(fail_write 之后);3、底层的文件句柄已失效;

通过前置检查来确保后续所有的操作都在一个确定有效的 writer 上进行。

【注意】 这里不进行“是否已经 prepare_commit 过”的检查,在 prepare_commit 之后 writer 理论上不可再写,但这个需要 prepare_commit 内部的状态转换来保证的,而不是在这里进行重复检查的。

3. 过滤

let filtered = self.filter_write_input(batch)?;
let input = filtered.as_ref().unwrap_or(batch);
  • filter_write_input 返回 Option<RecordBatch>,根据结果 Some(表示过滤产生新的批次)和 None(无需过滤);后面的 .unwrap_or(batch) 若是产生了新的批次则用新的;否则使用原始的 batch。
  • 这一步主要用来解决带过滤条件的写入(比如 UPDATE、DELETE 或带谓词的写入)。

4. 规范化与空批次“短路”

let Some(batch) = self.normalize_filtered_write_batch(input)? else {
    return Ok(());
};
  • normalize_filtered_write_batch 主要完成两件事:1、类型对齐(Arrow 数组转为 Paimon 内部期望的表示,处理可空性、时间戳精度、字典编码等差异);2、空批次检测:返回 None 表示本批次数据没有可写内容——过滤后所有行被剔除也可能输入本身就是空批次。
  • return Ok(()) 是一个“短路”操作,规避对空数据进行路由、创建空桶 writer、生产空文件等情况;若是没有短路操作,对应的空批次则会继续走到 divide_write_input,接着产生空的分组结果,虽然不会写任何文件,但会进行路由计算和可能的桶 writer 创建。所以该步骤是 合法的无操作而非错误。
  • 注意一旦 batch 在这里被 shadowing:后续的代码中的 batch 则是被规范化后的批次,但 input 则仍指向过滤的原始批次。在后面的步骤中可以见到两者的差异。

5. 路由决策

let routing = self.normalize_automatic_routing_input(input)?;
self.written = true;
  • normalize_automatic_routing_input 接收的是 input(过滤后、规范化前的原始批次),而不是 batch(规范化后的批次)。这里有一个重要的“契约”:路由决策是基于原始值而不是规范化后的值。
  • 为何是 input 而不是 batch:路由需要对分区键和桶键做哈希或比较。一旦使用规范化后的值(如时间戳被转了精读、字符串被重新编码)进行哈希,可能与索引中存储的哈希不一致,导致数据被路由到错误的桶。路由使用原始值、写入用规范化值 保证了路由决策与索引的一致性(也隐含要求“规范化不改变分区键和桶键的语义”)。
  • self.written = true 置于路由之后,分组之前。一旦到了这步也就说明这批数据要进入写入流程,而不是被过滤或规范化短路掉了。同时 prepare_commit 则会基于这个标记来判断“是否需要收尾、是否要生成快照”。

6. 分组

let grouped = match self.divide_write_input(&batch, routing).await {
    Ok(grouped) => grouped,
    Err(error) => {
        self.fail_write().await;
        return Err(error);
    }
};
  • divide_write_input 执行实际的路由:根据 routing 的决策,把 batch 切分为 (partition_bytes, bucket) -> sub_batch 的分组。这里使用的规范化后的 batch,写入数据必须是规范化后的表示。
  • fail_write 分组失败调用。在分组过程中可能已为部分桶创建了 writer、分配了缓冲区、甚至写入了部分数据。若是在该步骤出现错误,选择直接返回错误而不是“放弃”writer,后续的重试或提交就会基于不一致的中间状态——某些桶有数据,某些没有,在 prepare_commit 生成的 CommitMessage 则会反映出这种不完整的状态,导致提交出问题。

所以一旦进入分组,出现失败就必须让整个 writer“失效”,而不是简单的返回错误让调用方重试。

7. 逐桶写入

for ((partition_bytes, bucket), sub_batch) in grouped {
    self.write_bucket(partition_bytes, bucket, sub_batch).await?;
}
  • 遍历分组结果,对每个 (partition, bucket) 调用 write_bucket,这里面有个比较有意思的操作:桶级失败时没有调用 fail_write()。这操作是有意的,但这里有个边界:write_bucket 的失败可能是 I/O 错误(磁盘满了、对象存储返回 5XX 等),调用方可选择重试或跳过该桶。若是 write_bucket 在失败前修改了桶 writer 的内部状态(部分写入 parquet 的文件),就会导致 writer 整体可能不一致。在当前实现中把“失败后状态是否一致”的任务交给了 write_bucket 内容,而不是在 write_arrow_batch 统一“放弃”。这也是 write_bucket 实现保证的“契约”。

【总结】

WriteBuilder::new_write 构造 TableWrite 时会根据 overwrite、resources、restore_snapshot_id 来“配置”。故而在 write_arrow_batch 中 filter_write_input、normalize_automatic_routing_input 等,可能会受到这些配置的影响。需要记住一点:write_arrow_batch 不产生任何 CommitMessage(这属于 prepare_commit 的职责),只负责将数据“分发”到桶级 writer,并维护 written 标记供 prepate_commit 判断。对应的 TableCommit 只关注 prepare_commit 产出的 Vec<CommitMessage>,而不会看到 write_arrow_batch 的输出。

Commit 阶段

TableWrite::prepare_commit 收尾所有写入器,产出 Vec<CommitMessage>——一份纯数据描述,精确记录“新增/删除了哪些文件”。TableCommit::commit(messages) 读取最新快照做乐观并发检测,通过后构造新 Snapshot 并原子发布;Snapshot 文件出现的瞬间,Write 阶段落盘的文件才同时可见。

说明

prepare_commit 是 TableWrite 的收尾与描述生成的地方,是写入与提交之间的边界,同时也是对 prepare_commit_internal 的简单封装。主要负责关闭所有的桶级 writer 的关闭和收集他们所有的产出文件,以及按照分区 partition/桶 bucket 组成 CommitMessage。至此 TableWrite 也就完成自己的任务了,后续数据文件可见则有 TableCommit 来“消费”这份描述来决定。

定义

pub async fn prepare_commit(&mut self) -> Result<Vec<CommitMessage>> {
    self.prepare_commit_internal(None).await
}

// 内核签名
async fn prepare_commit_internal(
    &mut self,
    commit_identifier: Option<i64>,
) -> Result<Vec<CommitMessage>>

可以看出 prepare_commit() 底层是直接调用 prepare_commit_internal(None);发现在 prepare_commit_internal(None) 接收 commit_identifier,若是 commit_identifier 存在则是说明 CommitMessage 需携带“本次写入对应哪个提交标识”的信息,不过 TableWrite 本身并不知道这个标识——它是由上层决定的(比如流式写入的 checkpoint_id)。而这里的 None 表示“普通的批量提交”,最终 TableCommit 会用 BATCH_COMMIT_IDENTIFIER;不过它也会被用来 1、写入 AppendPrepareIdentifier 的状态,2、用于“空闲的 writer 是否可以 close”的判定。

源码分解

1. 格式写入“短路”

if let Some(writer) = self.format_writer.as_mut() {
    return writer.prepare_commit().await;
}

和前面的 write_arrow_batch 是“对称”的。Format Table 的收尾则由格式 writer 自己来负责,不经过 Paimon 的 CommitMessage 组装逻辑。

2. ensure_acrtive:是否可收尾与“可否关闭”的前置判断

self.ensure_active()?;
let can_retire = self.append_write_configs.values().any(|config| {
    matches!(config.last_modified_prepare, Some(AppendPrepareIdentifier::Unknown))
    || matches!(config.last_modified_prepare, Some(AppendPrepareIdentifier::Known(id)) if id != i64::MIN)
});

ensure_active 确认 writer 可收尾。can_retire 则判断“是否存在 已参加过至少一次的 prepare 的 append writer 配置”。

AppendPrepareIdentifier 有两个变体:Unknown(上一次 prepare 没有携带标识)和 Known(id)(上一次 perpare 携带了标识)。i64::MIN 表示从没 prepare 过,一个哨兵值。这样主要是为了只有已经参与过的 prepare 的 writer 才能被“关闭”,一个从未 prepare 的 writer 是新建的,即使本次 prepare 没有给这个 writer 分配任何数据也不能选择“关闭”,并丢弃其相关的配置,其关联的序列号计算器是需要保留给后续的写入。

3. 预解析最新已提交标识(关键的顺序决策)

let latest_committed_identifier = if can_retire && fixed_bucket && commit_identifier.is_some() && self.append_write_configs.iter().any(|(key, config)| {
        !self.partition_writers.contains_key(key) && matches!(config.last_modified_prepare, Some(AppendPrepareIdentifier::Known(_)))
    })
{
    Self::latest_committed_append_identifier(&self.table, &self.commit_user).await?
} else {
    None
};

这一段代码逻辑比较复杂,can_retire 表示有 retire 配置;fixed_bucket 表示固定桶表(固定桶的序列号则依赖提交状态进行分配);commit_identifier.is_some() 说明本次有明确标识;append_write_configs 则对是否存在“有已知标识但当前没有活跃 writer”的配置——一般来说这些配置是“空闲的”,也可能是可以 retire,但它们 retire 是需要知道最新已提交的标识。

这段代码执行有着隐性顺序性。若是先 drain 了 writer 再解析最新提交标识,而一旦解析失败,那么已经 drain 出来的 writer 就会“丢失”——此时它们产出的文件还在,但 writer 状态没有了,无法重试。而先进行解析后 drain,保证了元数据失败时 writer 仍是完整的,接下来可以重试 prepare_commit。

4. 清空序列号缓存并 drain writer

self.partition_seq_cache.clear();
let writers: Vec<(PartitionBucketKey, FileWriter)> = self.partition_writers.drain().collect();
  • partiton_seq_cache 缓存的是“之前未见过的桶的序列号起点”,每次 prepare 都会清空,因为下一次写入会重新从最新状态开始。drain() 把 partition_writers 中所有桶级 writer 移除(留下一个空的 HashMap),后续的 prepare_commit 在独立的 writer 上并发执行。

5. 并发结尾所有桶级 writer

let futures: Vec<_> = writers.into_iter().map(|((partition_bytes, bucket), writer)| async move {
    (partition_bytes, bucket, writer.prepare_commit().await)
}).collect();
let results = futures::future::join_all(futures).await;

每个桶级 writer 的 prepare_commit() 返回 (Result<Files>, Option<FileWriter>)。另外一个元素是 retained——若 writer 在收尾后仍需保留(比如还有未完成的状态需要后续的写入),就会将自己返回,并重新插入 partition_writers,这也就变成“收尾但不销毁”。后续的操作由于桶之间没有依赖,便可并发执行所有桶的收尾。

6. 结果处理

let mut messages = Vec::new();
let mut error = None;
for (partition_bytes, bucket, (result, retained)) in results {
    if let Some(writer) = retained {
        self.partition_writers.insert((partition_bytes.clone(), bucket), writer);
    }
    match result {
        Ok(mut files) if !files.data_files.is_empty() || !files.changelog_files.is_empty() => { ... }
        Ok(_) => {}
        Err(err) => { error.get_or_insert(err); }
    }
}
if let Some(error) = error {
    self.fail_prepare(&messages).await;
    return Err(error);
}

在这步还需要进行错误收集不会立即返回:

  • retained 的重新插入发生在匹配 result 之前,无论收尾成功与否,只要 writer 返回了 retained,它就会被重新放回 partition_writers。这样可以保证一旦失败 writer 状态尽可能完整。
  • 这步一旦产生错误是需要统一收集的而不是获得“首个错误立即返回”。确保所有的桶收尾都得到执行,并且第一个错误被记录到 error 中,但后续的循环继续,这样可以尽可能多的 writer 完成收尾,避免因一个桶的失败而让其他桶的 writer 处于不确定状态。收集完毕后统一调用 fail_prepare(&message) 清理已生成的 CommitMessage,再返回错误。

7. 国定桶 + 非主键表的序列号分配

if fixed_bucket && self.primary_key_indices.is_empty() {
    let config = self.append_write_configs.get_mut(&(partition_bytes.clone(), bucket)).expect("append writer has captured configuration");
    for file in &mut files.data_files {
        file.min_sequence_number = config.next_sequence;
        config.next_sequence += file.row_count;
        file.max_sequence_number = config.next_sequence - 1;
    }
}

这是 append 表且非主键表在固定桶上的序列号分配。每个 (partition, bucket) 的 append_write_config 维护一个 next_sequence 计数器;每个数据文件被分配一个区间 [min_sequence_number, max_sequence_number],长度为 row_count。序列号用于后续的合并/读取时确定行的顺序。而主键表不走这条路径——它的序列号由 primary_key_indices 相关的逻辑在桶级 writer 内部管理。

8. 组装 CommitMessage

let mut message = CommitMessage::new(partition_bytes, bucket, files.data_files);
message.new_changelog_files = files.changelog_files;
messages.push(message);

每个有数据的桶生成一个 CommitMessage,并携带 data_files 和 changelog_files。空文件列表的桶(Ok(_) 分支)被跳过——不生成空消息。

9. 索引文件的收集与 index-only 消息

let mut index_files_by_key = match self.bucket_assigner.prepare_commit_index(file_io).await {
    Ok(files) => files,
    Err(error) => {
        self.fail_prepare(&messages).await;
        return Err(error);
    }
};
for message in &mut messages {
    let key = (message.partition.clone(), message.bucket);
    message.new_index_files = index_files_by_key.remove(&key).unwrap_or_default();
}
for ((partition_bytes, bucket), idx_files) in index_files_by_key {
    if !idx_files.is_empty() {
        let mut msg = CommitMessage::new(partition_bytes, bucket, vec![]);
        msg.new_index_files = idx_files;
        messages.push(msg);
    }
}

索引文件由 bucket_assigner(动态桶分配器产生的 hash 索引等)。会按照 (partition, bucket) 分组,先匹配到已有的 CommitMessage 上;剩下的、没有对应数据消息的索引文件会生成独立的 index-only 消息:旧桶的键迁移走了,数据 writer 不在,但索引仍需要提交。如果索引收集失败则会调用 fail_prepare 清理,保持不留下“半产品”。

10. append_write_configs 的 retain 逻辑

let modified = messages.iter().map(|message| (message.partition.clone(), message.bucket)).collect::<HashSet<_>>();
self.append_write_configs.retain(|key, config| {
    if modified.contains(key) {
        config.last_modified_prepare = Some(match commit_identifier {
            Some(id) => AppendPrepareIdentifier::Known(id),
            None => AppendPrepareIdentifier::Unknown,
        });
        return true;
    }
    if !can_retire { return true; }
    if !fixed_bucket { return false; }
    match (commit_identifier, config.last_modified_prepare, latest_committed_identifier) {
        (Some(_), Some(AppendPrepareIdentifier::Known(last)), Some(latest)) => last >= latest,
        _ => true,
    }
});

这地方是整个函数中最精细的状态管理。append_write_configs 保存每个桶的序列机号计数器和“上次 prepare 的标识”,并需要在 prepare 之后决定哪些配置保留、哪些 retire:

1、有数据的桶(modified)一定保留,并更新 last_modified_prepare 为本次的标识(Known(id) 或 Unknown);

2、空闲的桶(未出现在本次 message 中):

  • can_retire 为 false(从未 prepare 过)→ 保留。新建的 writer 不能因为这次没数据就被丢弃。
  • 非固定桶 → retire。动态桶的序列号由索引管理,不需要保留计数器。
  • 固定桶 + 有明确标识 + 有已知的上次标识 + 有最新已提交标识 → 仅当上次 prepare 的标识不早于最新已提交标识时保留。这保证了“上一次的输出还没确认提交”时,配置不能丢,否则序列号会回退导致重复。如果上次的输出已经提交了,配置就可以 retire。
  • 其他情况(_ => true)→ 保守保留。无法证明已提交时,宁可保留。

【总结】

write_arrow_batch 把数据写进桶级 writer 的缓冲区,prepare_commit 把缓冲区 flush 成文件并组装 CommitMessage,TableCommit::commit 消费这些消息做冲突检测和快照发布。

彼此之间的状态契约是:

  • write_arrow_batch 设置 written = true,prepare_commit 不检查它,但 TableCommit 可能通过空消息列表来判断是否需要提交。
  • prepare_commit 不清空 append_write_configs 中有数据的桶,因为后续的写入可能继续使用同一个序列号计数器;它只 retire“已确认提交的空闲桶”。
  • prepare_commit 失败时调用 fail_prepare 清理已生成的消息,但不删除已落盘的文件——这些文件由 TableCommit::abort 在明确放弃时清理,因为“prepare 失败”不等于“写入放弃”。

写入和提交这条边界意味着:write_arrow_batch 返回 Ok 只代表“数据被接受”,prepare_commit 返回 Ok 只代表“文件已收尾并生成描述”,只有 commit 成功才代表“数据对世界可见”。


🏗️ 架构设计:三层职责与 CommitMessage 的桥梁作用

WriteBuilder(工厂层)

不持有数据,只持有配置——commit_user、overwrite 标记、ResourceContext(内存预算)、restore_snapshot_id(动态桶恢复)。它通过 WriteBuilderKind 枚举在 PaimonWriteBuilder 与 FormatWriteBuilder 之间分发,对调用方屏蔽表类型的差异。new_write() 和 new_commit() 是它的两个核心方法:前者构造 TableWrite,后者构造 TableCommit,两者共享同一个 commit_user——这是幂等提交和重复检测的关键。

TableWrite(数据层)

持有表上下文、写入状态和桶级 writer。write_arrow_batch 做路由(分区 + 桶),prepare_commit 做收尾并生成 CommitMessage。它不关心快照如何发布,只负责“把数据变成文件和文件描述”。

TableCommit(提交层)

持有 SnapshotManager、SnapshotCommit 抽象、重试配置和提交回调。commit 做冲突检测、构造 Snapshot、原子发布。它不关心数据怎么编码,只认 CommitMessage。

CommitMessage 是唯一的跨层载体

TableWrite 产出它,TableCommit 消费它。它携带 partition、bucket、new_files、new_changelog_files、new_index_files、compact_before/after、total_buckets 等字段。TableCommit 的 messages_to_entries 把它转成 ManifestEntry,再做冲突检测和快照构造。两层之间没有共享可变状态,只有这份不可变描述。


🔬 代码实现:三个组件的关键逻辑

WriteBuilder:配置收集与工厂分发

PaimonWriteBuilder 的字段直接对应写操作的四个可配置维度:

struct PaimonWriteBuilder<'a> {
    table: &'a Table,
    commit_user: String,           // 默认 Uuid::new_v4()
    overwrite: bool,               // 默认 false
    resources: Option<ResourceContext>,
    restore_snapshot_id: Option<i64>,
}

with_commit_user 的校验是最值得看的一段。validate_commit_user 拒绝空串、.、..、首尾空白、包含 / 或 \、包含控制字符的输入。原因是这个值会嵌入数据文件名(data--u-{commit_user}-s-...)并写入快照元数据,必须是安全的文件路径片段。测试 test_with_commit_user_rejects_invalid_file_name_segments 逐项锁定了这些拒绝规则。

with_restore_snapshot 的条件校验同样精确:它只在 bucket == -1(HASH_DYNAMIC)、有主键、且所有分区键都在主键中的表上生效,否则返回 DataInvalid。这不是过度防御,而是因为恢复语义只对动态桶表有意义。

new_write 的授权检查分两层:ensure_table_write_allowed 只检查表类型是否为可写的 Paimon 表;try_new_commit 额外调用 ensure_table_write_authorized,对启用了 query-auth.enabled 的表要求必须是从 REST Catalog 加载的、带查询授权会话的表。这是为了防止“用一个手工构造的 schema 绕过查询授权,把受保护的表当成普通文件系统表来写”。

TableWrite:路由与收尾

write_arrow_batch 的流水线(已在上一轮详细分析)可以概括为:格式写入器短路 → 状态检查 → 过滤 → 规范化 + 空批次短路 → 路由决策 → 分组(失败则 fail_write)→ 逐桶写入。它严格停留在路由层,不涉及 Parquet 编码细节。

prepare_commit 的职责是收尾与描述生成:flush 所有桶级 writer 的缓冲,关闭 Parquet 文件,然后为每个(分区,桶)生成一个 CommitMessage,其中 new_files 列出本次新增的数据文件,new_changelog_files 列出 changelog 文件,new_index_files 列出索引文件。

TableCommit:校验、冲突检测与发布

TableCommit::new 的构造逻辑体现了它需要预先解析多少配置:

let snapshot_commit = if let Some(env) = &table.rest_env {
    env.snapshot_commit()                                    // REST 模式
} else {
    Arc::new(RenamingSnapshotCommit::new(snapshot_manager.clone()))  // 文件系统模式
};

SnapshotCommit 抽象把“原子发布”的实现差异封装起来:文件系统用 RenamingSnapshotCommit,REST 用服务端提交。后续所有逻辑都只依赖这个 trait。

commit_with_identifier_impl 是提交的核心路径,它依次执行:

  1. 授权检查(ensure_table_write_authorized)。
  2. 拒绝 compact increment(reject_compact_increment)——compact 必须走独立的 COMPACT 快照。
  3. 固定桶提交模式校验(validate_fixed_bucket_commit_mode)——消息的 overwrite 标记必须与本次提交一致。
  4. 桶归属校验(validate_bucket_ownership)——同一(分区,桶)不能被多个消息同时声明。
  5. 空消息短路(ignore_empty_commit)。
  6. 消息转条目:messages_to_entries、messages_to_changelog_entries、messages_to_index_entries。
  7. 进入 commit_with_maintenance,最终走到 try_commit。

try_commit 的重试循环是并发控制的核心。每一轮迭代:

  • 读取最新快照。
  • 若 filter_committed,检查该 commit_identifier 是否已提交;已提交则返回 Filtered,避免重复执行破坏性操作。
  • 检查是否有重复提交(find_duplicate_commit),命中则直接返回已发布的快照。
  • 校验 expected_snapshot_id(如果调用方指定了期望的最新快照)。
  • resolve_commit 解析条目、检测冲突、合并索引。
  • 若解析结果为空且不需要空提交,返回 Empty。
  • try_commit_once 构造并发布快照。
  • 发布成功返回 Published;失败返回 Retry,进入下一轮,直到超时或重试次数耗尽。

冲突检测由 detect_commit_conflicts 驱动,它先解析冲突基线(resolve_conflict_base_entries),再调用 check_commit_conflicts。后者做了多层校验:删除条目必须存在于基线中(check_delete_entries_against_base)、文件条目不能重复(validate_file_entries)、固定桶的总桶数必须一致(check_total_bucket_conflicts)、postpone 桶的归属不能冲突(check_fixed_bucket_ownership_conflicts)、行 ID 不能冲突(check_row_id_existence 等)。这些校验共同保证了并发写入不会产生语义冲突的提交。

prepare_snapshot 是构造快照的地方,它写 delta manifest、changelog manifest、base manifest list,分配行 ID(如果启用行跟踪),处理删除向量的索引重写,最后用 Snapshot::builder() 组装出完整的快照对象。这个对象的字段——base_manifest_list、delta_manifest_list、commit_kind、total_record_count、next_row_id 等——就是快照文件的 JSON 内容。

abort 与 delete_new_files 处理“已知未提交”的清理。它们的注释反复强调:绝不能在提交结果未知时调用。因为发布可能已经成功但响应丢失,此时删除文件会让已发布的快照引用不存在的文件。这与 try_commit 中 publication_uncertain 的处理形成呼应——不确定时返回 UnexpectedError 并要求调用方保留文件、用同一 commit_identifier 重试。


🔗 三个组件的协作时序

调用方           WriteBuilder        TableWrite         TableCommit        SnapshotCommit
  │                  │                   │                   │                   │
  │── new_write ────▶│                   │                   │                   │
  │                  │ 授权检查           │                   │                   │
  │                  │── TableWrite::new ▶│                   │                   │
  │◀── writer ───────│                   │                   │                   │
  │                  │                   │                   │                   │
  │── new_commit ───▶│                   │                   │                   │
  │                  │── TableCommit::new ┼──────────────────▶│                   │
  │◀── txn ──────────│                   │                   │                   │
  │                  │                   │                   │                   │
  │── write_arrow_batch(batch) ─────────▶│                   │                   │
  │                  │                   │ 过滤/规范化/路由   │                   │
  │                  │                   │ 分组 → 逐桶写入    │                   │
  │                  │                   │ Parquet 落盘(不可见)│                  │
  │◀── Ok ───────────────────────────────│                   │                   │
  │                  │                   │                   │                   │
  │── prepare_commit() ─────────────────▶│                   │                   │
  │                  │                   │ flush/收尾         │                   │
  │                  │                   │ 生成 CommitMessage │                   │
  │◀── messages ─────────────────────────│                   │                   │
  │                  │                   │                   │                   │
  │── txn.commit(messages) ──────────────────────────────────▶│                   │
  │                  │                   │                   │ 校验/冲突检测      │
  │                  │                   │                   │ 构造 Snapshot      │
  │                  │                   │                   │── commit(snapshot)▶│
  │                  │                   │                   │                   │ 原子发布
  │                  │                   │                   │◀── Ok(true) ──────│
  │◀── Ok ───────────────────────────────────────────────────│                   │

💎 总结

paimon-rust 写操作的实现可以收敛为:WriteBuilder 收集配置并构造两个共享 commit_user 的句柄;TableWrite 把 RecordBatch 路由、编码为不可见的 Parquet 文件,并在 prepare_commit 中产出描述文件增删的 CommitMessage;TableCommit 消费这份描述,通过乐观并发控制检测冲突、构造新快照,并借助 SnapshotCommit 抽象原子发布。 三层之间没有共享可变状态,CommitMessage 是唯一的桥梁,而“可见性”只在最后那次快照指针切换时发生。TableCommit 源码中反复出现的“不确定时保留文件、用同一标识重试”和“绝不在结果未知时清理”,正是这套两阶段模型在工程上必须遵守的规则。