Python ライブラリを選択する

BigQuery では、ユースケースに応じて 3 つの Python ライブラリから選択できます。

	ユースケース	管理者	説明
BigQuery DataFrames	サーバーサイドによる Python ベースのデータ処理と ML オペレーション（スロットの使用など）	Google	サーバーサイドのプッシュダウンで実装された Pandas と Scikit learn API。詳細については、BigQuery DataFrames の概要をご覧ください。
pandas-gbq	クライアントサイドのデータコピーを使用した Python ベースのデータ処理	PyData とボランティアが管理するオープンソースライブラリ	クライアントサイドで Python DataFrame とデータをやり取りします。詳細については、ドキュメントとソースコードをご覧ください。
google-cloud-bigquery	BigQuery のデプロイ、管理、SQL ベースのクエリ	Google が管理するオープンソースライブラリ	すべての BigQuery API をラップする Python パッケージ。詳細については、ドキュメントとソースコードをご覧ください。

pandas-gbq と google-cloud-bigquery の使用

pandas-gbq ライブラリは、クエリを実行し、pandas データフレームを BigQuery にアップロードするシンプルなインターフェースを提供します。これは、BigQuery クライアントライブラリ google-cloud-bigquery のシンラッパーです。どちらのライブラリも、SQL を使用したデータ分析のサポートに重点を置いています。

ライブラリをインストールする

このガイドのコードサンプルを使用するには、pandas-gbq パッケージと BigQuery Python クライアントライブラリをインストールします。

pandas-gbq パッケージと google-cloud-bigquery パッケージをインストールします。

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

クエリの実行

どちらのライブラリも、BigQuery に保存されているデータのクエリをサポートしています。ライブラリ間の主な違いは次のとおりです。

	pandas-gbq	google-cloud-bigquery
デフォルトの SQL 構文	GoogleSQL（`pandas_gbq.context.dialect` で構成可能）	GoogleSQL
クエリの構成	クエリリクエストの形式で辞書として送信します。	さまざまな API 構成オプションのプロパティを含む `QueryJobConfig` クラスを使用します。

GoogleSQL 構文を使用したデータのクエリ

次の例では、プロジェクトを明示的に指定して GoogleSQL クエリを実行する方法と、明示的に指定せずに Google Cloud クエリを実行する方法を示しています。どちらのライブラリでも、プロジェクトが指定されていない場合、プロジェクトはデフォルトの認証情報から決定されます。

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 では、クエリリクエストの形式で辞書として構成を送信する必要があります。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 形式または CSV 形式に変換してから API に送信します。ネストされた値と配列値がサポートされます。構造体と配列の値には Parquet を選択します。日付と時刻のシリアル化の柔軟性を高めるには CSV を選択します。Parquet がデフォルトの選択肢です。DataFrame をテーブルに読み込むには、`pyarrow`（DataFrame のデータを BigQuery API へ送信するのに使う parquet エンジン）をインストールする必要があります。
読み込みの構成	必要に応じて、テーブルスキーマを指定できます。	さまざまな 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],
        "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 パッケージをインストールします。

 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 DataFrames 以外の形式または JSON 列を含む pandas DataFrames から BigQuery にデータを読み込む
テーブル管理: データセット内のテーブルの一覧表示、テーブルデータのコピー、テーブルの削除など
Cloud Storage に直接、BigQuery データをエクスポートすること

接続プールのエラーのトラブルシューティング

エラー文字列: Connection pool is full, discarding connection: bigquery.googleapis.com. Connection pool size: 10

Python でデフォルトの BigQuery クライアントオブジェクトを使用する場合、Python HTTPAdapter のデフォルトのプールサイズは 10 であるため、最大 10 個のスレッドに制限されます。10 個を超える接続を使用するには、カスタムの requests.adapters.HTTPAdapter オブジェクトを作成します。次に例を示します。

client = bigquery.Client()
adapter = requests.adapters.HTTPAdapter(pool_connections=128,
pool_maxsize=128,max_retries=3)
client._http.mount("https://",adapter)
client._http._auth_request.session.mount("https://",adapter)
query_job = client.query(QUERY)