从 pandas-gbq 迁移

pandas-gbq 库是由 pandas 社区主导的项目。BigQuery 客户端库 google-cloud-bigquery 是用于与 BigQuery 进行交互的官方 Python 库。如果您正在使用 pandas-gbq 库,则意味着您已在使用 google-cloud-bigquery 库。pandas-gbq 使用 google-cloud-bigquery 对 BigQuery 进行 API 调用。

本主题提供了用于比较 google-cloud-bigquerypandas-gbq 的代码示例。本主题中的代码示例使用以下库:

google-cloud-bigquery==1.20.0
google-cloud-bigquery-storage==0.7.0
pandas==0.25.1
pandas-gbq==0.11.0
pyarrow==0.14.1

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

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(可通过 pandas_gbq.context.dialect 配置) 标准 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 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

import google.auth
from google.cloud import bigquery
from google.cloud import bigquery_storage_v1beta1

# Create a BigQuery client and a BigQuery Storage API client with the same
# credentials to avoid authenticating twice.
credentials, project_id = google.auth.default(
    scopes=["https://www.googleapis.com/auth/cloud-platform"]
)
client = bigquery.Client(credentials=credentials, project=project_id)
bqstorage_client = bigquery_storage_v1beta1.BigQueryStorageClient(
    credentials=credentials
)
sql = "SELECT * FROM `bigquery-public-data.irs_990.irs_990_2012`"

# Use a BigQuery Storage API client to download results more quickly.
df = client.query(sql).to_dataframe(bqstorage_client=bqstorage_client)

通过配置运行查询

要执行某些复杂操作(例如运行参数化查询或指定目标表来存储查询结果),需要通过 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],
        '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 的众多功能,包括但不限于: