PyArrow Dataset API 使用教程

本文深入解析了PyArrow Dataset API使用中的三大典型陷阱：为何`read_table()`常返回空结果（根源在于默认仅识别Hive分区路径或含_metadata文件，裸Parquet需显式指定`format="parquet"`或`partitioning=False`）、filter为何完全不生效（必须使用`pyarrow.compute`构建表达式，如`pc.match_substring()`而非SQL语法），以及`scan().to_table()`为何显著慢于`read_table()`（因引入执行计划调度开销）。掌握这些底层机制差异，能帮你避开90%的Dataset误用坑，真正释放其在大规模数据读取与过滤中的高效潜力。

为什么 dataset.read_table() 读出来是空的

常见现象：用 dataset.read_table() 加载 Parquet 目录后，len(table) 是 0，但文件明明存在、用 pyarrow.parquet.read_table() 单个文件却能读出数据。

根本原因是：Dataset 默认只识别符合 Hive 分区路径格式（如 year=2023/month=04/）或含 _metadata/_common_metadata 的目录；裸 parquet 文件列表不被自动发现。

• 确认是否用了 format="parquet" 显式指定（默认会尝试推断，但容易失败）
• 检查路径下是否有 _metadata 文件；没有就加 partitioning=False 或显式传 partitioning="hive"
• 如果只是几个独立 .parquet 文件，别用 dataset，直接用 pyarrow.parquet.read_table([f1, f2])

filter 参数写不对，完全不生效

dataset.filter 不是 SQL WHERE，它是基于 Arrow 计算表达式的逻辑树，不支持字符串模糊匹配、函数调用或列别名。

典型错误：ds.filter("col LIKE '%abc%'") 或 ds.filter(pc.field("col") == "val")（漏掉 pc 模块导入或写法错）。

• 必须导入 import pyarrow.compute as pc
• 写法只能是 pc.field("col") == "val"、pc.greater(pc.field("ts"), pc.scalar("2023-01-01"))
• 字符串匹配只能用 pc.match_substring()，不是 LIKE：pc.match_substring(pc.field("name"), "abc")
• filter 在 scan 阶段下推，但不会改变 schema；若字段不存在，运行时报 KeyError，不是静默跳过

scan() + to_table() 比 read_table() 慢很多

表面看都是读成 Table，但行为完全不同：read_table() 是“一次性全量加载+内存聚合”，scan().to_table() 是“先建执行计划+逐 batch 扫描+最后合并”，中间多一层计算图调度开销。

尤其在小数据集（read_table() 更快也更省内存。

• 用 scan() 的真实价值在于：需要复用 scan 对象做多次不同 filter/project、或接 to_reader() 流式消费、或配合 fragments 做自定义分片
• 如果只是“读完就处理”，优先用 read_table(filter=..., columns=[...])
• read_table(use_threads=True) 默认已开并行，不用额外配；但 scan() 的线程数需通过 use_threads 显式传给 to_table()

写入 dataset 时分区字段没进数据，反而变成目录名

分区字段不会自动保留在每张表的 column 里 —— 这是 Dataset 的设计约定：分区信息只存路径，不冗余进数据本身。

如果你需要分区列也在表中（比如后续要做 groupby 或 join），必须手动加回来。

• 写入时用 partitioning=pa.dataset.partitioning(...) 只控制目录结构，不影响 table schema
• 读取后想恢复分区字段，得用 ds.to_table(columns=["a", "b"], fragments=...) + 手动从 fragment.path 提取值再 concat
• 更稳妥的做法：写入前把分区列作为普通列保留，再用 existing_data_behavior="delete_matching" 配合 partitioning 控制目录，避免丢失语义

分区不是魔法，它省的是扫描 IO，不是数据建模成本。路径解析、类型对齐、空分区处理，都得自己兜底。

今天带大家了解了的相关知识，希望对你有所帮助；关于文章的技术知识我们会一点点深入介绍，欢迎大家关注golang学习网公众号，一起学习编程~