QuestDB 仓库内 parquet2 库指南:用 Rust 安全高效地读写 Apache Parquet
QuestDB 仓库内 parquet2 库指南:用 Rust 安全高效地读写 Apache Parquet
本指南以 core/rust/parquet2 仓库自带的官方 Guide(guide/src/README.md)为骨架,结合仓库源码与示例展开。parquet2 是一个纯 Rust 实现的 Apache Parquet 读写库,被 QuestDB(一款高性能开源时序数据库)用于其 Rust 侧(qdbr)的 Parquet 导入导出。读完本文,你将掌握:如何同步/异步读取 Parquet 元数据、理解文件的分层结构(Row Group → Column Chunk → Page)、用迭代器或流式接口读取压缩页面并完成解压—解码—反序列化,以及如何利用行组统计信息、布隆过滤器、列索引与 Sidecar 元数据做查询下推(pushdown)优化。
IO-bound 与 CPU-bound:贯穿全库的设计视角
Guide 开篇提出了两个贯穿全文的核心概念:
- IO-bound 操作:执行磁盘读取或网络调用(例如从 S3 拉取数据),对应 Guide 中的 "read"、"write"、"seek";
- CPU-bound 操作:执行计算,对应 "decompress"(解压)、"compress"(压缩)、"deserialize"(反序列化)等。
Guide 给出的关键经验法则是:IO-bound 操作通常适合用绿色线程(green threads)并行化,而 CPU-bound 操作不适合。这一区分决定了 parquet2 的 API 形态——同一个功能往往同时提供 sync 与 async(基于 tokio)两套入口,例如元数据读取就有 read_metadata 与 read_metadata_async 两个函数,页面读取则有 get_page_iterator 与 get_page_stream。
值得一提的是,该库在 lib.rs 中声明了 #![forbid(unsafe_code)],即整个库不允许任何 unsafe 代码,这是其"安全(safely)读写 Parquet"承诺的源码级体现。
读取元数据:一切读取的起点
Guide 明确指出:Parquet 文件读取的起点是文件末尾(footer)处的元数据。元数据不包含任何数据,但它携带了读取、解压、解码与反序列化数据所需的全部信息。
同步读取
parquet2::read::read_metadata 用于同步读取,仓库示例 examples/read_metadata.rs 展示了最简用法:
use parquet2::read::read_metadata;
let path = &args[1];
let mut reader = std::fs::File::open(path)?;
let metadata = read_metadata(&mut reader)?;
println!("{:#?}", metadata);
其底层实现位于 src/read/metadata.rs:先通过 stream_len 获取文件总大小,再调用 read_metadata_with_size 从文件尾部定位 footer。read_metadata_with_size 允许在已知文件大小时跳过一次 IO,适合在远程存储场景下复用已有的文件长度信息。
异步读取
parquet2::read::read_metadata_async 对应异步版本,它其实是 src/read/mod.rs 中对 stream::read_metadata 的重导出(re-export)。示例 examples/read_metadata_async/src/main.rs 以 tokio::fs 为例:
use async_compat::Compat;
use parquet2::{error::Result, read::read_metadata_async};
use tokio::fs;
#[tokio::main]
async fn main() -> Result<()> {
let mut reader = Compat::new(fs::File::open("path.parquet").await?);
let metadata = read_metadata_async(&mut reader).await?;
// metadata
println!("{:#?}", metadata);
Ok(())
}
注意 Compat 包装的作用:让同步的 AsyncRead + AsyncSeek 实现兼容 parquet2 异步接口的 trait 约束,这在你对接自研异步 IO(如对象存储 SDK)时是常见做法。两种方式返回的都是 FileMetaData。
文件级常量
lib.rs 中定义了几个值得了解的文件格式常量:PARQUET_MAGIC = "PAR1"(4 字节魔数)、FOOTER_SIZE = 8(footer 长度字段 + 魔数)、DEFAULT_FOOTER_READ_SIZE = 64 * 1024——首次读取时默认从文件末尾读取 64KB 以解析 footer,这也是"元数据位于文件末尾"这一设计在工程上的具体落地。
文件分层结构:Schema、Row Group、Column Chunk 与 Page
Guide 用一段精炼的描述给出 Parquet 格式的层级模型,这是理解后续所有 API 的地图:
- 一个文件(file)拥有一个包含列(columns)的 schema 以及数据;
- 文件中的数据被划分为若干 row groups(行组);
- 每个 row group 包含多个 column chunks(列块);
- 每个 column chunk 包含多个 pages(页);
- 每个 page 包含多个值。
除 page 外,以上所有实体的元数据都已包含在 FileMetaData 中——page 级元数据需要额外从文件中读取(见下文"列索引与页索引")。
Guide 随后以单列读取为例,演示如何从 FileMetaData 中取出某个 column chunk 的元数据(见 examples/read_metadata.rs):
let row_group = 0;
let column = 0;
let columns = metadata.row_groups[row_group].columns();
let column_metadata = &columns[column];
这里的 column_metadata: &ColumnChunkMetaData 就是后续页面迭代、统计信息、布隆过滤器与索引读取的输入参数。
读取页面数据:解压、解码与反序列化
拿到 ColumnChunkMetaData 后,就可以读取该列块中的页面了。Guide 把读取流程明确拆为三步:解压(decompress)→ 解码(decode)→ 反序列化(deserialize)。
第一步:获取压缩页面的迭代器 / 流
同步场景使用 parquet2::read::get_page_iterator,其签名与实现见 src/read/mod.rs:
use parquet2::read::get_page_iterator;
let pages = get_page_iterator(column_metadata, &mut reader, None, vec![], 1024 * 1024)?;
参数依次为:列块元数据、可读可定位(Read + Seek)的 reader、可选的页面过滤器 PageFilter(默认对所有页面放行)、可复用的 scratch buffer,以及 max_page_size(示例中为 1MB)——后两者用于控制内存复用与页面大小上限,避免为每个页面重复分配缓冲区。
异步场景则使用 parquet2::read::get_page_stream,定义于 src/read/page/stream.rs,返回 impl Stream<Item = Result<CompressedPage>>,可直接接入 tokio / futures 的流式管线。
两者产出的都是 CompressedDataPage。Guide 特别提醒:这些页面持有数据,可能占用大块(压缩后的)内存,因此处理完应及时释放或复用缓冲区。
第二步:解压
解压通过 parquet2::read::decompress 完成,实现位于 src/read/compression.rs,其将压缩页面连同可复用的 Vec<u8> 一起传入,返回解压后的 Page。示例中的循环同时处理字典页与数据页(examples/read_metadata.rs):
let mut decompress_buffer = vec![];
let mut dict = None;
for maybe_page in pages {
let page = maybe_page?;
let page = parquet2::read::decompress(page, &mut decompress_buffer)?;
match page {
Page::Dict(page) => {
// 第一个页面可能是字典页,需要按目标内存格式反序列化字典
dict = Some(page);
}
Page::Data(page) => {
let _array = deserialize(&page, dict.as_ref())?;
}
}
}
这段代码揭示了读取带字典编码列时的标准模式:首个页面可能是 Page::Dict 字典页,需先反序列化并暂存,供后续 Page::Data 数据页解码引用。
第三步:解码与反序列化
Guide 指出,解码与反序列化通常在同一步完成,因为具体做法高度依赖你目标内存格式的选择,因此它只讲解如何把页面缓冲区拆解为各个组成部分。示例中的 deserialize 函数(examples/read_metadata.rs)展示了关键原语:
use parquet2::page::{split_buffer, DataPage, DictPage, Page};
fn deserialize(page: &DataPage, dict: Option<&DictPage>) -> Result<()> {
// 将数据缓冲区拆分为重复级别、定义级别和值
let (_rep_levels, _def_levels, _values_buffer) = split_buffer(page)?;
// 按物理类型 × 编码 × 是否有字典 分派解码
match (
page.descriptor.primitive_type.physical_type,
page.encoding(),
dict,
) {
(PhysicalType::Int32, Encoding::PlainDictionary | Encoding::RleDictionary, Some(_dict_page)) => {
// 带字典的 plain 编码页,_dict_page 可按物理类型 downcast
todo!()
}
(PhysicalType::Int32, Encoding::Plain, None) => {
// plain 编码页
todo!()
}
_ => todo!(),
}
}
这里有几个值得展开的要点:
split_buffer把数据缓冲区切成三段:重复级别(repetition levels)、定义级别(definition levels)与值(values)。重复级别用于还原嵌套/列表结构,定义级别用于还原可选列的空值位置;- Guide 举例说明目标格式决定了需要解码哪些部分:例如读取到 Apache Arrow 时,由于定义级别的表示与 Arrow 一致,往往不需要解码定义级别;但由于 Arrow 支持无符号整数而 Parquet 只接受(可能经过编码的)
i32/i64,某些值仍需反序列化转换; - 分派依据是"物理类型 × 页面编码 × 是否有字典"三元组,这正是不同编码(Plain、Dictionary、RLE 等)在解码路径上的分支点。
Guide 还建议:如需参考"反序列化到简单内存格式"的完整实现,可查阅本仓库的集成测试(位于 tests/ 目录);如需 Apache Arrow 目标格式的实现,可参考 arrow2 项目。仓库内的实际使用可以参考 qdbr 模块下的解码器实现(如 src/parquet_read),那里体现了把上述三步嵌入真实查询管线的工程做法。
行组统计信息(Row Group Statistics):过滤下推的第一道闸门
Guide 指出,row group 的元数据可以携带统计信息,用于下推过滤操作——即在读取页面之前,先根据统计信息跳过不可能命中的行组。
统计信息按列的物理类型编码,以 trait 对象 Arc<dyn Statistics> 表示,可通过 Statistics::physical_type() 获知具体类型后再 downcast。示例(examples/read_metadata.rs)以 i32/i64 为例:
if let Some(maybe_stats) = column_metadata.statistics() {
let stats = maybe_stats?;
use parquet2::statistics::PrimitiveStatistics;
match stats.physical_type() {
PhysicalType::Int32 => {
let stats = stats
.as_any()
.downcast_ref::<PrimitiveStatistics<i32>>()
.unwrap();
let _min: i32 = stats.min_value.unwrap();
let _max: i32 = stats.max_value.unwrap();
let _null_count: i64 = stats.null_count.unwrap();
}
PhysicalType::Int64 => { /* 同样的 downcast,类型为 i64 */ }
_ => todo!(),
}
}
PrimitiveStatistics<T> 提供 min_value、max_value、null_count 以及 distinct_count 等字段;对布尔、字节串等类型则分别有 BooleanStatistics、BinaryStatistics、FixedLenBinaryStatistics 等实现(见 src/statistics/ 目录)。拿到 min/max 后,查询引擎便可以在扫描前判断"该行组内不可能存在满足条件的值",从而跳过整个行组。
布隆过滤器(Bloom Filter):判断"元素一定不在列块中"
column chunk 的元数据还可能携带布隆过滤器位图,用于把过滤下推进一步细化到"元素不在列块中"的判定。相关代码位于 src/bloom_filter/ 模块(由 bloom_filter feature 门控)。
Guide 与示例(examples/read_metadata.rs)给出的用法分三步:读取位图 → 对查询值做哈希 → 判断哈希是否在位图中:
let mut bitset = vec![];
bloom_filter::read(column_metadata, &mut reader, &mut bitset)?;
if !bitset.is_empty() {
// 假设查询引擎产出了过滤条件 "column 0" == 100i64(并已确认该列为 i64)
let value = 100i64;
// 哈希该值
let hash = bloom_filter::hash_native(value);
// 判断哈希是否在位图中
let _in_set = bloom_filter::is_in_set(&bitset, hash);
// 若返回 false,可跳过整个行组(没有任何元素命中该过滤条件)
// 若返回 true,元素"可能"在行组中,通常不能跳过
}
底层实现细节:
- src/bloom_filter/read.rs 根据
column_metadata中的bloom_filter_offset定位位图并读入bitset; - src/bloom_filter/hash.rs 提供
hash_native(对原生数值类型,基于 xxh64 哈希)与hash_byte(对字节序列); - src/bloom_filter/split_block.rs 实现
is_in_set:按 Split Block Bloom Filter 的块式结构,对 8 个 salt 分别计算掩码并检查对应 4 字节字。
布隆过滤器的语义是"假阳性可以、假阴性不可能":返回 true 只能说明元素可能存在(需要继续扫描),返回 false 则能百分之百确认元素不存在——这正是它可以安全用于下推跳过的数学基础。
列索引与页索引(Column & Page Indexes):精确到页的 IO 裁剪
Guide 指出,column chunk 的元数据中还可以包含列索引(column indexes)与页索引/偏移索引(offset indexes),用于在读取(IO)页面时下推过滤。其中列索引记录每个页面的 min/max 统计,偏移索引记录每个页面在文件中的位置,二者配合可实现只读取可能命中过滤条件的页面,从而裁剪 IO 量。
示例(examples/read_metadata.rs)同时展示了两种索引的读取:
use parquet2::read;
// 读取所有列的列索引:每个页面的最小/最大值,可用于跳过页面
let index = read::read_columns_indexes(&mut reader, columns)?;
println!("{index:?}");
// 读取偏移索引:每个页面的位置
let pages = read::read_pages_locations(&mut reader, columns)?;
println!("{pages:?}");
对应实现位于 src/read/indexes/read.rs:
read_columns_indexes返回Vec<Box<dyn Index>>,先根据各列元数据计算出所有列索引的偏移与长度,一次性 seek 并读入;read_pages_locations返回Vec<Vec<PageLocation>>,给出每个页面(含字典页)的偏移量、压缩长度与行数区间。
有了页级 min/max(列索引)+ 页位置(偏移索引),读取路径就可以在调用 get_page_iterator / get_page_stream 时传入 PageFilter(src/read/mod.rs),只保留可能包含目标数据的页面,实现"按页跳过"的细粒度下推,这是 Parquet 谓词下推技术的最后一公里。
Sidecar:多文件场景下的合并元数据
写入多个 Parquet 文件(例如按分区写出 part-*.parquet)时,业界常见做法是维护一个 Sidecar 元数据文件,把所有文件的元数据(含统计信息)合并存放,以便查询引擎只读一个小文件就能完成全局规划,而无需逐个打开数据文件读 footer。
parquet2 对该场景提供了开箱即用的支持,完整示例见 examples/write_sidecar.rs,核心逻辑如下:
use parquet2::{
metadata::SchemaDescriptor,
schema::types::{ParquetType, PhysicalType},
write::{write_metadata_sidecar, FileWriter, Version, WriteOptions},
};
// 10 个文件共享同一个 schema
let schema = SchemaDescriptor::new(
"schema".to_string(),
vec![ParquetType::from_physical("c1".to_string(), PhysicalType::Int32)],
);
let mut metadatas = vec![];
for i in 0..10 {
let relative_path = format!("part-{i}.parquet");
let mut writer = FileWriter::new(
std::io::Cursor::new(vec![]),
schema.clone(),
WriteOptions {
write_statistics: true,
version: Version::V2,
bloom_filter_fpp: 0.01, // 布隆过滤器假阳性率
},
None,
);
// writer.write(row_group) 写入行组
writer.end(None)?;
let (_, mut metadata) = writer.into_inner_and_metadata();
// 关键一步:把数据文件的相对路径写回各 column chunk
metadata.row_groups.iter_mut().for_each(|row_group| {
row_group.columns.iter_mut().for_each(|column| {
column.file_path = Some(relative_path.clone())
})
});
metadatas.push(metadata);
}
// 合并所有元数据的行组
let first = metadatas.pop().unwrap();
let sidecar = metadatas.into_iter().fold(first, |mut acc, metadata| {
acc.row_groups.extend(metadata.row_groups.into_iter());
acc
});
// 写入独立的 sidecar 文件
let mut writer = std::io::Cursor::new(vec![]);
write_metadata_sidecar(&mut writer, &sidecar)?;
这段示例同时展示了 parquet2 写入侧的几个重要 API 与参数:
SchemaDescriptor::new定义顶层 schema(示例为单列c1: Int32);FileWriter::new配合WriteOptions控制写入行为,其中write_statistics: true决定是否生成行组统计信息,version: Version::V2指定格式版本,bloom_filter_fpp: 0.01设定布隆过滤器目标假阳性率;writer.end(None)负责写入 footer(数据文件本体),into_inner_and_metadata取出已写入的数据与FileMetaData;- 合并的关键在于把各数据文件的相对路径写回
column.file_path,这样 sidecar 中的 column chunk 才能定位到真实数据所在文件; - 最后用
write_metadata_sidecar把合并后的FileMetaData单独写出,形成标准的_metadata风格文件,供查询引擎一次性读取。
小结:一条完整的读取管线
把 Guide 的各部分串联起来,基于 parquet2 读取一个 Parquet 文件的完整管线是:
- 读 footer 元数据(
read_metadata/read_metadata_async,src/read/metadata.rs); - 利用行组统计(src/statistics/)与布隆过滤器(src/bloom_filter/)跳过不可能命中的行组;
- 利用列索引与偏移索引(src/read/indexes/read.rs)按页裁剪 IO;
- 用
get_page_iterator(src/read/mod.rs)或get_page_stream(src/read/page/stream.rs)取得压缩页面; - 用
decompress(src/read/compression.rs)解压,再经split_buffer拆分级别/值缓冲区并按物理类型与编码完成解码反序列化(examples/read_metadata.rs); - 多文件场景下,通过 Sidecar 合并元数据(examples/write_sidecar.rs)实现全局规划。
进一步探索仓库:可对照完整示例 examples/read_metadata.rs 与 examples/write_sidecar.rs 动手运行;想了解 parquet2 在真实数据库中的落地方式,可阅读 qdbr 的 parquet_read 与 parquet_write 模块,以及配套的集成测试(如 tests/decode_primitives.rs)。