【Pandas】pandas DataFrame to_gbq

Pandas2.2 DataFrame

Serialization IO conversion

pandas.DataFrame.to_gbq()

pandas.DataFrame.to_gbq() 是 Pandas 提供的一个方法，用于将 DataFrame 写入 Google BigQuery 数据库。该方法基于 pandas-gbq 包，支持将结构化数据直接上传到 Google Cloud 平台上的 BigQuery 表中，适用于数据分析、ETL 流程、数据可视化等场景。

📌 方法签名

DataFrame.to_gbq(
    destination_table,
    *,
    project_id=None,
    chunksize=None,
    reauth=False,
    if_exists='fail',
    auth_local_webserver=True,
    table_schema=None,
    location=None,
    progress_bar=True,
    credentials=None
)

🔍 参数说明

✅ 示例及结果

示例 1：基础用法（写入 BigQuery 表）

import pandas as pd

# 创建示例 DataFrame
df = pd.DataFrame({
    'Name': ['Alice', 'Bob', 'Charlie'],
    'Age': [25, 30, 35],
    'Salary': [70000, 80000, 90000]
})

# 写入 BigQuery 表
df.to_gbq(
    destination_table='my_dataset.my_table',
    project_id='my-project-id',
    if_exists='replace'
)

⚠️ 说明：

• 首次运行会打开浏览器进行 OAuth2 认证（默认使用用户凭据）。
• 成功上传后，可在 BigQuery 控制台查看 my_dataset.my_table 表。

示例 2：追加写入已有表（if_exists='append'）

# 新增一行数据
new_row = pd.DataFrame({
    'Name': ['David'],
    'Age': [28],
    'Salary': [75000]
})

# 追加写入已有表
new_row.to_gbq(
    destination_table='my_dataset.my_table',
    project_id='my-project-id',
    if_exists='append'
)

结果：

• my_dataset.my_table 表新增一行数据。
• 适用于增量更新或数据聚合场景。

示例 3：使用服务账户凭据（适用于自动化脚本）

from google.oauth2 import service_account
import pandas as pd

# 创建 DataFrame
df = pd.DataFrame({
    'Product': ['Laptop', 'Phone', 'Tablet'],
    'Price': [1200, 800, 400]
})

# 加载服务账户凭据
credentials = service_account.Credentials.from_service_account_file(
    'path/to/service-account.json'
)

# 写入 BigQuery 表
df.to_gbq(
    destination_table='my_dataset.products',
    project_id='my-project-id',
    if_exists='replace',
    credentials=credentials
)

说明：

• 适用于服务器端或定时任务，无需手动登录。
• 需提前创建服务账户并下载 JSON 凭据文件。

示例 4：指定表结构（table_schema）

# 自定义表结构
table_schema = [
    {'name': 'Name', 'type': 'STRING'},
    {'name': 'Age', 'type': 'INTEGER'},
    {'name': 'Salary', 'type': 'FLOAT'}
]

# 写入 BigQuery 并指定 schema
df.to_gbq(
    destination_table='my_dataset.my_table',
    project_id='my-project-id',
    if_exists='replace',
    table_schema=table_schema
)

说明：

• 可控制字段类型、是否允许空值等。
• 适用于需要严格数据类型定义的场景。

示例 5：分块写入大数据集（chunksize）

# 创建大数据集
df_large = pd.concat([df] * 10000)

# 分块写入，每批 1000 行
df_large.to_gbq(
    destination_table='my_dataset.large_table',
    project_id='my-project-id',
    if_exists='replace',
    chunksize=1000
)

优点：

• 避免内存溢出。
• 适用于百万级以上数据上传。

示例 6：指定地理区域（location）

# 指定数据集所在区域（如 'EU'）
df.to_gbq(
    destination_table='my_dataset.my_table',
    project_id='my-project-id',
    if_exists='replace',
    location='EU'
)

说明：

• 若数据集位于特定区域（如 EU），必须指定 location 参数。

⚠️ 注意事项

• 需要安装依赖包：

pip install pandas-gbq google-cloud-bigquery

• 首次运行会提示登录并授权访问 Google Cloud。
• 推荐使用服务账户凭据进行自动化操作。
• 支持 chunksize 分批写入，适用于大数据集。
• table_schema 可用于定义字段类型、精度、是否允许空值等。
• if_exists='replace' 会删除已有表并重建，慎用。
• if_exists='append' 适用于增量写入，但要求表结构一致。
• 上传前建议先在 BigQuery 中创建 Dataset。

📝 总结

🔁 与其他格式对比