【分布式 OLAP 查询引擎】Iceberg 下推全链路：Planner 视角

lakehouse 第 18 章 把读湖拆成四层漏斗：partition pruning → file pruning → row-group/page pruning → 字典过滤，并说明每层元数据从哪来、数据布局如何决定 \(p_{\text{part}}\)、\(p_{\text{file}}\)、\(p_{\text{rg}}\)。那条文章回答 「裁剪链路是什么、为什么有效」。

本文是 query-engine 系列 第 15 篇，回答 「谁在 planner 的哪一步发起裁剪、约束如何传到 Worker 上的 scan 算子」：

• SQL 里的 WHERE 如何变成 Connector 的 layout constraint。
• Trino Iceberg connector 在 Metadata → SplitManager → PageSource 的职责切分。
• Spark / DuckDB 同一谓词在 planning 入口 上的差异（能力表引用官方文档，不排名 latency）。

不重复粘贴 lakehouse/18 的漏斗全文与 Parquet 格式细节；需要时跳转 lakehouse/18、08 Iceberg 元数据、02 Parquet。

环境说明：本机 WSL2、无 JVM Trino/Spark。Trino/Spark planner 行为按 476+ / 3.5+ 官方文档与源码结构 归纳；不伪造 EXPLAIN 输出。裁剪效果数字复用 lakehouse/18 的 PyIceberg plan_files() + DuckDB 1.5.4 本机实测（A 级）。

一、与 lakehouse/18 的分工

读 lakehouse/18 建立 「读湖时发生了什么」；读本篇建立 「优化器如何发起读湖」。两篇合读才能从 SQL 文本追到 Worker 上的 Parquet reader。

二、从 SQL 谓词到 Layout Constraint

第 2 篇 之后，一条带 Iceberg 表扫描的查询在引擎内大致经历：

flowchart TB
  SQL["SQL + WHERE"] --> AN["Analyzer<br/>绑定表/列"]
  AN --> LOG["Logical Plan<br/>TableScan + Filter"]
  LOG --> OPT["Optimizer<br/>谓词下推/常量折叠"]
  OPT --> PHY["Physical Plan<br/>TableScanNode"]
  PHY --> META["Connector Metadata<br/>applyFilter / layout"]
  META --> ICE["Iceberg TableScan.planFiles()"]
  ICE --> SPL["Splits + residual predicate"]
  SPL --> SCAN["Parquet PageSource"]

关键分界：

1. 引擎内优化（Trino planner、Spark Catalyst）：常量折叠、谓词合并、join 下推——产出对 TableHandle 的 TupleDomain 或等价约束（Trino SPI ConnectorMetadata.applyFilter）。
2. Connector + Iceberg 库：把 TupleDomain 映射为 Iceberg Expression，调用 TableScan.planFiles() 做 manifest 层 partition/file pruning（Iceberg spec, Planning；A 级）。
3. Worker scan：对每个 split 打开 Parquet，做 row-group/page pruning；残余谓词在向量算子上求值。

lakehouse/18 的 funnel 主要覆盖 步骤 2 的后半 + 步骤 3；本篇聚焦 步骤 1→2 的接口 与 步骤 2→split 的分发。

三、Trino：Metadata 层注入约束

Trino Iceberg connector（文档 476+，源码 trinodb/trino plugin/trino-iceberg，A 级）在 planning 阶段的典型职责：

3.1 常量折叠与分区 transform

Trino 对 Iceberg 隐藏分区 的谓词改写（constant folding + desugaring）发生在 引擎 optimizer，再经 applyFilter 进入 Iceberg（Trino blog, Just the right time date predicates with Iceberg, 2023-04-11，B 级）。这与 lakehouse/18 第二节「partition pruning 在 manifest 层」衔接：引擎先改写 SQL 谓词，Iceberg 库再在 manifest entry 上过滤。

3.2 Dynamic filter 与 split 生成时序

第 5 篇 讲过 broadcast/partitioned join；Trino dynamic filter 在 build 侧收集 join key，运行时合并进 probe 侧 scan 的 constraint（Trino 481 docs, Dynamic filtering）。Planning 因此可能是 两阶段：

1. Coordinator 先基于静态谓词 planFiles，生成初始 split。
2. Join build 完成后，probe scan 等待 dynamic filter（iceberg.dynamic-filtering.wait-timeout），再缩小实际读范围。

这是 query-engine 独有 的时序问题：lakehouse/18 讲静态漏斗，本篇补 MPP 上 runtime 约束如何并入 scan。

