Python实用工具：pandas-gbq 从入门到精通的完整指南

作者：

在

一、pandas-gbq 库核心概述

pandas-gbq 是 pandas 生态中专门用于连接 Google BigQuery 数据仓库的工具库，它的核心用途是实现 pandas DataFrame 与 Google BigQuery 数据表之间的高效数据读写操作。其工作原理是基于 Google Cloud 的 BigQuery API，将 pandas 的数据结构与 BigQuery 的表结构进行映射，通过认证机制建立连接后，完成数据的上传、下载与查询任务。

二、pandas-gbq 安装与环境配置

2.1 库的安装

安装 pandas-gbq 非常简单，使用 Python 包管理工具 pip 即可完成，打开命令行终端，输入以下命令：

pip install pandas-gbq

这条命令会自动下载并安装 pandas-gbq 的最新稳定版本，同时安装其依赖项，包括 pandas、google-cloud-bigquery、google-auth 等。如果需要安装指定版本的 pandas-gbq，可以在命令后加上版本号，例如安装 0.19.0 版本：

pip install pandas-gbq==0.19.0

安装完成后，可以在 Python 环境中通过导入语句验证是否安装成功：

import pandas_gbq
print(pandas_gbq.__version__)

运行上述代码，如果控制台输出对应的版本号，说明安装成功。

2.2 Google Cloud 环境配置

要使用 pandas-gbq 操作 BigQuery，必须先完成 Google Cloud 的环境配置，主要包括以下几个步骤：

创建 Google Cloud 项目
登录 Google Cloud 控制台，创建一个新的项目，或者选择已有的项目。项目是 Google Cloud 资源管理的基本单位，后续的 BigQuery 操作都需要关联到具体项目。
启用 BigQuery API
在 Google Cloud 控制台的 API 和服务页面，搜索并启用 BigQuery API，只有启用该 API，才能通过 pandas-gbq 调用 BigQuery 的相关功能。
创建并下载认证密钥文件
为了让本地程序能够访问 Google Cloud 资源，需要创建服务账号并生成认证密钥。在 Google Cloud 控制台的 “IAM 与管理-服务账号” 页面，创建新的服务账号，为其分配合适的权限，例如 BigQuery Admin（管理员权限，适合开发测试）或 BigQuery Data Editor（数据编辑权限，适合生产环境）。创建完成后，为服务账号生成并下载 JSON 格式的密钥文件。
配置环境变量 将下载的 JSON 密钥文件的路径配置到环境变量 GOOGLE_APPLICATION_CREDENTIALS 中，这是 Google Cloud 认证的默认方式。
- Windows 系统（命令行）：
  bash set GOOGLE_APPLICATION_CREDENTIALS="C:\path\to\your\keyfile.json"
- Linux/Mac 系统（终端）：
  bash export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/keyfile.json"
  配置完成后，程序就能自动识别认证信息，无需在代码中手动指定密钥路径。

三、pandas-gbq 核心功能与代码实例

pandas-gbq 的核心功能分为三大类：从 BigQuery 查询数据到 DataFrame、将 DataFrame 数据写入 BigQuery、以及对 BigQuery 表的基础管理操作。下面结合具体代码实例详细讲解每个功能的使用方法。

3.1 从 BigQuery 查询数据到 DataFrame

这是 pandas-gbq 最常用的功能之一，通过编写 SQL 查询语句，将 BigQuery 中的数据读取到 pandas DataFrame 中，方便后续的数据分析和处理。核心函数是 pandas_gbq.read_gbq()。

3.1.1 基础查询示例

假设我们有一个 BigQuery 数据集 my_dataset，其中包含一个表 sales_data，存储了某电商平台的销售数据，表结构如下：
| 字段名 | 数据类型 | 说明 |
|–|-||
| order_id | STRING | 订单ID |
| sale_date | DATE | 销售日期 |
| product_id | STRING | 商品ID |
| sale_amount | FLOAT | 销售金额 |
| customer_id | STRING | 客户ID |

