Python用json_normalize展开字典格式列

本文深入解析了使用 pandas 的 `pd.json_normalize()` 高效展开 DataFrame 中字典格式列的核心要点与常见陷阱：必须将字典列转为列表（`df['col'].tolist()`）才能正确输入，`record_path` 必须是字符串列表（如 `['items']`）而非单个字符串，否则会触发 KeyError、空结果或 TypeError；同时详解了如何用 `sep` 参数替换嵌套字段的点号分隔符、用 `max_level` 控制展开深度、配合 `explode()` 处理简单列表、以及通过批量处理而非逐行调用避免性能暴跌和内存爆炸——这些正是实践中最易踩坑又最常被忽略的关键细节。

pd.json_normalize() 处理字典列时直接报错 KeyError 或返回空 DataFrame

常见现象是：DataFrame 里有一列存的是 Python 字典（不是 JSON 字符串），但直接传给 pd.json_normalize() 就出错，比如 KeyError: 'id'，或者结果全是 NaN。这是因为 pd.json_normalize() 默认只接受 list of dict，不接受单个 dict 或含 dict 的 Series。

• 先确认列类型：df['col'].apply(type).unique() —— 如果看到 ，说明是字典，不是字符串
• 必须把字典列转成列表：pd.json_normalize(df['col'].tolist())，不能写 pd.json_normalize(df['col'])
• 如果列里混了 None、NaN 或非 dict 类型，.tolist() 会保留它们，导致 json_normalize 报错；需提前清洗：df['col'].dropna().apply(lambda x: isinstance(x, dict)).all() 检查，再用 df['col'].dropna().tolist()

嵌套字典展开后字段名带点号（如 user.name），想改成下划线或去掉层级

默认展开后字段是 user.name、address.city 这种点分隔形式，Pandas 不允许点号作为列名（虽然实际能存，但后续用 df.user.name 会失败），而且也不符合多数数据库或导出规范。

• 用 sep 参数换分隔符：pd.json_normalize(data, sep='_') → 得到 user_name、address_city
• 想完全扁平化（去掉所有嵌套标识），只能手动重命名，json_normalize 本身不支持；可接 .rename(columns=lambda x: x.rsplit('.', 1)[-1])，但注意同名字段会冲突（比如两个不同层级都有 id）
• max_level 控制展开深度，设为 0 就不展开任何嵌套，设为 1 只展开一层 —— 对深层嵌套很实用，避免爆炸式列增长

处理含列表的嵌套结构（如 "tags": ["a", "b"] 或 "items": [{"id":1}, {"id":2}]）

遇到字段值是 list，json_normalize 默认会把整个 list 当成一个单元塞进单元格，不会自动“炸开”。要真正展开，得靠 record_path 和 meta 配合。

• 若目标是展开 items 列表（每个元素是 dict）：pd.json_normalize(df, record_path=['items'], meta=['id', 'name'])，其中 record_path 指定要“压平”的路径，meta 是想保留的外层字段
• 若字段是简单 list（如 ["a","b"]），json_normalize 无法直接展开；得先用 explode()：df.explode('tags').reset_index(drop=True)，再对单个 tag 做后续处理
• 注意 record_path 必须是 list 路径，写成字符串（如 'items'）会报 TypeError；正确写法是 ['items'] 或 ['data', 'items']

性能差、内存暴涨：大 DataFrame 上反复调用 json_normalize

别在循环里对每一行做 json_normalize(row['col']) —— 这会触发上千次小规模 normalize，开销远高于一次性处理整个列表，还容易因 dtype 不一致导致隐式转换和内存碎片。

• 始终优先批量处理：pd.json_normalize(df['col'].dropna().tolist())，而不是逐行
• 如果字典列里有大量 null 或结构不一致，json_normalize 内部会填充 NaN 并推断 dtype，可能把 int 列变 float；可在之后用 .convert_dtypes() 或显式 .astype() 修正
• 超大 JSON（单条 >1MB）建议先用 json.loads() 验证合法性，避免 json_normalize 在中间崩溃导致整批失败

事情说清了就结束。最常被忽略的是：字典列必须转 tolist() 才能喂给 json_normalize，以及 record_path 必须是列表而非字符串 —— 这两个点卡住的人最多。

以上就是本文的全部内容了，是否有顺利帮助你解决问题？若是能给你带来学习上的帮助，请大家多多支持golang学习网！更多关于文章的相关知识，也可关注golang学习网公众号。