Velox DataSource 源码核对清单

基线：origin/main c52ff97b4b5b0f2d0f931f989e5f9c98020927ba，2026-10-21。

本文按真实 TableScan 调用者核对 Hive / Iceberg 的 CPU 文件扫描。没有改动 Velox，也未运行完整引擎测试。13 个场景为源码推演；小型数据选择与桶号算例单独校验。

主调用链

TableScanNode → TableScan::getSplit / getOutput → registry-selected Connector → FileDataSource constructor → subclass createSplitReader → FileSplitReader/override prepareSplit → DWIO Reader / RowReader → subclass next → residual ExprSet → output projection → splitFinished / next split / takeover。

重点行为边界

  • 普通 split 复用 ScanSpec；extraction/bucket/preload 是不同创建或替换路径。
  • moveAdaptationFrom 只处理直接 child，跳 constant，不递归、不清缓存、不复制 metadata/extraction。
  • MetadataFilter leaf 与创建时 ScanSpec 绑定；重建不自动重绑。
  • DataSource 的 R、G、P 类型与实际 RowVector/child.type 分开检查，前 N 列保持投影契约。
  • zero-projection 带辅助列的非零行路径返回内部 RowVector；空 batch 使用计划类型。
  • 动态 Filter 在 Driver 合并，在 ScanSpec 替换；常量与 takeover 时序有独立边界。
  • donor context、ExprSet listener 析构与 borrowed reader 状态应分别做寿命审计。
  • Iceberg position/DV 在 DWIO Mutation 阶段，equality delete 在读 key 后；changelog 分路。

13 个场景

  • 15.1 输出名称与表/文件列名不同
  • 15.2 输出 c0，remaining filter 用未投影 c1
  • 15.3 某列仅做 reader 下推过滤
  • 15.4 ROW / ARRAY / MAP 子字段裁剪
  • 15.5 extraction 把 MAP 变成 ARRAY
  • 15.6 只输出分区列、row index 或 Hive row ID
  • 15.7 文件缺列后又重新出现
  • 15.8 相同隐藏桶列的连续 split，同时有嵌套 Filter
  • 15.9 Hive row ID 常量在连续 split 与 takeover 后变化
  • 15.10 Equality delete 需要未投影 key
  • 15.11 Position delete、lineage 与 changelog
  • 15.12 动态过滤遇到真实列、缺失列、常量与 preload
  • 15.13 零输出列、零 batch、空 split

固定版本源码入口

配图生成

SVG 按 MacHexo 项目 lark-doc-diagram-style 与 nano-vLLM 图例绘制。下载同目录 draw.py 后使用 Python 3：

1
python3 draw.py ./diagrams

生成后仍须用 whiteboard-cli 和中文字体浏览器检查，不能以 XML 合法代替语义与布局检查。