现在需要查询 2024 年 1 月的销售数据，代码如下：

import pandas as pd
import pandas_gbq

# 定义SQL查询语句
query = """
SELECT order_id, sale_date, product_id, sale_amount, customer_id
FROM `my_project.my_dataset.sales_data`
WHERE sale_date BETWEEN '2024-01-01' AND '2024-01-31'
"""

# 执行查询，将结果读取到DataFrame
df = pandas_gbq.read_gbq(
    query=query,
    project_id="my_project"  # 替换为你的Google Cloud项目ID
)

# 查看数据的前5行
print(df.head())

代码说明：

首先导入 pandas 和 pandas_gbq 库；
定义 SQL 查询语句，注意 BigQuery 的表名格式为 项目ID.数据集ID.表名，需要用反引号包裹；
调用 read_gbq() 函数，传入查询语句和项目 ID，函数会自动完成认证并执行查询；
最后通过 head() 方法查看数据的前 5 行，验证数据是否成功读取。

3.1.2 带参数的查询

在实际应用中，经常需要根据动态参数执行查询，例如查询指定月份的销售数据。pandas-gbq 支持通过 params 参数传入查询参数，避免手动拼接 SQL 语句导致的安全问题（如 SQL 注入）。代码示例如下：

import pandas as pd
import pandas_gbq

# 定义动态参数
start_date = "2024-02-01"
end_date = "2024-02-29"

# 定义带参数的SQL查询语句
query = """
SELECT order_id, sale_date, product_id, sale_amount, customer_id
FROM `my_project.my_dataset.sales_data`
WHERE sale_date BETWEEN @start_date AND @end_date
"""

# 执行带参数的查询
df = pandas_gbq.read_gbq(
    query=query,
    project_id="my_project",
    params={"start_date": start_date, "end_date": end_date}
)

# 查看数据的基本信息
print(df.info())

代码说明：

SQL 查询语句中使用 @参数名 的格式定义参数占位符；
在 read_gbq() 函数中，通过 params 参数传入一个字典，字典的键为参数名，值为参数的具体取值；
这种方式不仅提高了代码的灵活性，还能有效防止 SQL 注入攻击，保证查询的安全性。

3.1.3 分页查询大数据集

当查询的数据集非常大时，一次性读取所有数据可能会导致内存不足。pandas-gbq 支持分页查询，通过设置 chunksize 参数，将查询结果分成多个小块，逐块读取和处理。代码示例如下：

import pandas as pd
import pandas_gbq

# 定义SQL查询语句，查询所有销售数据
query = """
SELECT * FROM `my_project.my_dataset.sales_data`
"""

# 分页读取数据，每次读取10000行
chunk_iter = pandas_gbq.read_gbq(
    query=query,
    project_id="my_project",
    chunksize=10000
)

# 遍历每个数据块并进行处理
for chunk in chunk_iter:
    # 示例：计算每个数据块的销售金额总和
    total_sale = chunk["sale_amount"].sum()
    print(f"当前数据块销售金额总和：{total_sale}")

代码说明：

设置 chunksize=10000 后，read_gbq() 函数会返回一个迭代器，每次迭代返回一个包含 10000 行数据的 DataFrame；
通过遍历迭代器，可以逐块处理数据，避免一次性加载大量数据占用过多内存；
这种方法适用于处理超大数据集，是大数据分析中常用的优化手段。

3.2 将 DataFrame 数据写入 BigQuery

将本地或处理后的 pandas DataFrame 数据写入 BigQuery 表，是数据存储和共享的重要环节。pandas-gbq 提供了 pandas_gbq.to_gbq() 函数，支持将 DataFrame 数据写入新表或追加到已有表中。

3.2.1 写入新表

假设我们有一个本地的 DataFrame，存储了新的销售数据，需要将其写入 BigQuery 的 my_dataset 数据集中，创建一个新表 new_sales_data。代码示例如下：

import pandas as pd
import pandas_gbq

