含列表字段的Python DataFrame导入BigQuery异常求助

核心问题定位 #

你遇到的两个错误本质都是DataFrame中字段类型与BigQuery Schema不匹配：

1. 重复string类型导入后字符拆分：因为DataFrame的field_name列实际是字符串类型（而非列表类型），BigQuery会将字符串按字符拆解为重复元素。
2. 重复record类型报错：因为重复record要求每个元素是键值对结构（如字典），但你的DataFrame中是普通字符串元素，类型不兼容。

步骤1：确保DataFrame字段为列表类型 #

先检查并修复field_name列的类型，确保每个元素都是Python列表（而非字符串）：

import pandas as pd
import ast

# 假设API返回的原始数据存在data变量中
df = pd.DataFrame(data)

# 检查字段类型：正常输出应为<class 'list'>
print(df['field_name'].apply(type).unique())

# 如果输出是<class 'str'>，需将字符串解析为列表
df['field_name'] = df['field_name'].apply(ast.literal_eval)

步骤2：匹配正确的Schema #

根据你的数据结构，选择对应的Schema：

场景1：直接存储字符串列表（推荐）

使用重复string类型的Schema，与DataFrame中的列表类型完全匹配：
用SchemaField定义：

from google.cloud.bigquery.schema import SchemaField

schema = [
    SchemaField("field_name", "STRING", mode="REPEATED"),
    # 添加其他字段...
]

或JSON Schema：

[
    {
        "name": "field_name",
        "type": "STRING",
        "mode": "REPEATED"
    }
]

场景2：需要用record类型存储

如果必须用重复record类型，需将DataFrame中的列表元素转换为字典结构：

# 将每个字符串元素包装为字典
df['field_name'] = df['field_name'].apply(lambda x: [{"list": item} for item in x])

此时使用你定义的第一种重复record Schema即可正常导入。

验证导入 #

修复后重新执行导入代码，即可避免两种错误：

destination_id = f"{self.dataset_id}.{table_id}"
bq_client.load_table_from_dataframe(
  df, destination_id, job_config=job_config
).result()

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