Parquet文件中pandas元数据作用及保留必要性咨询

1. pandas专属元数据的实用价值 #

Parquet原生schema只覆盖了通用列式存储的基础信息，pandas额外写入的专属元数据核心作用是实现DataFrame的无损读写还原，具体价值点如下：

• 解决扩展类型的映射问题：pandas很多特有数据类型是Parquet原生schema不支持的，比如带时区的时间类型、分类类型（Category）、周期类型（Period）、可空数值类型（Int64/BooleanDtype等支持NaN的扩展类型），如果没有这部分元数据，读回时这些类型会自动降级：分类类型变普通字符串、带时区时间丢失时区信息、可空整数变浮点型，和写入时的类型完全不一致。
• 完整还原索引结构：Parquet本身没有DataFrame“索引”的概念，不管是普通单索引、多级索引、还是默认的范围索引，都存在pandas专属元数据里。如果丢失这部分元数据，读文件时原有索引会被识别成普通数据列，甚至范围索引直接被丢弃，读出来的DataFrame会默认生成从0开始的整数索引，和原数据结构对不上。
• 还原复杂表结构：Parquet原生只支持扁平的单列名，如果你的DataFrame用了多级列名（MultiIndex表头），这部分嵌套结构只能靠pandas元数据存储，没有的话读回来会变成拼接后的扁平字符串列名。另外列的顺序、object类型列的实际存储类型（是纯字符串还是混合类型）也靠这部分元数据标记，避免读入时类型推断出错。
• 提升大文件读取效率：没有元数据做类型映射的话，pandas读Parquet时需要扫描部分数据块做类型推断，大文件场景下会额外增加不少读取耗时，有元数据可以直接按映射构造列类型，跳过推断步骤。

2. 写入自定义业务元数据时是否需要保留原有pandas元数据 #

除非你能100%确定这个Parquet文件之后永远不会用pandas读取，也不需要还原成写入时的原始DataFrame结构，否则一定要保留原有pandas元数据。

• 两者完全不冲突：pandas的专属元数据是存在Parquet页脚元数据区一个固定的pandas键下，你写自定义业务元数据时，只需要新增自己的业务键值对即可，不要覆盖或删除pandas键对应的内容，两边可以共存。
• 保留成本极低：pandas元数据的体积通常只有几KB，相对于Parquet文件本身的大小几乎可以忽略，不会带来额外的存储开销。
• 错误操作的代价很高：如果误删了pandas元数据，之后用pandas读文件时很容易出现类型错乱、索引丢失、多级表头解析失败等问题，排查成本很高。

如果是用pandas原生API写入自定义元数据，直接更新DataFrame的attrs属性即可，写入时会自动保留原有pandas元数据，同时把自定义元数据写到文件里，示例代码：

import pandas as pd

# 构造示例数据
df = pd.DataFrame({
    "user_id": pd.array([1,2,None], dtype="Int64"),
    "user_level": pd.Categorical(["v1", "v2", "v3"])
})

# 追加业务自定义元数据
df.attrs.update({
    "biz_line": "电商用户域",
    "data_level": "公共明细层",
    "etl_dt": "2024-05-20"
})

# 写入Parquet，原有pandas元数据会自动保留
df.to_parquet("./user_data.parquet")

如果你的文件是专门给Spark、ClickHouse等非pandas引擎消费的，完全不需要考虑pandas读入的兼容性，也可以选择删除pandas元数据缩减一点点文件体积，但绝大多数场景下都不建议这么做。

注意：不要手动修改pandas键下的元数据内容，这部分是pandas内部维护的序列化结构，不同版本的格式可能存在差异，手动篡改很容易导致文件无法正常读取。

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