PyArrow读写Parquet文件教程详解

本文深入解析了使用 PyArrow 读写 Parquet 文件时的典型实战陷阱与精准应对策略：从因文件损坏或截断导致的 `ArrowInvalid: Unable to infer schema` 报错排查，到利用 `parquet-tools` 验证元数据、规避无效分区参数误用，再到压缩配置失效引发的内存暴涨与性能下降问题，均给出可立即落地的诊断步骤和版本兼容性提醒——帮你避开“看似正常却静默失败”的坑，在数据工程实践中真正用稳、用准 PyArrow。

pyarrow.read_parquet 读取失败的常见报错和应对

pyarrow.read_parquet 报错 ArrowInvalid: Unable to infer schema，大概率是文件本身不完整或被截断（比如写入中途崩溃、网络中断上传未完成）。Parquet 是列式格式，头部有 schema 元数据，缺了就无法解析。

• 检查文件大小是否明显偏小（比如几百字节），用 ls -lh 或 os.path.getsize 快速确认
• 用 parquet-tools 命令行工具验证：运行 parquet-tools meta your_file.parquet，若报错或无输出，基本可判定损坏
• 不要尝试用 try/except 吞掉这个错误后强行读——read_parquet 不支持跳过坏块，它要么全读，要么失败

write_table 写 Parquet 时分区字段没生效？检查参数位置

分区功能靠 partition_cols 参数触发，但它只在写入目录路径时有效；如果目标是单个文件（如 "data/part-001.parquet"），传 partition_cols 完全被忽略，且不报错。

• 确保 where 是目录路径，例如 "./output/"，而不是带 .parquet 后缀的文件名
• 分区列必须是 table 的列之一，且类型需支持字典编码（string、int 常见，float 或含 None 的列可能失败）
• 默认使用 Hive 风格分区（year=2023/month=04/），如需自定义分隔符或格式，得自己预处理列值再建子目录，pyarrow 不提供钩子

内存暴涨或写入极慢？关掉 compression 或换 codec

默认 compression="snappy" 对 CPU 友好但压缩率一般；设成 "zstd" 或 "lz4" 能减体积，但某些旧版 PyArrow 会因编译时没启用对应库而静默回退到 None，导致文件变大、读写变慢。

• 先查实际生效的压缩方式：parquet-tools meta file.parquet | grep Compression
• 小数据量（<10MB）直接设 compression=None，省去编解码开销，实测常比 snappy 快 2–3 倍
• 如果要用 zstd，确保安装时带了支持：pip install pyarrow[zstd]，否则运行时不报错，但写出来是未压缩的

用 pandas.read_parquet 读却提示 ArrowNotImplementedError？版本不匹配

这是典型的 PyArrow 和 pandas 版本协同问题。pandas 2.0+ 内部大量依赖 PyArrow 行为，但若 PyArrow < 12.0.0，某些新 Parquet 文件特性（如 INT96 时间戳、嵌套 struct）就会触发 ArrowNotImplementedError: Unsupported logical type。

• 运行 import pyarrow as pa; print(pa.version)，低于 12.0.0 就升级：pip install --upgrade pyarrow
• 不要只升 pandas：pandas 2.2.x 要求 PyArrow ≥ 12.0.0，降 pandas 版本反而容易引发更隐蔽的 dtype 转换错误
• 如果必须用旧 PyArrow（如公司镜像限制），读取前加 use_nullable_dtypes=False，避免 pandas 尝试映射新逻辑类型

PyArrow 处理 Parquet 时，很多问题不是代码写错了，而是文件状态、参数作用域或版本边界没对齐。尤其注意：分区只对目录有效、压缩行为要实测验证、版本号得手动核对——这些点不看文档根本猜不到。

以上就是《PyArrow读写Parquet文件教程详解》的详细内容，更多关于的资料请关注golang学习网公众号！