Python加载pandas整数数组至BigQuery时数组为空问题咨询

尝试将pandas DataFrame中的整数数组加载到BigQuery时，加载任务正常执行完成，但目标表内的数组字段为空，数组中存储的所有整数值全部丢失，现象如下：

复现代码如下：

tableId = test-dev.xpto.array
df = pd.DataFrame()
    df['name'] = ['city']
    df['channels'] = [[1, 13, 36]]

schema = [
    bigquery.SchemaField("name", "STRING", mode="NULLABLE"),
    bigquery.SchemaField("channels", "INT64", mode="REPEATED")
]
job_config = bigquery.LoadJobConfig(
        schema=schema,
        create_disposition="CREATE_IF_NEEDED",
        write_disposition="WRITE_APPEND",
    )

job = client.load_table_from_dataframe(
            df, table_id, job_config=job_config
        )

核心疏漏是未处理pandas数组列的序列化类型适配问题：
load_table_from_dataframe方法默认使用Parquet作为中间传输格式，序列化阶段依赖pyarrow做类型转换。代码中channels列存储的是Python原生列表，pandas会把该列识别为object类型，旧版BigQuery客户端无法自动将object类型的列表值映射为BigQuery的REPEATED类型字段，序列化时会直接丢弃列值，且不会抛出显性错误，最终表现为作业执行成功但数组字段为空。显式传入schema仅会在BigQuery服务端做加载校验，无法修正客户端本地序列化阶段的数值丢失问题。

• 先校验DataFrame字段类型：执行print(df.dtypes)，可观察到channels列类型为object，不属于BigQuery客户端可自动识别的数组类型
• 检查加载作业详情：调用job.result()后打印job.load_statistics，或去BigQuery控制台查看对应作业的加载日志，可看到REPEATED字段的写入值统计为0，无显式报错
• 做最小场景验证：将channels列替换为字符串列表、浮点数列表重复加载测试，会发现所有object类型的列表列都存在空值问题，确认是序列化适配问题而非整数类型专属问题

以下方案任选其一即可：

• 显式转换为pyarrow数组类型（最稳定推荐）
  提前将数组列转为pyarrow原生的列表类型，让Parquet序列化阶段可直接识别类型，无需修改原有schema配置：

  import pyarrow as pa
  
  # 构造DataFrame后增加类型转换步骤
  df = pd.DataFrame()
  df['name'] = ['city']
  df['channels'] = [[1, 13, 36]]
  # 将列表列转为pyarrow int64数组类型
  df['channels'] = df['channels'].apply(lambda x: pa.array(x, type=pa.int64()))
  
  # 后续加载逻辑保持不变即可
  

• 修改加载源格式绕过Parquet序列化
  在作业配置中指定源格式为换行符分隔JSON，跳过Parquet序列化环节，直接按JSON结构解析列表值：

  job_config = bigquery.LoadJobConfig(
      schema=schema,
      create_disposition="CREATE_IF_NEEDED",
      write_disposition="WRITE_APPEND",
      # 新增源格式配置
      source_format=bigquery.SourceFormat.NEWLINE_DELIMITED_JSON
  )
  

• 升级依赖版本修复已知bug
  升级google-cloud-bigquery到3.0以上版本、pyarrow到6.0以上稳定版，新版本对pandas object类型的列表列做了自动适配，部分简单场景下无需手动做类型转换即可正常加载。

注意：不要直接将numpy数组存入DataFrame的数组列，numpy整数类型与BigQuery INT64存在序列化适配差异，容易出现值截断或类型不匹配错误，建议转为原生Python int列表或pyarrow数组后再写入

内容的提问来源于stack exchange，提问作者Rui Bras Fernandes