Pandas中orient='split'模式下to_json与read_json的多层索引兼容问题

问题本质：版本兼容性缺陷，非Bug #

在Pandas 1.2.4版本中，orient='split'参数对多层索引（MultiIndex）的往返序列化支持不完善。该参数最初仅针对单层索引设计，序列化MultiIndex时会将索引的每一层转为独立列表存入JSON的index字段，但反序列化时read_json无法正确识别此结构——会把这些列表当成行索引的单个元素，导致索引转置；当索引层数与数据行数不一致时，还会因形状不匹配抛出ValueError。后续Pandas版本（1.3.x及以上）修复了该问题，但1.2.4版本中此问题确实存在。

简便解决办法（保留split格式） #

无需修改序列化逻辑，仅在反序列化时手动重建多层索引即可修正结果，具体代码如下：

完整复现与修复代码 #

import pandas as pd

mindex=['A','B','C']
df = pd.DataFrame({
   'A': ['foo', 'bar', 'baz'],
   'B': ['one', 'two', 'three'],
   'C': [1, 2, 3],
   'vals':[1.1,2.2, 3.3]
}).set_index(mindex)    

# 保持原有序列化逻辑
result = df.to_json(orient='split')

# 反序列化并修复索引
df_r_temp = pd.read_json(result, orient='split')
# 将JSON中存储的多层索引列表转置，重建MultiIndex
new_multi_index = pd.MultiIndex.from_arrays(df_r_temp.index.tolist(), names=mindex)
# 构建结构正确的DataFrame
df_r = pd.DataFrame(df_r_temp.values, index=new_multi_index, columns=df_r_temp.columns)

# 验证结果
print("原始DataFrame:")
print(df)
print("\n还原后的DataFrame:")
print(df_r)

原理说明 #

• 序列化时，to_json(orient='split')会把MultiIndex的每一层转为一个子列表，存入JSON的index字段（例如3层索引会生成3个长度为3的子列表）。
• 反序列化时，read_json会错误地将这些子列表直接作为行索引元素，导致结构错乱。我们通过pd.MultiIndex.from_arrays将转置后的索引列表重新构建为多层索引，即可还原原始结构。

该方法适用于所有索引层数与数据行数的组合，能稳定保留split格式的存储方式。

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