Lance 列式存储的 Arrow 统计累加器:深入解读 lance-arrow-stats 的谓词下推基石

原创2026-09-16 14:07:191,893 阅读
文章标签:数据湖湖仓一体大数据列式数据库向量数据库全文检索OLAP人工智能

Lance 列式存储的 Arrow 统计累加器:深入解读 lance-arrow-stats 的谓词下推基石

本文围绕 Lance 开源仓库中的 rust/arrow-stats 模块,系统讲解 lance-arrow-stats——一个面向 Apache Arrow 数组流的统计累加器。它通过一次数据扫描同时累计 min、max、null_count、nan_count、item_nulls 与 buffer_memory 六类统计信息,是 Lance 列式存储层中页级(page-level)统计信息与谓词下推(predicate pushdown)、查询规划的重要数据来源。读完本文,你将掌握它的核心 API、支持的数据类型边界、并行合并机制,以及它在 Lance 标量索引(如 ZoneMap 与 Bloom Filter)中的真实落地方式。

模块定位:统计信息从何而来

在 Lance 的列式存储设计中,查询引擎要快速跳过与过滤条件无关的数据页,前提是每一页都携带浓缩的统计摘要(如某页某列的最小值/最大值)。lance-arrow-stats 正是这套机制的前置组件:它不直接参与存储格式的读写,而是负责在数据写入或索引构建过程中,对一批又一批(batch)的 Arrow 数组做流式统计累计,最终产出一份可供存储层与查询层消费的统计快照。

其官方定义(见 rust/arrow-stats/README.md)是:

Statistics accumulator for Apache Arrow arrays. Computes min, max, null count, NaN count, and buffer memory usage over one or more batches of Arrow data. Designed for use in Lance's columnar storage layer where page-level statistics drive predicate pushdown and query planning.

也就是说,它的职责边界非常清晰:输入是共享同一 DataType 的一个或多个 Arrow 数组(ArrayRef),输出是一份结构化的统计结果,供上层(如 ZoneMap 标量索引、Bloom Filter 索引)进一步加工后写入存储或参与查询裁剪。

从 rust/arrow-stats/Cargo.toml 可以看到它的依赖面刻意收窄,仅依赖 arrow-array、arrow-schema 与工作区内的 lance-arrow-scalar(用于极值 ArrowScalar 表示),开发依赖则包含 proptest、rstest 与 arrow-select,说明该模块的正确性由参数化测试与属性测试双重保障。

快速上手:三步完成统计

StatisticsAccumulator 的使用遵循"创建 → 更新 → 产出"三步流程,README 给出了最小可运行示例:

use arrow_array::{Int32Array, ArrayRef};
use lance_arrow_stats::StatisticsAccumulator;
use arrow_schema::DataType;
use std::sync::Arc;

let mut acc = StatisticsAccumulator::new(&DataType::Int32);

let batch: ArrayRef = Arc::new(Int32Array::from(vec![Some(3), None, Some(1), Some(4)]));
acc.update(&batch).unwrap();

let stats = acc.finish();
assert_eq!(stats.null_count, 1);

这段代码背后的调用链(对应 rust/arrow-stats/src/lib.rs)依次完成:

  1. StatisticsAccumulator::new(&DataType::Int32)——按目标类型初始化内部计数。构造时即根据类型预设字段形态:List 系类型将 item_nulls 置为 Some(0),可含 NaN 的浮点类型(含浮点元素的列表)将 nan_count 置为 Some(0),其余类型对应字段为 None;
  2. update(&batch)——注入一个数组批次。若数组类型与累加器声明的类型不一致,返回 ArrowError::InvalidArgumentError;若数组为空则直接返回 Ok(()),不做任何累计;
  3. finish()——消费累加器,产出不可变的 Statistics 快照。

多次调用 update 会跨批次持续累计:例如先更新 [5, 3],再更新 [Some(1), None, Some(7)],最终 min 为 1、max 为 7、null_count 为 1(对应源码中的 test_multiple_updates 用例)。

六类统计项及其语义

StatisticsAccumulator 最终产出的 Statistics 快照(定义见 rust/arrow-stats/src/lib.rs)包含六项统计,README 中的官方表格如下:

