与 pandas-gbq 的比较

pandas-gbq 库提供了一个用于运行查询以及将 pandas DataFrame 上传到 BigQuery 的简单接口。它是 BigQuery 客户端库 google-cloud-bigquery 的瘦封装容器。这两个库都专注于帮助您使用 SQL 执行数据分析。本主题提供了用于比较 google-cloud-bigquery 和 pandas-gbq 的代码示例。

在功能和支持层面，两个库存在以下主要差异：

	pandas-gbq	google-cloud-bigquery
支持	这是由 PyData 和志愿贡献者维护的开放源代码库	由 Google 维护的开放源代码库
涵盖的 BigQuery API 功能	运行查询以及将 pandas DataFrame 中的数据保存到表中	支持全部 BigQuery API 功能，并添加了对读取/写入 pandas DataFrame 数据以及用于运行查询的 Jupyter 魔法命令的支持
	文档/源代码	文档/源代码

安装库

要使用本指南中的代码示例，请安装 pandas-gbq 软件包和 BigQuery Python 客户端库。

PIP

安装 pandas-gbq 和 google-cloud-bigquery 软件包。

pip install --upgrade pandas-gbq 'google-cloud-bigquery[bqstorage,pandas]'

Conda

从社区运行的 conda-forge 渠道安装 pandas-gbq 和 google-cloud-bigquery Conda 软件包。

conda install -c conda-forge pandas-gbq google-cloud-bigquery

运行查询

两个库都支持查询 BigQuery 中存储的数据。二者的主要区别如下所示：

	pandas-gbq	google-cloud-bigquery
默认 SQL 语法	GoogleSQL（可使用 pandas_gbq.context.dialect 配置）	GoogleSQL
查询配置	按照 BigQuery REST 参考中指定的格式，以字典形式发送。	使用 QueryJobConfig 类，其中包含各种 API 配置选项的属性。

使用 GoogleSQL 语法查询数据

以下示例演示了如何在明确指定项目和未明确指定项目的情况下运行 GoogleSQL 查询。对于这两个库，如果未指定项目，则系统将根据默认凭据确定项目。

注意：pandas.read_gbq 方法默认使用旧版 SQL。如需使用标准 SQL，您必须将 dialect 参数明确设置为 'standard'，如下所示。

pandas-gbq：

import pandas

sql = """
    SELECT name
    FROM `bigquery-public-data.usa_names.usa_1910_current`
    WHERE state = 'TX'
    LIMIT 100
"""

# Run a Standard SQL query using the environment's default project
df = pandas.read_gbq(sql, dialect="standard")

# Run a Standard SQL query with the project set explicitly
project_id = "your-project-id"
df = pandas.read_gbq(sql, project_id=project_id, dialect="standard")

google-cloud-bigquery：

from google.cloud import bigquery

client = bigquery.Client()
sql = """
    SELECT name
    FROM `bigquery-public-data.usa_names.usa_1910_current`
    WHERE state = 'TX'
    LIMIT 100
"""

# Run a Standard SQL query using the environment's default project
df = client.query(sql).to_dataframe()

# Run a Standard SQL query with the project set explicitly
project_id = "your-project-id"
df = client.query(sql, project=project_id).to_dataframe()

使用旧版 SQL 语法查询数据

以下示例演示了如何使用旧版 SQL 语法运行查询。如需了解如何将查询更新为采用 GoogleSQL，请参阅 GoogleSQL 迁移指南。

pandas-gbq：

import pandas

sql = """
    SELECT name
    FROM [bigquery-public-data:usa_names.usa_1910_current]
    WHERE state = 'TX'
    LIMIT 100
"""

df = pandas.read_gbq(sql, dialect="legacy")

google-cloud-bigquery：

from google.cloud import bigquery

client = bigquery.Client()
sql = """
    SELECT name
    FROM [bigquery-public-data:usa_names.usa_1910_current]
    WHERE state = 'TX'
    LIMIT 100
"""
query_config = bigquery.QueryJobConfig(use_legacy_sql=True)

df = client.query(sql, job_config=query_config).to_dataframe()

使用 BigQuery Storage API 下载大型结果

使用 BigQuery Storage API 将大型结果的下载速度提高 15 至 31 倍。

pandas-gbq：

import pandas

sql = "SELECT * FROM `bigquery-public-data.irs_990.irs_990_2012`"

# Use the BigQuery Storage API to download results more quickly.
df = pandas.read_gbq(sql, dialect="standard", use_bqstorage_api=True)

google-cloud-bigquery：

from google.cloud import bigquery

client = bigquery.Client()
sql = "SELECT * FROM `bigquery-public-data.irs_990.irs_990_2012`"

# The client library uses the BigQuery Storage API to download results to a
# pandas dataframe if the API is enabled on the project, the
# `google-cloud-bigquery-storage` package is installed, and the `pyarrow`
# package is installed.
df = client.query(sql).to_dataframe()

通过配置运行查询

要执行某些复杂操作（例如运行参数化查询或指定目标表来存储查询结果），需要通过 BigQuery API 请求发送配置。在 pandas-gbq 中，必须按照 BigQuery REST 参考中指定的格式以字典形式发送配置。google-cloud-bigquery 提供了作业配置类（例如 QueryJobConfig），其中包含用于配置复杂作业的必要属性。

以下示例演示了如何使用指定参数运行查询。

pandas-gbq：

import pandas

sql = """
    SELECT name
    FROM `bigquery-public-data.usa_names.usa_1910_current`
    WHERE state = @state
    LIMIT @limit
"""
query_config = {
    "query": {
        "parameterMode": "NAMED",
        "queryParameters": [
            {
                "name": "state",
                "parameterType": {"type": "STRING"},
                "parameterValue": {"value": "TX"},
            },
            {
                "name": "limit",
                "parameterType": {"type": "INTEGER"},
                "parameterValue": {"value": 100},
            },
        ],
    }
}

df = pandas.read_gbq(sql, configuration=query_config)

google-cloud-bigquery：

from google.cloud import bigquery

client = bigquery.Client()
sql = """
    SELECT name
    FROM `bigquery-public-data.usa_names.usa_1910_current`
    WHERE state = @state
    LIMIT @limit
"""
query_config = bigquery.QueryJobConfig(
    query_parameters=[
        bigquery.ScalarQueryParameter("state", "STRING", "TX"),
        bigquery.ScalarQueryParameter("limit", "INTEGER", 100),
    ]
)

df = client.query(sql, job_config=query_config).to_dataframe()

将 pandas DataFrame 数据加载到 BigQuery 表中

两个库都支持将 pandas DataFrame 中的数据上传到 BigQuery 中的新表。二者的主要区别如下所示：

	pandas-gbq	google-cloud-bigquery
类型支持	将要发送到 API 的 DataFrame 数据转换为 CSV 格式，该格式不支持嵌套值或数组值。	将要发送到 API 的 DataFrame 数据转换为 Parquet 或 CSV 格式，该格式支持嵌套值和数组值。为结构体和数组值选择 Parquet，为日期和时间序列化灵活性选择 CSV。Parquet 是默认选项。请注意，pyarrow 是用于将 DataFrame 数据发送到 BigQuery API 的 parquet 引擎，因此必须安装该引擎才能将 DataFrame 数据加载到表中。
加载配置	按照 BigQuery REST 参考中指定的格式，以字典形式发送。	使用 LoadJobConfig 类，其中包含各种 API 配置选项的属性。

pandas-gbq：

import pandas

df = pandas.DataFrame(
    {
        "my_string": ["a", "b", "c"],
        "my_int64": [1, 2, 3],
        "my_float64": [4.0, 5.0, 6.0],
        "my_timestamp": [
            pandas.Timestamp("1998-09-04T16:03:14"),
            pandas.Timestamp("2010-09-13T12:03:45"),
            pandas.Timestamp("2015-10-02T16:00:00"),
        ],
    }
)
table_id = "my_dataset.new_table"

df.to_gbq(table_id)

google-cloud-bigquery：

google-cloud-bigquery 软件包要求 pyarrow 库将 pandas DataFrame 序列化为 Parquet 文件。

安装 pyarrow 软件包。

 conda install -c conda-forge pyarrow

或

 pip install pyarrow

from google.cloud import bigquery
import pandas

df = pandas.DataFrame(
    {
        "my_string": ["a", "b", "c"],
        "my_int64": [1, 2, 3],
        "my_float64": [4.0, 5.0, 6.0],
        "my_timestamp": [
            pandas.Timestamp("1998-09-04T16:03:14"),
            pandas.Timestamp("2010-09-13T12:03:45"),
            pandas.Timestamp("2015-10-02T16:00:00"),
        ],
    }
)
client = bigquery.Client()
table_id = "my_dataset.new_table"
# Since string columns use the "object" dtype, pass in a (partial) schema
# to ensure the correct BigQuery data type.
job_config = bigquery.LoadJobConfig(
    schema=[
        bigquery.SchemaField("my_string", "STRING"),
    ]
)

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

# Wait for the load job to complete.
job.result()

pandas-gbq 不支持的功能

虽然 pandas-gbq 库提供了一个可以查询数据并将数据写入表中的实用接口，但它并不具备 BigQuery API 的众多功能，包括但不限于：

• 管理数据集，包括创建新数据集、更新数据集属性和删除数据集
• 将非 pandas DataFrame 格式的数据加载到 BigQuery 中
• 管理表，包括列出数据集中的表、复制表数据和删除表
• 将 BigQuery 数据直接导出到 Cloud Storage