从 pandas-gbq 迁移

pandas-gbq 库是由 pandas 社区主导的项目。BigQuery 客户端库 google-cloud-bigquery 是用来与 BigQuery 进行交互的官方 Python 库。如果您正在使用 pandas-gbq 库,则意味着您已在使用 google-cloud-bigquery 库,因为 pandas-gbq 会使用 google-cloud-bigquery 对 BigQuery 进行 API 调用。此库可让您轻松地从 pandas 连接到 BigQuery,但它并不具备 google-cloud-bigquery 库所能提供的诸多功能。

本主题详细介绍将 Python 代码更新为使用 google-cloud-bigquery(而非 pandas-gbq)所需的更改。本主题中的代码示例使用了这两个库的以下版本:

google-cloud-bigquery[pandas,pyarrow]==1.7.0
pandas-gbq==0.7.0

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

pandas-gbq google-cloud-bigquery
支持 这是由 PyData 和志愿贡献者维护的开放源代码库 这是由 Google 和志愿贡献者维护的开放源代码库
涵盖的 BigQuery API 功能 仅支持运行查询以及将 pandas DataFrame 中的数据保存到表中 支持全部 BigQuery API 功能,并添加了对读取/写入 pandas DataFrame 数据以及用于运行查询的 Jupyter 魔法命令的支持
新功能的实现速率 新功能只会在通过志愿贡献者实现后添加到库中 新功能在 BigQuery API 中一旦发布即可实现
文档/源代码 文档/源代码

运行查询

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

pandas-gbq google-cloud-bigquery
默认 SQL 语法 旧版 SQL 标准 SQL
查询配置 按照 BigQuery REST 参考中指定的格式,以字典形式发送。 使用 QueryJobConfig 类,其中包含各种 API 配置选项的属性。

使用标准 SQL 语法查询数据

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

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 语法运行查询。如需将查询更新为标准 SQL 的指导,请参阅标准 SQL 迁移指南

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 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 格式,该格式支持嵌套值和数组值。请注意,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],
    }
)
full_table_id = 'my_dataset.new_table'
project_id = 'my-project-id'

df.to_gbq(full_table_id, project_id=project_id)

google-cloud-bigquery

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

安装 pyarrow 软件包:

 pip install pyarrow

 conda install -c conda-forge 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],
    }
)
client = bigquery.Client()
dataset_ref = client.dataset('my_dataset')
table_ref = dataset_ref.table('new_table')

client.load_table_from_dataframe(df, table_ref).result()

pandas-gbq 不支持的功能

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

此页内容是否有用?请给出您的反馈和评价:

发送以下问题的反馈:

此网页
需要帮助?请访问我们的支持页面