首次使用Apache Parquet遇类型错误：为何不兼容Pandas所有数据类型？

嘿，我完全懂你刚接触Parquet时遇到这种类型错误的困惑——当初我第一次踩这个坑的时候也纳闷“Parquet不是号称兼容Pandas吗？”，其实这里面确实有几个容易被忽略的关键点，咱一步步来拆解：

为什么会出现类型错误？ #

Parquet和Pandas的类型系统并不是完全1:1对应的，核心原因有这几个：

• 底层类型标准不同：Parquet基于Apache Arrow的类型规范，而Pandas有不少自己独有的扩展类型，比如带时区的datetime64[ns, tz]、可空整数Int64、某些特殊的categorical类型，这些在早期Parquet的支持里是有局限的。
• 存储引擎的差异：Pandas写Parquet有pyarrow和fastparquet两个常用引擎，它们对小众dtype的支持程度不一样。比如fastparquet对可空整数的兼容就不如pyarrow，某些场景下会直接报错。
• 版本不匹配：旧版本的Pandas（比如1.0之前）和Parquet相关库（pyarrow/fastparquet）搭配时，会存在类型映射的bug，比如可空整数类型是Pandas 1.0才引入的，旧版本根本没法和Parquet兼容。

怎么解决？ #

1. 先定位问题列 #

先把你的数据类型打印出来，看看哪一列是“罪魁祸首”：

print(df.dtypes)

重点关注带时区的时间列、可空整数列、object类型里混存不同数据的列，这些是高频出错点。

2. 针对不同类型做适配 #

• 带时区的datetime：如果业务允许，可以先去掉时区再存储；如果必须保留时区，就用pyarrow引擎（确保pyarrow版本≥0.17）：

  # 方案1：去掉时区
  df['time_col'] = df['time_col'].dt.tz_localize(None)
  # 方案2：用pyarrow保留时区存储
  df.to_parquet('data_with_tz.parquet', engine='pyarrow')
  

• 可空整数Int64：换成pyarrow引擎存储，或者如果业务允许，临时转成float64（不推荐，会丢失整数语义）：

  df.to_parquet('data.parquet', engine='pyarrow')
  

• 特殊categorical类型：确保分类的类别是Parquet支持的类型（比如字符串、数字），避免混合类型的分类值，必要时可以先把分类列转成字符串列再存储。

3. 指定存储引擎并更新库版本 #

优先尝试用pyarrow引擎，它对Pandas扩展类型的支持更完善；同时把相关库都更到最新稳定版，避免版本兼容问题：

pip install --upgrade pandas pyarrow fastparquet

如果能补充具体的报错信息和df.dtypes的输出，还能更精准地定位问题，但按照上面的步骤，大部分常见的类型不兼容问题都能解决。

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