PyArrow与Parquet文件中Python枚举的序列化方案问询

原生序列化支持情况 #

PyArrow和Parquet不支持Python枚举（enum.Enum）的原生序列化。原因在于Python枚举是Python语言特有的类型，而Arrow/Parquet是跨语言的列式存储标准，没有定义与Python枚举直接对应的原生数据类型。直接序列化枚举对象要么会触发PyArrow类型不兼容错误，要么会存储无意义的对象字符串（如<Status.ACTIVE>），无法被其他Parquet阅读器正常解析。

高效且跨阅读器兼容的枚举编码方式 #

以下是几种兼顾存储效率和跨工具兼容性的可行方案：

1. 字符串直存（最简单兼容） #

将枚举的name或value（若为字符串类型）直接转换为字符串存储，对应Parquet的string类型。所有Parquet阅读器都能直接识别读取，无需额外处理。

示例代码：

from enum import Enum
import pyarrow as pa
import pyarrow.parquet as pq

class Status(Enum):
    ACTIVE = "active"
    INACTIVE = "inactive"
    PENDING = "pending"

# 转换枚举为字符串值
data = {"status": [s.value for s in [Status.ACTIVE, Status.INACTIVE, Status.PENDING]]}
table = pa.Table.from_pydict(data)
pq.write_table(table, "status_string.parquet")

2. 整数编码+元数据映射（最高存储效率） #

如果枚举的value是整数类型，直接存储整数值（对应Parquet的int8/int16等小整数类型），同时在Parquet的Schema元数据中记录枚举与整数的映射关系。这种方式存储效率最高，其他阅读器可通过读取元数据解析枚举含义。

示例代码：

class StatusInt(Enum):
    ACTIVE = 1
    INACTIVE = 2
    PENDING = 3

# 转换枚举为整数值
data = {"status": [s.value for s in [StatusInt.ACTIVE, StatusInt.INACTIVE, StatusInt.PENDING]]}
table = pa.Table.from_pydict(data)

# 添加枚举映射到Schema元数据
metadata = table.schema.metadata.copy()
metadata[b"enum_mapping:status"] = b'{"1": "ACTIVE", "2": "INACTIVE", "3": "PENDING"}'
table = table.replace_schema_metadata(metadata)

pq.write_table(table, "status_int.parquet")

3. 字典编码字符串（兼顾效率与可读性） #

利用Parquet的字典编码（Dictionary Encoding）存储枚举字符串。对于基数低（枚举值数量少）的场景，字典编码会将重复字符串映射为整数，既保留字符串可读性，又能获得接近整数的存储效率。PyArrow默认会对低基数字符串列自动启用字典编码，也可手动指定类型。

示例代码：

# 手动指定字典编码类型（用int8作为索引，最大化节省空间）
status_dict_type = pa.dictionary(pa.int8(), pa.string())

# 转换枚举为字符串后，Cast到字典类型
status_array = pa.array([s.value for s in [Status.ACTIVE, Status.INACTIVE, Status.PENDING]], 
                        type=status_dict_type)
table = pa.Table.from_arrays([status_array], names=["status"])
pq.write_table(table, "status_dictionary.parquet")

方案选择建议 #

• 优先选字典编码字符串：平衡可读性、存储效率和跨工具兼容性，无需额外维护映射表。
• 追求极致效率选整数编码+元数据：适合枚举值数量多、对存储体积敏感的场景。
• 快速实现选字符串直存：开发成本最低，兼容性最好。

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