Quickwit 双 Parquet 合并引擎:流式引擎上线期的运行时回退设计(Deviation 001 深度解析)
Quickwit 双 Parquet 合并引擎:流式引擎上线期的运行时回退设计(Deviation 001 深度解析)
本文基于 docs/internals/adr/deviations/001-dual-parquet-merge-engines.md 展开。Quickwit 的 Parquet 合并(compaction/merge)管线在当前生产中同时运行两套引擎:符合 ADR-003 目标内存模型(页级流式、内存有界)的流式引擎
execute_merge_operation,以及作为运行时回退的常驻内存引擎merge_sorted_parquet_files。两套引擎由一个节点级 YAML 开关parquet_merge_use_streaming_engine在运行时切换(默认false)。读完本文你将掌握:这套双引擎架构为何存在、开关如何接线到执行器路由、两套引擎的内存模型差异、parity 一致性测试如何保证二者等价、以及该偏差的退出条件与后续删除计划。
一、背景:ADR-003 定义的目标内存模型
在深入偏差之前,需要先理解该偏差所要对齐的"目标状态"。ADR-003 Time-Windowed Sorted Compaction 为 Quickwit 的 Parquet(metrics)管线定义了时间窗口化的有序合并设计,其中 §4 Sorted Merge, Phase 2(column streaming) 是本次偏差的核心参照:
Phase 2: Stream columns through the merge. 一旦全局排序顺序确定,每个列从输入 split 中读取并按键排序顺序写入输出。列被逐个(或小批量)处理以节省内存。 对于大列,以 页粒度(page granularity) 操作优于从每个输入加载整列:按需从输入读取单个 Parquet 页并写入输出页。这界定了含大值列(如高基数字符串 tag、大型 attribute map)的内存占用,避免同时在所有输入上物化整列。
也就是说,ADR-003 要求的合并是一个 有界内存的流式操作:页级读写、列主序(column-major)、内存占用大致恒定。而后续要介绍的常驻内存引擎恰恰与这一内存模型背道而驰——它会同时将所有输入的整列预物化进内存。
二、偏差摘要:生产环境中并存的两套引擎
Deviation 001 记录的事实是:两套 Parquet 合并引擎当前在生产环境中并存,由一个运行时 YAML 开关控制:
- 流式引擎(streaming engine):
execute_merge_operation,实现于 quickwit/quickwit-parquet-engine/src/merge/mod.rs 与 quickwit/quickwit-parquet-engine/src/merge/streaming.rs。列主序、页有界 body cache、通过RemoteByteSource读取输入。这是符合 ADR-003 的实现,也是 promotion 合并的唯一路径(内存引擎无法处理混合rg_partition_prefix_len),同时是普通合并的可选路径。 - 常驻内存引擎(in-memory engine):
merge_sorted_parquet_files,同样位于 merge/mod.rs。通过 arrow-rs 将所有输入缓冲进内存,并在run_cpu_intensive下执行合并。这是最初的 bootstrap 实现,被保留为运行时回退。
双引擎状态是 有意为之且有时限的(time-bounded):当流式引擎以新默认值在生产环境完成足够时长的 soak(浸泡验证)后,该状态即告结束。
三、路由逻辑:ParquetMergeExecutor::handle 的引擎选择
两套引擎的切换发生在执行器层。quickwit/quickwit-indexing/src/actors/parquet_pipeline/parquet_merge_executor.rs 中的 ParquetMergeExecutor::handle 负责路由,其核心分支逻辑与文档所述一致:
let is_promotion = scratch.merge_operation.target_prefix_len_override.is_some();
if is_promotion || self.use_streaming_engine {
execute_merge_operation(&op, sources, &output_dir, &config).await
} else {
run_cpu_intensive(move || {
merge_sorted_parquet_files(&input_paths, &output_dir_clone, &config)
}).await
}
从源码可以看出路由判定规则(对应执行器文件头部模块注释):
target_prefix_len_override.is_some()(即 promotion 合并)→ 无条件走流式引擎。原因:promotion 本身就是target_prefix_len_override的全部意义所在,而内存路径的extract_and_validate_input_metadata会在任何输出产生之前,就对混合的rg_partition_prefix_len报错退出;- 否则若
use_streaming_engine == true→ 流式引擎(这是 soak 完成后计划中的新默认路径); - 否则 → 常驻内存引擎(运行时回退)。
此外,mixed_prefix_ok 标志仅对 promotion 合并传给 merge_parquet_split_metadata,用于让合并后的元数据聚合器跳过输入侧的前缀长度相等性检查(详见 GAP-011 中提到的 merge_parquet_split_metadata 混合前缀支持)。
use_streaming_engine 布尔值在 ParquetMergePipelineParams 与 ParquetMergeExecutor 之间透传(见 parquet_merge_pipeline.rs 中 ParquetMergeExecutor::new(..., self.params.use_streaming_engine, ...) 的调用),最终来源于节点级 IndexerConfig::parquet_merge_use_streaming_engine。
四、YAML 开关:parquet_merge_use_streaming_engine 的配置面
开关的配置定义位于 quickwit/quickwit-config/src/node_config/mod.rs:
/// merges (those with `target_prefix_len_override`) always go through
/// the streaming engine regardless of this flag — the in-memory path
/// can't handle mixed prefix lengths.
#[serde(default = "IndexerConfig::default_parquet_merge_use_streaming_engine")]
pub parquet_merge_use_streaming_engine: bool,
关键事实:
- 默认值为
false,由default_parquet_merge_use_streaming_engine()函数显式返回false。这保证了生产环境当前默认走常驻内存引擎。 - 该字段位于节点配置的
indexer段下(与max_concurrent_split_uploads、max_merge_write_throughput、merge_concurrency等索引器参数同级)。 - 开关是 节点级(node-level) 配置而非索引级,意味着运维人员可以按节点粒度灰度启用流式引擎,构建"soak 舰队"。
完整的 YAML 配置示例(来自 quickwit/quickwit-config/resources/tests/node_config/quickwit.yaml):
indexer:
max_concurrent_split_uploads: 8
max_merge_write_throughput: 100mb
merge_concurrency: 2
parquet_merge_use_streaming_engine: true
同一配置的 TOML 与 JSON 形态分别见 quickwit.toml 与 quickwit.json。注意示例中开关置为 true 仅用于测试配置反序列化;生产默认仍为 false。回退操作极其简单:修改配置为 false 并重启节点即可,无需重新部署二进制(见下文影响评估表中"Operator rollback"一行)。
五、两套引擎的实现差异与内存模型对比
从 merge/mod.rs 的源码可以看出合并引擎的通用契约:
- 合并操作接收 N 个共享同一 sort schema 的有序 Parquet 文件,产出 M 个有序输出文件;
- 合并键为
(sorted_series ASC, timestamp_secs <方向>),时间戳方向来自 sort schema; - 输出在
sorted_series边界处切分,保证每个输出文件的键范围互不重叠; - sort schema、窗口元数据、merge ops 计数均从输入文件的 Parquet KV 元数据读取,不由调用方提供(由 compaction planner 保证所有输入共享 sort schema 与窗口,引擎侧再做校验)。
InputMetadata 结构还揭示了一个与偏差直接相关的细节:rg_partition_prefix_len(前导排序列中其转换与行组边界对齐的列数)是 compaction scope 键的一部分,所有输入文件必须一致;流式引擎在输入侧遵循该值,并在输出侧生成前缀对齐的区域——当输入 prefix_len == 0 时,引擎从合并顺序合成前缀对齐区域,并将输出的 rg_partition_prefix_len 相应提升。这正是流式引擎能处理 promotion、而内存引擎不能的原因。
两套引擎的根本差异在内存模型:
| 维度 | 流式引擎(ADR-003 目标) | 常驻内存引擎(回退) |
|---|---|---|
| 数据加载方式 | 列主序、页粒度按需读取 | 通过 arrow-rs 将全部输入缓冲进内存 |
| 内存占用 | 页有界,每列大致恒定 | 每次合并 O(总输入列大小) |
| 输入访问 | RemoteByteSource(file_size / get_slice / get_slice_stream) |
本地文件路径,整读为 RecordBatch |
| 执行环境 | async,随字节到达推进 | run_cpu_intensive 同步执行 |
| 大值列场景 | 页粒度避免整列物化(高基数字符串 tag、大型 attribute map) | 整列跨所有输入同时物化 |
值得说明的是:虽然流式引擎设计上通过 RemoteByteSource 支持直接从对象存储拉取(每次输入两次 GET:footer + body 流),但当前 actor 管线仍采用"先下载到本地 scratch 再合并"的模式(GAP-012 对此有专门记录),执行器通过 LocalFileByteSource 将本地文件包装为 RemoteByteSource 供流式引擎消费——这不影响本偏差讨论的引擎并存问题,但说明了流式引擎的完整能力尚未在生产全部启用。
六、一致性保障:parity 测试
两套引擎能安全共存的前提是行内容等价(row-content equivalence),这一约束由 quickwit/quickwit-parquet-engine/src/merge/tests.rs 中的 mod parity 测试强制执行。只要两套引擎并存,该测试就必须持续通过。
parity 测试的工作方式(结合 tests.rs 源码):
- 在同一组输入文件上分别运行
merge_sorted_parquet_files(内存引擎)和execute_merge_operation(流式引擎,通过make_regular_merge_op构造普通非 promotion 合并操作); - 流式引擎通过一个镜像执行器
LocalFileByteSource的RemoteByteSource实现来驱动——该实现将get_slice/get_slice_stream委托给本地文件的 seek/read,与生产执行器的包装方式一致; - 断言两侧输出在每个输出文件上按列逐列比对行内容一致;每个输出的物理元数据(页边界、行组大小)允许不同——只断言合并契约对读者保证的内容。
从注释看,parity 测试是 parquet_merge_use_streaming_engine YAML 开关的门禁(gate):一旦 parity 在真实感强的 fixture 上成立,生产环境就有信心翻转开关,视流式引擎为 drop-in 替换。
此外,在 actor 管线层还有端到端测试覆盖双引擎:例如 parquet_merge_pipeline_test.rs 中的测试明确以 use_streaming_engine: true 运行完整 actor 链(planner → downloader → executor → uploader → publisher),并确认在 promotion 关闭、flag 为 true 时,流式引擎是唯一可达路径、不存在静默回退;parquet_merge_pipeline_multi_metric_test.rs 则对 false 与 true 两种引擎变体均执行多指标多输入合并场景断言(sum 恒等于总量、输出 sorted_series 互斥、并集等于全集等)。
七、影响范围:Signal Impact
该偏差目前只影响 metrics(唯一使用 Parquet 管线的信号);当 traces 与 logs 后续迁移到 Parquet split 时同样适用。偏差不影响 Tantivy 支撑的管线(Tantivy 合并使用 StableLogMergePolicy 与 UnionDirectory,与本偏差无关,见 ADR-003 §Context)。
八、影响评估:ADR 目标 vs 当前现实
文档用一张对比表总结了偏差对各项指标的影响,这里完整保留:
| 方面 | ADR 目标 | 当前现实 |
|---|---|---|
| 生产中的引擎 | 单一流式引擎 | 两个(流式 + 内存) |
| 内存模型 | 页有界;每列大致恒定 | 内存引擎:每次合并 O(总输入列大小) |
| 配置面 | 无——引擎选择是内部实现细节 | 一个 YAML 开关(parquet_merge_use_streaming_engine) |
| 需维护的代码面 | 一个引擎 | 两个引擎 + parity 测试 + 路由分支 |
| 运维回退 | 不适用——只有一条路径 | 开关置回 false,无需重新部署 |
九、偏差为何存在:三大动因
流式引擎是全新代码。ADR-003 描述了目标内存模型,但不保证首次部署零 bug。三个力共同造就了双引擎状态:
- 生产安全(Production safety)。在 metrics 管线 bring-up 期间,内存引擎一直是实际运行的合并路径。若在单个 PR 中整体替换、不留就地回退,流式引擎的任何 bug 都将需要重新部署才能恢复。而有了开关,恢复 = 改配置 + 重启。
- 分阶段灰度(Staged rollout)。生产信心是通过让 soak 舰队启用流式引擎、观察一段时间、再翻转默认值建立的。双引擎状态正是这种灰度所需的基础设施。
- parity 可验证但非绝对(Parity verifiable, not certain)。
merge::tests::parity覆盖的是代表性合成 fixture,生产数据的形态(shape)未必全部覆盖。回退的存在正是因为 parity 是"强但不完全"的保证。
十、优先级评估:何时必须解决
- PoC / MVP:可接受——双引擎本来就是 MVP 灰度期间的有意状态。
- 生产(当前):可接受——开关默认
false,灰度尚未开始;流式引擎目前只被 promotion 合并使用(其执行将在 GAP-011 关闭后启动,见 GAP-011 No legacy promotion planner)。 - 生产(soak 之后):不可接受。一旦流式引擎在生产以默认
true完成 soak,内存引擎就成为死代码,它会让 merge-executor 复杂化并模糊 ADR-003 的内存契约。应在向parquet_merge_executor.rs合并更多重要工作之前解决。
十一、退出条件与后续删除计划
偏差在以下三个条件全部满足时宣告解决:
IndexerConfig::default_parquet_merge_use_streaming_engine在quickwit-config中的默认值翻转为true;- 至少一个生产舰队以
true运行了 ≥ 2 周的 soak 窗口,且无合并正确性事件(无数据丢失、无 schema 不匹配、无"merge 输出行数 ≠ 输入行数"告警); - soak 期间未发出过解除偏差的回退操作。
三个条件满足后,后续 PR 将执行:
- 从
quickwit-parquet-engine删除merge_sorted_parquet_files; - 删除
ParquetMergeExecutor::handle中的内存分支; - 删除
ParquetMergeExecutor与ParquetMergePipelineParams上的use_streaming_engine字段; - 删除
IndexerConfig::parquet_merge_use_streaming_engine; - 删除
merge::tests::parity(两套引擎已不存在,无从比较); - 关闭本偏差。
十二、回归 ADR 所需的工作清单
| 变更 | 难度 | 说明 |
|---|---|---|
翻转默认值为 true |
琐碎 | 在 IndexerConfig::default_parquet_merge_use_streaming_engine 中改一行,soak 后落地 |
| 生产 soak | 运维性 | 至少一个舰队以 true 运行 ≥ 2 周,监控合并正确性信号 |
| 删除内存引擎 | 中等 | 移除 merge_sorted_parquet_files、回退分支、开关与 parity 测试;机械上直接但触及多个调用点 |
十三、结论与建议
当前结论:接受(Accept for now)。 双引擎状态是"开关 + 回退"灰度模式的刻意产物(参见 #6441 及其相关 PR 的提交历史,即 YAML 开关的接线提交)。其解决路径是已知的后续工作,而非需要提前偿还的技术债。
该偏差文档本身就承担着跟踪职责:以本文档中的退出条件为追踪清单,当三个条件全部成立时,开启删除 PR 并关闭本偏差。对于仓库读者与运维人员,这套设计提供了一个可复用的工程范式——在架构演进期,用"运行时开关 + 等价性测试门禁 + 明确退出条件"三件套,既保住上线安全,又不让临时妥协退化为永久技术债。
相关延伸阅读:ADR-003 Time-Windowed Sorted Compaction §4、GAP-011 No legacy promotion planner、GAP-012 Merge downloads instead of streaming,以及偏差登记总览 docs/internals/adr/deviations/README.md。