Quickwit 双 Parquet 合并引擎:流式引擎上线期的运行时回退设计(Deviation 001 深度解析)

原创2026-09-14 12:16:481,842 阅读
文章标签:搜索引擎全文检索可观测性日志分析链路追踪后端云原生实时分析前端

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
}

从源码可以看出路由判定规则(对应执行器文件头部模块注释):

  1. target_prefix_len_override.is_some()(即 promotion 合并)→ 无条件走流式引擎。原因:promotion 本身就是 target_prefix_len_override 的全部意义所在,而内存路径的 extract_and_validate_input_metadata 会在任何输出产生之前,就对混合的 rg_partition_prefix_len 报错退出;
  2. 否则若 use_streaming_engine == true → 流式引擎(这是 soak 完成后计划中的新默认路径);
  3. 否则 → 常驻内存引擎(运行时回退)。

此外,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 源码):

  1. 在同一组输入文件上分别运行 merge_sorted_parquet_files(内存引擎)和 execute_merge_operation(流式引擎,通过 make_regular_merge_op 构造普通非 promotion 合并操作);
  2. 流式引擎通过一个镜像执行器 LocalFileByteSource 的 RemoteByteSource 实现来驱动——该实现将 get_slice / get_slice_stream 委托给本地文件的 seek/read,与生产执行器的包装方式一致;
  3. 断言两侧输出在每个输出文件上按列逐列比对行内容一致;每个输出的物理元数据(页边界、行组大小)允许不同——只断言合并契约对读者保证的内容。

从注释看,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。三个力共同造就了双引擎状态:

  1. 生产安全(Production safety)。在 metrics 管线 bring-up 期间,内存引擎一直是实际运行的合并路径。若在单个 PR 中整体替换、不留就地回退,流式引擎的任何 bug 都将需要重新部署才能恢复。而有了开关,恢复 = 改配置 + 重启。
  2. 分阶段灰度(Staged rollout)。生产信心是通过让 soak 舰队启用流式引擎、观察一段时间、再翻转默认值建立的。双引擎状态正是这种灰度所需的基础设施。
  3. 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 合并更多重要工作之前解决。

十一、退出条件与后续删除计划

偏差在以下三个条件全部满足时宣告解决:

  1. IndexerConfig::default_parquet_merge_use_streaming_engine 在 quickwit-config 中的默认值翻转为 true;
  2. 至少一个生产舰队以 true 运行了 ≥ 2 周的 soak 窗口,且无合并正确性事件(无数据丢失、无 schema 不匹配、无"merge 输出行数 ≠ 输入行数"告警);
  3. 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。

登录后查看全文
quickwit