如何在pandas中将DataFrame与列描述元数据一同存储为JSON或其他格式

方案1：JSON格式（兼容现有需求） #

你碰到的问题本质是直接调用pandas的to_json和read_json时，pandas会自动忽略schema里的自定义字段，只要绕开pandas的自动序列化/反序列化流程，手动处理完整的JSON结构即可，不会出现尾随数据错误，也没有额外使用门槛：

• 存储逻辑：先把DataFrame转成orient='table'格式的字典，手动给每个字段插入描述后，用Python原生的json模块写入文件
• 读取逻辑：先用json模块读取完整JSON结构，单独提取描述信息，再用数据部分生成DataFrame

示例代码 #

存储

import pandas as pd
import json

df = pd.DataFrame({"numbers": [6, 2],"strings": ["foo", "whatever"]})
# 定义每个字段的描述
col_desc = {
    "numbers": "values don't include ABC because XYZ",
    "strings": "普通文本字段，支持任意字符串存储"
}

# 生成带schema的table结构
table_dict = df.to_dict(orient='table', index=False)
# 插入字段描述
for field in table_dict['schema']['fields']:
    if field['name'] in col_desc:
        field['description'] = col_desc[field['name']]

# 写入文件
with open("data_with_desc.json", "w", encoding="utf-8") as f:
    json.dump(table_dict, f, indent=4, ensure_ascii=False)

读取

import pandas as pd
import json

with open("data_with_desc.json", "r", encoding="utf-8") as f:
    full_data = json.load(f)

# 提取字段描述
field_desc = {f["name"]: f.get("description", "") for f in full_data["schema"]["fields"]}
# 读取DataFrame，普通用户也可以直接用pd.read_json("data_with_desc.json", orient="table")读取，无任何障碍
df = pd.DataFrame(full_data["data"])

方案2：Parquet格式（更适合结构化数据，性能更优） #

如果对文件大小、读写速度有要求，更推荐用Parquet格式，它原生支持列级元数据存储，无pickle的安全风险，是工业界通用的结构化数据存储格式，使用门槛更低：

示例代码 #

存储

import pandas as pd

df = pd.DataFrame({"numbers": [6, 2],"strings": ["foo", "whatever"]})
col_desc = {
    "numbers": "values don't include ABC because XYZ",
    "strings": "普通文本字段，支持任意字符串存储"
}

# 给列绑定描述属性
for col, desc in col_desc.items():
    df[col].attrs["description"] = desc

# 写入文件，开启列属性存储开关
df.to_parquet("data_with_desc.parquet", store_data_column_attrs=True, index=False)

读取

import pandas as pd

# 读取数据，普通用户直接调用该方法即可正常获取DataFrame，无额外操作
df = pd.read_parquet("data_with_desc.parquet")
# 提取字段描述
col_desc = {col: df[col].attrs.get("description", "") for col in df.columns}

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