pandas-gbq からの移行

pandas-gbq ライブラリは、pandas コミュニティによるコミュニティ主導のプロジェクトです。BigQuery クライアント ライブラリgoogle-cloud-bigquery は、BigQuery とやり取りするための公式 Python ライブラリです。pandas-gbq ライブラリを使用している場合、すでに google-cloud-bigquery ライブラリを使用しています。pandas-gbqgoogle-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

2 つのライブラリの機能レベルおよびサポートレベルの違いのうち主なものは以下のとおりです。

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()

BigQuery テーブルに pandas DataFrame を読み込む

どちらのライブラリも、pandas DataFrame から BigQuery の新しいテーブルへのデータのアップロードをサポートしています。主な違いは次のとおりです。

pandas-gbq google-cloud-bigquery
サポートされる型 DataFrame を CSV 形式に変換してから API に送信。ネストした値と配列値はサポートしません。 DataFrame を Parquet 形式に変換してから API に送信。ネストした値と配列値をサポートします。pyarrow(DataFrame のデータを BigQuery API へ送信するのに使う parquet エンジン)は、DataFrame をテーブルに読み込むためにインストールする必要があります。
読み込みの構成 BigQuery REST リファレンス指定の形式で辞書として送信します。 さまざまな API 構成オプションのプロパティを含む LoadJobConfig クラスを使用します。

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],
    }
)
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],
    }
)
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 の機能の多くには対応していません。

このページは役立ちましたか?評価をお願いいたします。

フィードバックを送信...

ご不明な点がありましたら、Google のサポートページをご覧ください。