统计项 说明
min 非空、非 NaN 的最小值(ArrowScalar)
max 非空、非 NaN 的最大值(ArrowScalar)
null_count 空值总数
nan_count NaN 总数(仅浮点类型与浮点列表类型)
item_nulls 列表条目内部的空值数(仅列表类型)
buffer_memory Arrow 缓冲区内存总字节数

其中三个字段的 Option 语义值得特别注意,它们是"按类型有无意义"设计的:

  • null_count 与 buffer_memory 对所有数据类型恒有意义,始终参与累计;
  • nan_count 仅对浮点类型(Float16/32/64)及"元素为浮点的列表类型"为 Some,其余类型为 None;
  • item_nulls 仅对列表系类型为 Some,其余类型为 None。

buffer_memory 的累计方式是调用 array.get_buffer_memory_size() 逐批累加(见 rust/arrow-stats/src/lib.rs),可用于估算某列/某页数据在内存中的实际占用,为缓存与内存预算提供依据。

支持的数据类型与边界行为

完整支持的类型清单

README 列出了受支持的类型族,源码的 find_min_max_indices 分发逻辑(见 rust/arrow-stats/src/lib.rs)与之一一对应:

类型族 具体类型
数值(整数) Int8 – Int64、UInt8 – UInt64
数值(浮点) Float16、Float32、Float64
数值(十进制) Decimal128、Decimal256
时间 Date32、Date64、Time32(Second/Millisecond)、Time64(Microsecond/Nanosecond)、Timestamp(各时间单位)、Duration(各时间单位)
布尔 Boolean
字符串 Utf8、LargeUtf8
二进制 Binary、LargeBinary
列表 List、LargeList、FixedSizeList(对条目递归计算统计)

值得注意:README 的表格未列 Decimal128/256,但当前仓库源码 rust/arrow-stats/src/lib.rs 明确支持这两种十进制类型,且 test_rstest_primitives 中带 precision/scale 的十进制用例验证了 min/max 输出(如 Decimal128(10, 2) 下 300/100/200 对应 1.00/3.00)。此外 rust/arrow-stats/src/lib.rs 的模块文档还说明字符串视图与二进制视图类型同样受支持。

列表类型:递归下钻

对于 List、LargeList、FixedSizeList,累加器不会把列表整体当作一个标量处理,而是:

  • 跳过整个列表为空的条目,将其计入外层 null_count;
  • 展开非空列表,对其内部条目逐项递归统计:叶子值参与 min/max 计算,条目内的空值累计进 item_nulls;
  • 若列表条目本身又是列表(嵌套列表),继续递归下钻,直到叶子类型(见 update_item 的递归实现,rust/arrow-stats/src/lib.rs)。

test_nested_list 用例对此做了完整验证:数组 [[[1, 2], [3]], null, [[null, 5], null, [6]]] 的统计结果为 min=1、max=6、null_count=1(外层空列表)、item_nulls=2(1 个空 int32 + 1 个空内层列表)。

特殊编码与不支持的类型的降级行为

README 明确指出:

Dictionary, run-end encoded, and view types are accepted but min/max will be None.

即字典编码、run-end 编码以及(当前实现中的)部分视图类型虽然能被 update 接受,但不会产出 min/max(返回 None);nan_count 除非底层是浮点类型否则同样为 None。而Struct 类型当前不被支持(模块文档见 rust/arrow-stats/src/lib.rs),但降级策略仍然有效:null_count 与 buffer_memory 照常累计(test_unsupported_type_tracks_null_count_and_memory 验证了 struct 数组 3 个空值被正确计数、缓冲区内存大于 0)。这种"极值缺省、计数不缺席"的设计,保证了存储层在遇到特殊类型时仍能拿到一部分可用的统计信息。

字符串与二进制的极值比较

字符串与二进制类型的 min/max 采用逐字节二进制比较(源码走 find_extrema_bytes! 宏,见 rust/arrow-stats/src/lib.rs)。模块文档对此给出了一个容易踩坑的说明:

Binary comparison will be used for string types to calculate the min and the max. This works for ASCII but may be surprising for special characters. For example, "é" would sort after "z".

