在 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 是提交的核心路径,它依次执行:
- 授权检查(
ensure_table_write_authorized)。 - 拒绝 compact increment(
reject_compact_increment)——compact 必须走独立的 COMPACT 快照。 - 固定桶提交模式校验(
validate_fixed_bucket_commit_mode)——消息的 overwrite 标记必须与本次提交一致。 - 桶归属校验(
validate_bucket_ownership)——同一(分区,桶)不能被多个消息同时声明。 - 空消息短路(
ignore_empty_commit)。 - 消息转条目:
messages_to_entries、messages_to_changelog_entries、messages_to_index_entries。 - 进入
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 源码中反复出现的“不确定时保留文件、用同一标识重试”和“绝不在结果未知时清理”,正是这套两阶段模型在工程上必须遵守的规则。