選擇 Python 程式庫

您可以根據用途，在 BigQuery 中選擇三種 Python 程式庫。

用途 維護者： 說明
BigQuery DataFrames 以 Python 為基礎的資料處理和機器學習作業，並搭配伺服器端處理作業 (例如使用時段) Google Pandas 和 Scikit 學習 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
查詢設定 以字典形式傳送，格式為查詢要求。 使用 QueryJobConfig 類別，其中包含各種 API 設定選項的屬性。

使用 GoogleSQL 語法查詢資料

以下範例顯示如何在明確/未明確指定專案的情況下，執行 GoogleSQL 查詢。兩種程式庫在未指定專案時，均會根據預設憑證來判定專案。

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

將 pandas DataFrame 載入 BigQuery 表格

兩種程式庫均支援將 pandas DataFrame 資料上傳至新的 BigQuery 資料表。主要差異如下：

pandas-gbq google-cloud-bigquery
支援類型 由於 API 不支援巢狀結構值或陣列值，因此會將 DataFrame 轉換為 CSV 格式後才傳送至 API。 由於 API 支援巢狀結構值或陣列值，因此會將 DataFrame 轉換為 Parquet 或 CSV 格式後才傳送至 API。請選擇 Parquet 來處理結構體和陣列值，並選擇 CSV 來處理日期和時間序列化彈性。預設會選擇 Parquet。請注意，您必須安裝 pyarrow (即用來將 DataFrame 資料傳送至 BigQuery API 的 Parquet Engine)，才能將 DataFrame 載入至資料表。
載入設定 您可以選擇指定資料表結構定義。 使用 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 套件：

 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 功能，包括 (但不限於) 以下功能：

排解連線集區錯誤

錯誤字串：Connection pool is full, discarding connection: bigquery.googleapis.com. Connection pool size: 10

如果您在 Python 中使用預設的 BigQuery 用戶端物件，則最多只能使用 10 個執行緒，因為 Python HTTPAdapter 的預設集區大小為 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)