# 创建本地DataFrame
data = {
    "order_id": ["OD202403001", "OD202403002", "OD202403003"],
    "sale_date": ["2024-03-01", "2024-03-01", "2024-03-02"],
    "product_id": ["P001", "P002", "P001"],
    "sale_amount": [199.9, 299.9, 199.9],
    "customer_id": ["C001", "C002", "C003"]
}
df = pd.DataFrame(data)

# 将DataFrame写入BigQuery新表
pandas_gbq.to_gbq(
    dataframe=df,
    destination_table="my_dataset.new_sales_data",  # 目标表：数据集.表名
    project_id="my_project",
    if_exists="fail"  # 如果表已存在，则抛出错误
)

print("数据成功写入BigQuery新表！")

代码说明：

首先创建一个包含销售数据的 DataFrame；
调用 to_gbq() 函数，传入 DataFrame、目标表名和项目 ID；
if_exists 参数用于指定表已存在时的处理方式，可选值有：
fail：默认值，如果表已存在则抛出错误；
replace：覆盖已存在的表；
append：将数据追加到已存在的表中。

3.2.2 追加数据到已有表

在日常业务中，经常需要将新增的数据追加到 BigQuery 的已有表中，例如每日新增的销售数据。此时只需将 if_exists 参数设置为 append 即可。代码示例如下：

import pandas as pd
import pandas_gbq

# 创建新增的销售数据DataFrame
new_data = {
    "order_id": ["OD202403004", "OD202403005"],
    "sale_date": ["2024-03-02", "2024-03-03"],
    "product_id": ["P003", "P002"],
    "sale_amount": [399.9, 299.9],
    "customer_id": ["C004", "C005"]
}
df_new = pd.DataFrame(new_data)

# 将新增数据追加到已有表中
pandas_gbq.to_gbq(
    dataframe=df_new,
    destination_table="my_dataset.new_sales_data",
    project_id="my_project",
    if_exists="append"
)

print("数据成功追加到BigQuery已有表！")

代码说明：

创建包含新增数据的 DataFrame df_new；
设置 if_exists="append"，函数会将 df_new 中的数据追加到 my_dataset.new_sales_data 表中；
追加数据时，需要确保 DataFrame 的列名和数据类型与 BigQuery 表的结构一致，否则会导致写入失败。

3.2.3 指定数据类型写入

默认情况下，pandas-gbq 会根据 DataFrame 的列数据类型自动推断 BigQuery 表的字段类型，但有时自动推断的结果可能不符合需求。此时可以通过 table_schema 参数手动指定字段的数据类型。代码示例如下：

import pandas as pd
import pandas_gbq

# 创建DataFrame
data = {
    "id": [1, 2, 3],
    "name": ["Alice", "Bob", "Charlie"],
    "score": [95.5, 88.0, 92.3]
}
df = pd.DataFrame(data)

# 手动指定BigQuery表的schema
table_schema = [
    {"name": "id", "type": "INTEGER"},
    {"name": "name", "type": "STRING"},
    {"name": "score", "type": "FLOAT"}
]

# 写入数据并指定schema
pandas_gbq.to_gbq(
    dataframe=df,
    destination_table="my_dataset.student_scores",
    project_id="my_project",
    table_schema=table_schema,
    if_exists="replace"
)

print("数据成功写入，并应用自定义schema！")

代码说明：

table_schema 参数接受一个列表，列表中的每个元素是一个字典，包含 name（字段名）和 type（BigQuery 数据类型）两个键；
BigQuery 支持的数据类型包括 INTEGER、FLOAT、STRING、DATE、DATETIME 等，详细类型可参考 BigQuery 官方文档；
手动指定 schema 可以确保 BigQuery 表的字段类型符合业务需求，避免自动推断带来的误差。

3.3 BigQuery 表的基础管理操作

除了数据的读写，pandas-gbq 还可以结合 Google Cloud 的其他库，实现对 BigQuery 表的基础管理操作，例如查看表的元数据、删除表等。需要注意的是，部分高级管理功能需要依赖 google-cloud-bigquery 库。

