從 pandas-gbq 遷移

pandas-gbq 程式庫是由 pandas 社群發起的專案,BigQuery 用戶端程式庫 (google-cloud-bigquery) 則是 Python 用來與 BigQuery 互動的官方程式庫。如果您可以使用 pandas-gbq 程式庫,即表示您已在使用 google-cloud-bigquery 程式庫。pandas-gbq 會透過 google-cloud-bigquery 向 BigQuery 執行 API 呼叫。這個程式庫提供從 pandas 向 BigQuery 執行操作的簡易介面,但不具備 google-cloud-bigquery 程式庫提供的許多功能。

您必須更新 Python 程式碼才能從 pandas-gbq 改為使用 google-cloud-bigquery,相關變更詳情請參考以下說明。本文中的程式碼範例是出自這兩種程式庫的以下版本:

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 DataFrames 和可執行查詢的 Jupyter Magic 指令
發佈新功能的頻率 新功能必須由自願貢獻者導入才能新增至程式庫 新功能在 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。 由於 API 支援巢狀結構值或陣列值,因此會將 DataFrame 轉換為 Parquet 格式後才傳送至 API。請注意,您必須安裝 pyarrow (即用來將 DataFrame 資料傳送至 BigQuery API 的 Parquet Engine),才能將 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

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

本頁內容對您是否有任何幫助?請提供意見:

傳送您對下列選項的寶貴意見...

這個網頁