也就是说,对于纯 ASCII 文本(英文标识符、数值字符串、日志消息等)结果是符合直觉的;但一旦出现非 ASCII 字符(如带重音的 "é"),其结果与字典序/语言排序语义可能不同——"é" 会被排到 "z" 之后。设计查询条件时若依赖字符串极值做裁剪,需要知晓这一前提。

浮点极值:跳过 NaN,使用全序比较

浮点数组的极值统计有两个刻意设计(find_extrema_float! 宏,见 rust/arrow-stats/src/lib.rs):

  1. NaN 不参与 min/max,仅被计入 nan_count。因此 [1.0, NaN, 3.0] 的 min=1.0、max=3.0、nan_count=Some(1);若整个数组全是 NaN,则 min/max 均为 None;
  2. 比较采用 f64::total_cmp 这类全序比较(total_cmp),能够在 NaN 之外把 -0.0 与 0.0 区分开,与 ArrowScalar 的 Ord 实现保持一致,避免"负零"在极值比较中被吞掉。

NaN 计数本身由 rust/arrow-stats/src/nan.rs 的 count_nans 完成,它只对 Float16/32/64 逐元素调用 is_nan(),其余类型直接返回 0。而"该类型是否可能含 NaN"的判断由 can_have_nan 递归完成(rust/arrow-stats/src/lib.rs):浮点原始类型为 true,列表类型则递归检查其元素类型。这也解释了为何 List<Float32> 的 nan_count 是 Some 而非 None。

并行合并:多页/多文件统计的汇聚

在大数据场景下,统计通常按页(page)、按分区(partition)并行计算,最后再汇总。StatisticsAccumulator::merge 正是为此设计——同类型的两个累加器可以合并:

use lance_arrow_stats::StatisticsAccumulator;
use arrow_schema::DataType;

let mut a = StatisticsAccumulator::new(&DataType::Float32);
let mut b = StatisticsAccumulator::new(&DataType::Float32);
// ... update each with different batches ...
a.merge(&b).unwrap();

合并的语义(见 rust/arrow-stats/src/lib.rs):

  • 类型校验:双方 data_type 必须一致,否则返回 ArrowError::InvalidArgumentError(test_merge_type_mismatch 验证了 Int32 与 Float64 合并报错);
  • 计数相加:null_count、nan_count、item_nulls、buffer_memory 均为对应字段的加法;
  • 极值取优:min 取两者较小者,max 取两者较大者;若一方无极值,则继承另一方的极值;
  • 合并允许任意顺序调用,且与"一次性处理全量数据"结果等价——prop_merge_consistent_i32 属性测试验证了"数组切两半分别累计再合并"与"整数组一次累计"得到的 min/max/null_count 完全一致。

因此 merge 天然适配 Rayon/分布式框架下"各分区独立建累加器 → 归并结果"的编程模型。

完整 API 参考

除上述核心方法外,StatisticsAccumulator 还提供以下成员(全部见 rust/arrow-stats/src/lib.rs):

方法 签名 行为
new fn new(data_type: &DataType) -> Self 按类型创建累加器,初始化字段形态
data_type fn data_type(&self) -> &DataType 返回累加器声明的目标类型
update fn update(&mut self, array: &ArrayRef) -> Result<()> 注入一个批次;类型不匹配或处理失败时返回错误
finish fn finish(self) -> Statistics 消费自身并返回统计快照
statistics fn statistics(&self) -> Statistics 不消费自身,返回当前统计快照(可重复调用)
merge fn merge(&mut self, other: &Self) -> Result<()> 合并另一个同类型累加器
reset fn reset(&mut self) 将所有统计归零,保留类型与字段形态,可复用

finish 与 statistics 的区别是实战中的常见易错点:前者按值消费(self),调用后累加器不可再用;后者按引用借用,适合"边写数据边多次查询当前统计"的流式写入场景。reset 则支持累加器复用,例如在 ZoneMap 索引中每完成一个 zone 的处理就重置一次。

在 Lance 存储层中的真实落地

lance-arrow-stats 不是孤立的工具库,它直接支撑 Lance 的标量索引构建。