3.3 EXPLAIN 读什么（不贴未实测输出）

Trino EXPLAIN ANALYZE 中关注（文档 SQL explain）：

• Scan 算子 input rows / input size vs 表总行数。
• dynamicFilters 是否出现在 probe 侧 Iceberg scan。
• Layout 行上的 partition constraint 文本。

本机未跑 Trino 时，用 lakehouse/18 的 PyIceberg 数文件 + 文档字段对照，避免伪造 CLI 输出。

四、Spark Catalyst：DataSource V2 扫描

Spark 3.5+ 读 Iceberg 走 DataSource V2（Spark SQL Guide；Iceberg Spark 文档，A 级）：

df.explain() / SQL UI 看 PushedFilters、PartitionFilters（lakehouse/18 附录 B）。AQE（第 13 篇）在 shuffle 后改分区数，不改变 manifest planning 接口，但会改 scan 并行度。

五、DuckDB：单进程内 Metadata + Scan

DuckDB iceberg 扩展（文档 Lakehouse formats，A 级）在 同一进程 完成：

1. SQL optimizer 下推 filter/project 到 IcebergScan 物理算子。
2. 扩展读 snapshot/manifest，等价 Iceberg planFiles()。
3. 复用 Parquet scan 做 row-group 跳过。

无 Coordinator：没有 split 跨网络分发，EXPLAIN ANALYZE 看 Total Files Read 与 scan 行数（lakehouse/18 实验二、本篇 第 14 篇 宽表实验）。

六、四层漏斗：Planner 发起点对照

能力边界以各引擎 当前文档 为准，不做跨引擎 latency 排名。

七、实验：复用 lakehouse/18 的 Metadata Planning 数字

下列结果来自 lakehouse/18 本机 PyIceberg 0.11.1 真实执行（10 个按天分区文件），证明 步骤 2 planFiles() 的裁剪——与 Trino applyFilter 后调用 Iceberg planning 的语义一致（Iceberg Java/Python API 同 spec）：

Planner 视角解读：

• 引擎把 event_ts 折叠成对 day transform 的约束 → Iceberg 在 manifest 分区字段上匹配 → ① 生效。
• user_id 谓词进入 planFiles() 后与 manifest bounds 求交 → ② 生效。
• country 每文件 min/max 覆盖谓词 → ② 不裁剪；不是 planner 漏下推，而是 stats + 布局决定（lakehouse/18 第三节）。

Row-group 层：lakehouse/18 实验二 DuckDB 1.5.4 对排序 Parquet 窄区间扫描 10000 行 vs 打乱文件，中位耗时 2.6 ms vs 6.3 ms——发生在 Split 打开文件之后，③ 层与引擎无关布局的数据仍一致。

八、常见「下推失效」在 Planner 上的信号

排查顺序：先确认约束是否进入 Connector，再查 Iceberg stats，最后查 Parquet 布局——与 lakehouse/18 附录 A 自检清单正交：那边偏 数据与格式，本篇偏 计划形状。

九、小结

• lakehouse/18 = 读湖漏斗与布局；本篇 = SQL planner 如何把谓词交给 Iceberg、MPP 上 split 与 dynamic filter 时序。
• Trino：IcebergMetadata.applyFilter → planFiles → Split → PageSource；Spark：V2Scan pushdown → BatchScanExec；DuckDB：单进程 IcebergScan + Parquet。
• 实测数字引用 lakehouse/18 PyIceberg/DuckDB，不伪造 Trino EXPLAIN。
• 生产内存与 spill 导致的 scan 放大见 第 16 篇；故障排查见 第 17 篇。

上一篇：DuckDB 与 DataFusion

下一篇：内存、Spill 与资源隔离

返回 系列目录 · lakehouse/18 读湖漏斗

参考资料

1. Apache Iceberg, Table Spec — Planning、planFiles()（A 级）。
2. Trino Documentation 476+, Iceberg connector、ConnectorMetadata、Dynamic filtering（A 级；本机未实测 CLI）。
3. Apache Spark SQL Guide 3.5+, Iceberg Spark 文档 — V2 pushdown（A 级）。
4. DuckDB Documentation, Iceberg Extension（A 级）。
5. lakehouse/18 本机 PyIceberg + DuckDB 1.5.4 实验（A 级）。
6. Trino Blog, Just the right time date predicates with Iceberg, 2023-04-11（B 级）。