Parquet 格式不支持 datetime.time 类型作为 DataFrame 列名，直接使用会导致 TypeError: data type 'time' not understood；本文提供简洁可靠的字符串化转换方案，并说明原理与最佳实践。
parquet 格式不支持 `datetime.time` 类型作为 dataframe 列名，直接使用会导致 `typeerror: data type 'time' not understood`；本文提供简洁可靠的字符串化转换方案，并说明原理与最佳实践。
Parquet 是一种列式存储格式，被广泛用于高效大数据读写，但其元数据规范（基于 Apache Arrow）不支持 Python 原生 datetime.time 类型作为列名（即 DataFrame 的 columns）。当您用 time(9) 或 time(10) 这样的对象作为字典键构造 DataFrame 列时，Pandas 会将其保留为 Index 的元素类型；而 to_parquet() 在序列化列名时无法映射该类型到 Arrow 支持的物理类型，从而在 read_parquet() 阶段触发解析失败。
✅ 推荐解决方案：将 time 对象预转换为 ISO 格式字符串（如 '09:00:00'），既保持语义清晰，又完全兼容 Parquet 标准：
from datetime import time
import pandas as pd
# 正确做法：列名使用字符串而非 time 对象
df = pd.DataFrame(
index=['ABC', 'DEF'],
data={str(time(9)): [2, 4], str(time(10)): [6, 8]}
)
df.to_parquet('MWE.parquet')
# 可安全读取，列名自动还原为字符串
df1 = pd.read_parquet('MWE.parquet')
print(df1)
# 输出：
# 09:00:00 10:00:00
# ABC 2 6
# DEF 4 8
⚠️ 注意事项：
- 不要依赖
pd.read_parquet(..., dtype={'09:00:00': 'time64[ns]'})强制转列内容类型——列名本身不是数据，无法通过dtype参数修复； - 若需后续将列名转回
time对象，可手动映射：df1.columns = pd.to_datetime(df1.columns).dt.time（需确保格式统一）； - 更稳健的工程实践是：始终使用字符串或数值作为列名，将结构化语义（如时间点）存于列内容、索引或额外元数据中，避免格式耦合。
总结：Parquet 的设计目标是跨语言互操作性与高性能，因此牺牲了对部分 Python 特有类型的直接支持。将 time 列名转为标准字符串是最小侵入、零依赖、可逆性强的通用解法，建议纳入 Pandas + Parquet 工作流的默认规范。