ZoneMap 索引(ZoneMap Processor)

在 rust/lance-index/src/scalar/zonemap.rs 中,ZoneMapProcessor 持有 StatisticsAccumulator,逐块(chunk)调用 process_chunk 驱动 statistics.update(array),在 finish_zone 时把统计快照转换为 ZoneMapStatistics 写入索引文件:

  • 对非嵌套类型,min/max/null_count/nan_count 全部落盘;其中 max 有一处特殊处理:若 nan_count > 0,zone 的 max 会被存成 NaN 标量(max_value_from_stats),以保持与 DataFusion 既有 zonemap 形状一致,同时让区间/等值裁剪在存在 NaN 时保持保守(不过度裁剪);
  • 对嵌套类型(List、Struct、Map 等),只保留 null_count,min/max 存为类型化空值;
  • null_count 与 nan_count 在落盘时被安全转换为 u32,超范围会报错。

这正是 README 所说"page-level statistics drive predicate pushdown"的最直接体现:ZoneMap 文件中的 min/max/null_count 正是查询规划器做页级裁剪的数据底座。

Bloom Filter 索引

在 rust/lance-index/src/scalar/bloomfilter.rs 中,BloomFilterProcessor 同样内嵌了一个可选的 StatisticsAccumulator(statistics: Option<StatisticsAccumulator>),在向分段 Bloom Filter(SBBF)插入键值的同时累计统计信息,作为索引元数据的补充。这说明该累加器在 Lance 标量索引族中是被复用的事实标准组件。

正确性保障:测试矩阵

该模块的测试覆盖非常立体(见 rust/arrow-stats/src/lib.rs):

  • 单元测试:空数组、全空值、单值、含空值、跨批次累计、类型不匹配报错、reset 复位、statistics 不消费、buffer_memory 累计与复位、列表的各种组合(空列表、空外层列表、空条目、嵌套列表、LargeList、多次更新、合并、重置)、非列表类型的 item_nulls=None 语义、Struct 的降级计数;
  • 参数化测试:rstest 覆盖 Int32/Int64/UInt32/UInt64/Float32/Float64/Decimal128/Decimal256 的极值输出;
  • 属性测试:proptest 验证随机数组下 min <= max、数组乱序/反转后极值与计数不变(shuffle 不变性)、以及"分片合并结果 == 整体一次计算结果"(merge 一致性)。

这些测试共同保证了:无论数据以何种顺序、何种批次划分流入,统计结果都是确定且可复现的。

使用边界与注意事项

综合 README 与源码,使用时有几点需要牢记:

  1. 类型必须严格一致:update 与 merge 都做严格类型校验,Int32 累加器收到 Float64 数组会直接报错,不能隐式转换;
  2. 字符串极值是字节序:非 ASCII 字符可能产生反直觉排序(如 "é" > "z"),做范围裁剪查询时注意前提;
  3. NaN 语义:NaN 不进 min/max,只进 nan_count;全 NaN 数组的极值为 None。ZoneMap 落盘时存在 NaN 的 zone 其 max 存为 NaN 以保守裁剪;
  4. 特殊编码降级:字典、run-end 编码及部分视图类型的极值为 None;Struct 当前不支持(仅计数不产极值);
  5. buffer_memory 的语义:它统计的是 Arrow 数组 get_buffer_memory_size() 的字节和,可用于内存预算与页面大小估算,而非存储压缩后的磁盘占用。

结语

lance-arrow-stats 以极简的依赖与 API 设计,撑起了 Lance 列式存储层中"页级统计 → 谓词下推"这条关键链路:统一的 StatisticsAccumulator 在写入与索引构建阶段流式累计六类统计,merge 让并行计算与汇聚成为可能,reset 支持索引 zone 的逐个复用,而 ZoneMap 与 Bloom Filter 两个真实使用者则证明了其工程价值。若你需要在自有 Arrow 生态项目中实现列级裁剪、缓存预算或数据画像功能,这个模块的 API 形态与边界处理(尤其是 NaN、列表递归与类型降级)本身就是一份高质量的设计参考。

登录后查看全文
lance