Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

使用開放原始碼 Python 程式庫

您可以在 BigQuery 中使用開放原始碼 Python 程式庫，以熟悉的程式碼處理資料、建構機器學習 (ML) 模型，以及管理雲端資源。為工作負載選擇合適的程式庫，有助於有效率地從輕量用戶端指令碼，擴充至使用 BigQuery 伺服器端引擎處理數 TB 的資料。

程式庫	用途	資料大小上限	說明
`bigquery-dataframes`	使用伺服器端處理，執行 Python 資料處理和機器學習作業	可擴充至多 TB 資料集 (伺服器端下推)	Pandas 和 scikit-learn API 採用伺服器端下推技術，詳情請參閱「BigQuery DataFrames 簡介」。
`pandas-gbq`	使用用戶端資料複製功能，以 Python 處理資料	受限於用戶端記憶體	可讓您在用戶端與 Python DataFrame 之間移動資料。詳情請參閱說明文件和原始碼。
`google-cloud-bigquery`	BigQuery 部署、管理和 SQL 查詢	受限於用戶端記憶體	Python 套件，可包裝所有 BigQuery API。詳情請參閱說明文件和原始碼。

使用 BigQuery DataFrames、pandas-gbq 和 google-cloud-bigquery

BigQuery DataFrames (bigframes) 程式庫提供 Pythonic DataFrame 和機器學習 API，並具備伺服器端查詢處理功能。pandas-gbq 程式庫提供介面，可用於執行查詢及將 pandas DataFrame 上傳至 BigQuery。它是 BigQuery 用戶端程式庫 google-cloud-bigquery 的精簡包裝函式。

安裝程式庫

如要使用本指南中的程式碼範例，請安裝 bigframes、pandas-gbq 和 google-cloud-bigquery 套件：

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

執行中的查詢數

這三個程式庫都支援查詢儲存在 BigQuery 中的資料。主要差異包括：

	bigquery-dataframes	pandas-gbq	google-cloud-bigquery
預設 SQL 語法	GoogleSQL	GoogleSQL (可透過 `pandas_gbq.context.dialect` 設定)	GoogleSQL
查詢設定	可使用 `bpd.options.bigquery` 或 `read_gbq` 參數設定	以查詢要求格式的字典形式傳送。	使用 `QueryJobConfig` 類別，其中包含各種 API 設定選項的屬性。

使用 GoogleSQL 語法查詢資料

下列範例說明如何在明確指定和未指定專案的情況下，執行 GoogleSQL 查詢。對於這三個程式庫，如果未指定專案，系統會根據預設憑證決定專案。

bigquery-dataframes

import bigframes.pandas as bpd

# Set partial ordering mode for BigQuery DataFrames.
bpd.options.bigquery.ordering_mode = "partial"


def query_standard_sql(project_id: str = "your-project-id") -> bpd.DataFrame:
    """Runs a standard SQL query using BigQuery DataFrames."""
    sql = """
    SELECT name FROM `bigquery-public-data.usa_names.usa_1910_current`
    WHERE state = 'TX'
    LIMIT 100
    """

    # Run a query alongside existing SQL. The project will be determined from
    # default credentials.
    df = bpd.read_gbq(sql)

    # Run a query after explicitly specifying a project.
    bpd.close_session()
    bpd.options.bigquery.project = project_id
    df = bpd.read_gbq(sql)
    return df


# Run the sample:
# df = query_standard_sql("your-project-id")
# print(df.head())

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 遷移指南。

bigquery-dataframes

BigQuery DataFrames 不支援舊版 SQL 語法。請改用 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 倍。

bigquery-dataframes

import bigframes.pandas as bpd
import pandas as pd

# Set partial ordering mode for BigQuery DataFrames.
bpd.options.bigquery.ordering_mode = "partial"


def query_bqstorage() -> pd.DataFrame:
    """Queries BigQuery and downloads results using the BigQuery Storage API."""
    sql = """
    SELECT name FROM `bigquery-public-data.usa_names.usa_1910_current`
    WHERE state = 'TX'
    LIMIT 100
    """

    # Read query results into a server-side DataFrame without downloading data.
    df = bpd.read_gbq(sql)

    # When downloading results to an in-memory pandas DataFrame,
    # bigquery-dataframes automatically uses the BigQuery Storage API if
    # installed.
    pandas_df = df.to_pandas()
    return pandas_df