3.3.1 查看表的元数据

查看 BigQuery 表的元数据，包括字段名、数据类型、表描述等信息，代码示例如下：

import pandas_gbq
from google.cloud import bigquery

# 初始化BigQuery客户端
client = bigquery.Client(project="my_project")

# 定义表的引用
table_ref = client.dataset("my_dataset").table("sales_data")

# 获取表的元数据
table = client.get_table(table_ref)

# 打印表的基本信息
print(f"表名：{table.table_id}")
print(f"数据集：{table.dataset_id}")
print(f"创建时间：{table.created}")
print("字段信息：")
for schema_field in table.schema:
    print(f"- {schema_field.name}: {schema_field.field_type}")

代码说明：

首先导入 google.cloud.bigquery 库，并初始化 BigQuery 客户端；
通过 dataset() 和 table() 方法创建表的引用；
调用 get_table() 方法获取表的元数据对象，通过该对象可以访问表的各种属性，如表名、创建时间、字段信息等。

3.3.2 删除 BigQuery 表

如果需要删除不再使用的 BigQuery 表，可以使用 client.delete_table() 方法，代码示例如下：

from google.cloud import bigquery

# 初始化BigQuery客户端
client = bigquery.Client(project="my_project")

# 定义要删除的表的引用
table_ref = client.dataset("my_dataset").table("temp_table")

# 删除表
client.delete_table(table_ref)

print("表已成功删除！")

代码说明：

该操作需要确保服务账号拥有 BigQuery Table Admin 权限；
删除表的操作不可逆，执行前需要确认表中的数据不再需要，避免数据丢失。

四、pandas-gbq 实际应用案例：电商销售数据分析

为了更好地理解 pandas-gbq 在实际项目中的应用，我们以电商销售数据分析为例，完整展示从 BigQuery 读取数据、数据清洗、分析可视化到结果写入 BigQuery 的全流程。

4.1 案例背景

某电商平台将每日销售数据存储在 Google BigQuery 的 ecommerce.sales_data 表中，需要分析 2024 年第一季度（1-3 月）的销售情况，包括：

每月的销售总额；
热销商品 TOP10；
客户购买频次分布。
最后将分析结果写入 BigQuery 的 ecommerce.sales_analysis 表中，供业务部门查看。

4.2 完整代码实现

import pandas as pd
import pandas_gbq
import matplotlib.pyplot as plt
from google.cloud import bigquery

# - 步骤1：配置环境与初始化客户端 -
# 初始化BigQuery客户端
client = bigquery.Client(project="my_ecommerce_project")

# - 步骤2：从BigQuery读取第一季度销售数据 -
query = """
SELECT 
    order_id,
    sale_date,
    product_id,
    sale_amount,
    customer_id
FROM `my_ecommerce_project.ecommerce.sales_data`
WHERE sale_date BETWEEN '2024-01-01' AND '2024-03-31'
"""

# 读取数据到DataFrame
df_sales = pandas_gbq.read_gbq(
    query=query,
    project_id="my_ecommerce_project"
)

# - 步骤3：数据清洗 -
# 查看数据是否存在缺失值
print("缺失值情况：")
print(df_sales.isnull().sum())

# 删除缺失值所在行
df_sales = df_sales.dropna()

# 将sale_date转换为日期类型
df_sales["sale_date"] = pd.to_datetime(df_sales["sale_date"])

# 添加月份列，方便后续按月分析
df_sales["month"] = df_sales["sale_date"].dt.month_name()

# - 步骤4：数据分析 -
# 4.1 计算每月销售总额
monthly_sales = df_sales.groupby("month")["sale_amount"].sum().reset_index()
monthly_sales.columns = ["month", "total_sale"]
# 按月份顺序排序
month_order = ["January", "February", "March"]
monthly_sales["month"] = pd.Categorical(monthly_sales["month"], categories=month_order, ordered=True)
monthly_sales = monthly_sales.sort_values("month")
print("\n每月销售总额：")
print(monthly_sales)

