如何重命名嵌套DataFrame的列名以适配BigQuery字段命名规范

问题原因 #

原来的prepare_json函数仅重命名了DataFrame最顶层的列名，嵌套JSON转换得到的DataFrame中，object类型列存储的字典、列表嵌套结构内部的键名未被处理，这些内部键会作为BigQuery的嵌套字段名，不符合命名规范导致报错。

解决方案 #

优先选择先处理原始JSON的全层级键名，再转换为DataFrame的方案，实现逻辑更简单可靠，不会触发Pandas嵌套数据类型的兼容问题。

完整实现代码如下：

import re
import pandas as pd
import json

def format_key(key: str) -> str:
    # 替换空格为下划线
    formatted = key.replace(' ', '_')
    # 首字符为数字则追加下划线前缀，兼容空键场景
    if formatted and formatted[0].isdigit():
        formatted = '_' + formatted
    return formatted

def format_json_keys(obj):
    if isinstance(obj, dict):
        # 递归处理字典的所有键和值
        return {format_key(k): format_json_keys(v) for k, v in obj.items()}
    elif isinstance(obj, list):
        # 递归处理列表的每个元素
        return [format_json_keys(item) for item in obj]
    else:
        # 基础类型直接返回
        return obj

# 业务处理流程示例
if __name__ == "__main__":
    # 1. 加载原始JSON
    with open("your_json_file.json", "r", encoding="utf-8") as f:
        raw_json = json.load(f)
    # 2. 全层级格式化所有键名
    processed_json = format_json_keys(raw_json)
    # 3. 转换为DataFrame（按需求选择json_normalize或普通转换方法）
    df = pd.json_normalize(processed_json)

效果说明 #

该方案会递归遍历JSON的所有层级，对每一个键执行两次格式化操作：

• 替换键名中的空格为下划线
• 若键名首字符为数字，自动在开头追加下划线前缀
  完全匹配BigQuery的字段命名规则：仅包含字母、数字、下划线，开头为字母或下划线。

如果确实需要处理已经生成的嵌套DataFrame，可以将DataFrame先通过to_json()方法转为JSON格式，再调用上述format_json_keys处理后重新转回DataFrame即可。

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