使用DataFrame向BigQuery JSON列插入数据报错问题排查

• load_table_from_dataframe() 依赖自动推断Pandas列对应的BigQuery数据类型，但Pandas没有原生JSON类型——当DataFrame中json_col存储的是Python字典/列表或字符串时，客户端库无法自动映射到BigQuery的JSON类型，因此抛出类型无法确定的警告。
• 即使目标表已通过Terraform定义了JSON列类型，自动推断逻辑仍会优先尝试匹配Pandas数据类型，推断失败后可能默认按字符串处理，导致与目标列类型不兼容。
• insert_rows_from_dataframe() 是逐行校验并插入，会严格对齐目标表预定义的schema，因此能正确识别并处理JSON列数据。

1. 手动指定目标表Schema #

显式定义包含JSON类型列的schema，跳过自动推断步骤：

from google.cloud import bigquery
import pandas as pd

# 示例DataFrame，json_col存储Python原生字典/列表
df = pd.DataFrame({
    "id": [1, 2],
    "json_col": [{"key": "val1"}, {"key": "val2"}]
})

# 定义与Terraform创建的表完全匹配的schema
schema = [
    bigquery.SchemaField("id", "INTEGER"),
    bigquery.SchemaField("json_col", "JSON")
]

client = bigquery.Client()
table_ref = client.get_table("your-project.your-dataset.your-table")

job_config = bigquery.LoadJobConfig(
    schema=schema,
    write_disposition=bigquery.WriteDisposition.WRITE_APPEND,  # 启用追加模式
    autodetect=False  # 禁用自动类型推断
)

# 执行数据加载
load_job = client.load_table_from_dataframe(
    df, table_ref, job_config=job_config
)
load_job.result()  # 等待任务执行完成

2. 确保DataFrame中JSON列的数据格式正确 #

• 不要将JSON序列化为字符串存储在json_col中，直接保留Python原生的字典或列表类型，BigQuery客户端会自动将其序列化为合法JSON格式插入目标列。
• 如果你的数据源是JSON字符串，提前转换为Python对象：

import json
df["json_col"] = df["json_col"].apply(json.loads)

3. 验证目标表Schema一致性 #

确认Terraform创建的表中json_col的类型确实是JSON（而非STRING），可通过以下代码检查：

table = client.get_table("your-project.your-dataset.your-table")
for field in table.schema:
    print(f"{field.name}: {field.field_type}")

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