# 4.2 热销商品TOP10
top10_products = df_sales.groupby("product_id")["sale_amount"].sum().reset_index()
top10_products = top10_products.sort_values("sale_amount", ascending=False).head(10)
print("\n热销商品TOP10：")
print(top10_products)

# 4.3 客户购买频次分布
customer_freq = df_sales.groupby("customer_id")["order_id"].nunique().reset_index()
customer_freq.columns = ["customer_id", "order_count"]
freq_distribution = customer_freq.groupby("order_count")["customer_id"].count().reset_index()
freq_distribution.columns = ["order_count", "customer_num"]
print("\n客户购买频次分布：")
print(freq_distribution)

# - 步骤5：数据可视化 -
# 设置中文字体，避免图表中文乱码
plt.rcParams["font.sans-serif"] = ["SimHei"]
plt.rcParams["axes.unicode_minus"] = False

# 绘制每月销售总额柱状图
plt.figure(figsize=(10, 6))
plt.bar(monthly_sales["month"], monthly_sales["total_sale"], color="#1f77b4")
plt.title("2024年第一季度每月销售总额", fontsize=14)
plt.xlabel("月份", fontsize=12)
plt.ylabel("销售总额（元）", fontsize=12)
plt.grid(axis="y", linestyle="--", alpha=0.7)
plt.savefig("monthly_sales.png", dpi=300, bbox_inches="tight")
plt.show()

# - 步骤6：将分析结果写入BigQuery -
# 合并所有分析结果到一个DataFrame
# 为了简化，这里以每月销售总额为例写入BigQuery
pandas_gbq.to_gbq(
    dataframe=monthly_sales,
    destination_table="ecommerce.sales_analysis",
    project_id="my_ecommerce_project",
    if_exists="replace"
)

print("\n分析结果已成功写入BigQuery表！")

4.3 案例说明

数据读取与清洗：通过 read_gbq() 读取第一季度销售数据，使用 dropna() 删除缺失值，将日期字段转换为 datetime 类型，并添加月份列，为后续分析做准备。
核心分析：利用 pandas 的分组聚合功能，分别计算每月销售总额、热销商品 TOP10 和客户购买频次分布，这些分析结果能帮助业务部门了解销售趋势和客户行为。
数据可视化：使用 matplotlib 绘制每月销售总额柱状图，直观展示销售趋势，图表保存为图片文件，方便汇报使用。
结果存储：将每月销售总额的分析结果写入 BigQuery 的 sales_analysis 表中，实现分析结果的共享和长期存储。

五、pandas-gbq 相关资源地址

PyPI 地址：https://pypi.org/project/pandas-gbq
GitHub 地址：https://github.com/pandas-dev/pandas-gbq
官方文档地址：https://pandas-gbq.readthedocs.io/

关注我，每天分享一个实用的Python自动化工具。

实用工具

Python实用工具：pandas-gbq 从入门到精通的完整指南

一、pandas-gbq 库核心概述

二、pandas-gbq 安装与环境配置

2.1 库的安装

2.2 Google Cloud 环境配置

三、pandas-gbq 核心功能与代码实例

3.1 从 BigQuery 查询数据到 DataFrame

3.1.1 基础查询示例

3.1.2 带参数的查询

3.1.3 分页查询大数据集

3.2 将 DataFrame 数据写入 BigQuery

3.2.1 写入新表

3.2.2 追加数据到已有表

3.2.3 指定数据类型写入

3.3 BigQuery 表的基础管理操作

3.3.1 查看表的元数据

3.3.2 删除 BigQuery 表

四、pandas-gbq 实际应用案例：电商销售数据分析

4.1 案例背景

4.2 完整代码实现

4.3 案例说明

五、pandas-gbq 相关资源地址

更多文章

Python实用工具Upgini：零代码特征工程与数据集增强教程

Python实用工具库excalibur：PDF表格提取与数据处理实战教程

Python实用工具：rows库快速入门与实战指南

Python实用工具：Camelot库——轻松提取PDF表格数据的完整指南