# Run the sample:
# pandas_df = query_bqstorage()
# print(pandas_df.head())

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 要求傳送設定，才能執行某些複雜作業，例如執行參數化查詢，或是指定要儲存查詢結果的目標資料表。在 bigquery-dataframes (read_gbq) 和 pandas-gbq 中，設定必須以查詢要求格式的字典形式傳送。google-cloud-bigquery 提供工作設定類別，例如 QueryJobConfig，其中包含設定複雜工作所需的屬性。

以下範例顯示如何使用具名參數執行查詢。

bigquery-dataframes

import bigframes.pandas as bpd

# Set partial ordering mode for BigQuery DataFrames.
bpd.options.bigquery.ordering_mode = "partial"


def query_parameters() -> bpd.DataFrame:
    """Queries BigQuery using BigQuery DataFrames with query parameters."""
    sql = """
    SELECT name FROM `bigquery-public-data.usa_names.usa_1910_current`
    WHERE state = @state
    LIMIT 100
    """

    query_config = {
        "query": {
            "parameterMode": "NAMED",
            "queryParameters": [
                {
                    "name": "state",
                    "parameterType": {"type": "STRING"},
                    "parameterValue": {"value": "TX"},
                }
            ],
        }
    }

    df = bpd.read_gbq(sql, configuration=query_config)
    return df


# Run the sample:
# df = query_parameters()
# print(df.head())

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 的新資料表。主要差異如下：

	bigquery-dataframes	pandas-gbq	google-cloud-bigquery
支援類型	使用 `read_pandas` 轉換 DataFrame，並使用 `to_gbq` 將其寫入資料表。	將 DataFrame 轉換為 CSV 格式，再傳送至不支援巢狀或陣列值的 API。	將 DataFrame 轉換為 Parquet 或 CSV 格式，再傳送至 API，支援巢狀和陣列值。如要處理結構體和陣列值，請選擇 Parquet；如要彈性序列化日期和時間，請選擇 CSV。Parquet 是預設選項。請注意，您必須安裝 `pyarrow` (即用來將 DataFrame 資料傳送至 BigQuery API 的 Parquet Engine)，才能將 DataFrame 載入至資料表。
載入設定	使用 `to_gbq` 參數 (例如 `if_exists`) 設定行為。	您可以視需要指定資料表結構定義。	使用 `LoadJobConfig` 類別，其中包含各種 API 設定選項的屬性。

bigquery-dataframes

import bigframes.pandas as bpd
import pandas as pd

# Set partial ordering mode for BigQuery DataFrames.
bpd.options.bigquery.ordering_mode = "partial"


def upload_from_dataframe(
    table_id: str = "your-project.your_dataset.your_table_name",
) -> bpd.DataFrame:
    """Uploads an in-memory pandas DataFrame to a BigQuery table using BigQuery DataFrames."""
    # Create a local pandas DataFrame.
    df = pd.DataFrame(
        {
            "my_string": ["a", "b", "c"],
            "my_int64": [1, 2, 3],
            "my_float64": [4.0, 5.0, 6.0],
        }
    )

    # Convert the local pandas DataFrame to a BigQuery DataFrame.
    bq_df = bpd.read_pandas(df)

    # Write the DataFrame to a BigQuery table.
    bq_df.to_gbq(table_id, if_exists="replace")
    return bq_df


# Run the sample:
# bq_df = upload_from_dataframe("your-project.your_dataset.your_table_name")
# print(bq_df.head())

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 和 bigquery-dataframes 不支援的功能

雖然 pandas-gbq 和 bigquery-dataframes 程式庫提供實用的介面，可用於查詢資料及將資料寫入資料表，但並未涵蓋許多 BigQuery API 功能，包括但不限於：

管理資料集，包括建立新資料集、更新資料集屬性以及刪除資料集
從 pandas DataFrame 以外的格式，或從含有 JSON 資料欄的 pandas DataFrame 將資料載入 BigQuery
管理資料表，包括列出資料集中的資料表、複製資料表的資料以及刪除資料表
直接將 BigQuery 資料匯出至 Cloud Storage

疑難排解連線集區錯誤

錯誤字串：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)