Parquet单文件能否突破2.1GB？fastparquet写入大文件报错求助

核心结论 #

这不是Parquet格式的固有设计限制，问题出在fastparquet库的底层C扩展实现中——它错误地用int32类型处理文件偏移量，导致文件大小超过2.1GB（2^31-1字节）时触发溢出。

问题细节 #

当使用fastparquet持续追加DataFrame到单个Parquet文件，文件大小突破2147483647字节阈值后，会抛出如下错误：

OverflowError: value too large to convert to int
Exception ignored in: 'fastparquet.cencoding.write_thrift'

异常被库内部忽略，无法直接获取完整堆栈，但可以明确是文件偏移量超出int32范围导致的。

为什么Parquet格式本身没问题？ #

Parquet官方的Thrift定义中，与文件偏移量相关的字段（比如FileMetaData里的file_offset、RowGroup里的total_byte_size等）均采用i64（int64）类型，理论上单个Parquet文件支持的大小上限可达EB级，完全能容纳40GB的数据集。

解决方案 #

1. 临时规避方案

   • 拆分数据集：将40GB数据拆分为多个小于2GB的DataFrame，分别写入独立的Parquet文件，后续可通过pyarrow或fastparquet的合并读取功能统一处理。
   • 使用分区表：按时间、类别等维度对数据做分区，每个分区生成单独的Parquet文件，既避免单文件过大，还能提升后续查询的效率。

2. 修复库本身问题

   • 升级fastparquet到最新版本：查看官方更新日志，新版本大概率已修复int32偏移量的溢出bug。
   • 手动修改代码（若版本未修复）：找到fastparquet的cencoding模块中处理Thrift写入的逻辑，将偏移量的存储类型从int32改为int64，重新编译扩展即可。

内容的提问来源于stack exchange，提问作者Alex Pilafian