含元组列的Pandas DataFrame导出至BigQuery触发PyArrow错误

问题背景 #

我创建了带元组列的Pandas DataFrame：

import pandas as pd
df = pd.DataFrame({"id": [1,2,3], "items": [('a', 'b'), ('a', 'b', 'c'), tuple('d')]})

# 输出结果
#    id      items
# 0   1     (a, b)
# 1   2  (a, b, c)
# 2   3       (d,)

已通过环境变量配置好GCP凭据：

import os
os.environ["GOOGLE_APPLICATION_CREDENTIALS"] = "path_to_my_creds.json"

尝试用pandas_gbq.to_gbq导出到BigQuery时，持续报错：

pyarrow.lib.ArrowTypeError: Expected bytes, got a 'tuple' object

试过把元组转字符串、指定table_schema、改用load_table_from_dataframe方法，都没用。

解决步骤 #

BigQuery支持数组类型，只要把元组转成列表，再配合正确的表结构就能解决。

1. 把元组列转为列表 #

Pandas里的元组无法被pyarrow识别为数组，必须显式转成列表：

df['items'] = df['items'].apply(list)

2. 定义BigQuery表结构 #

指定items列为字符串类型的数组：

table_schema = [
    {"name": "id", "type": "INTEGER"},
    {"name": "items", "type": "STRING", "mode": "REPEATED"}
]

3. 重新导出数据 #

用pandas_gbq的方式：

import pandas_gbq
pandas_gbq.to_gbq(
    df, 
    "my_table_name", 
    if_exists="replace",
    table_schema=table_schema
)

用BigQuery客户端的方式：

from google.cloud import bigquery
client = bigquery.Client()
table_ref = client.dataset("你的数据集名称").table("my_table_name")

job = client.load_table_from_dataframe(
    df,
    table_ref,
    job_config=bigquery.LoadJobConfig(
        schema=table_schema,
        write_disposition="WRITE_TRUNCATE"
    )
)
job.result()  # 等待任务执行完成

无效原因说明 #

• 直接转字符串只是把元组变成了类似"(a,b)"的文本，但pyarrow仍会尝试解析原始元组类型，导致报错；
• 只指定schema不转列表，pyarrow无法把元组映射成BigQuery的数组类型，自然失败。

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