BigQuery DataFrames を使用する

BigQuery DataFrames は、BigQuery エンジンによる Pythonic DataFrame と ML API を提供します。BigQuery DataFrames は、オープンソースのパッケージです。 pip install --upgrade bigframes を実行すると、最新バージョンをインストールできます。

BigQuery DataFrames には、次の 3 つのライブラリが用意されています。

  • bigframes.pandas は、BigQuery でデータの分析と操作に使用できる pandas API を提供します。多くのワークロードは、インポートをいくつか変更するだけで pandas から bigframes に移行できます。bigframes.pandas API は、テラバイト単位の BigQuery データの処理をサポートするようにスケーラブルで、BigQuery クエリエンジンを使用して計算を実行します。
  • bigframes.bigquery には、相当するものが pandas にない BigQuery SQL 関数が多く用意されています。
  • bigframes.ml は、ML 用の scikit-learn API と同様の API を提供します。BigQuery DataFrames の ML 機能を使用すると、データを前処理してから、そのデータでモデルをトレーニングできます。また、これらのアクションを連結してデータ パイプラインを作成することもできます。

必要なロール

このドキュメントのタスクを完了するために必要な権限を取得するには、プロジェクトに対する次の IAM ロールを付与するよう管理者に依頼してください。

ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

また、BigQuery DataFrames リモート関数または BigQuery DataFrames ML リモートモデルを使用する場合は、デフォルトの BigQuery 接続を使用している場合はプロジェクト IAM 管理者ロール（roles/resourcemanager.projectIamAdmin）、事前構成済みの接続を使用している場合は参照者ロール（roles/browser）が必要です。この要件は、bigframes.pandas.options.bigquery.skip_bq_connection_check オプションを True に設定することで回避できます。この場合、接続（デフォルトまたは事前構成）は存在チェックや権限チェックなしでそのまま使用されます。事前構成された接続を使用して接続チェックを省略する場合は、次のことを確認します。

  • 接続が適切な場所に作成されている。
  • BigQuery DataFrames リモート関数を使用している場合、サービス アカウントにはプロジェクトに対する Cloud Run 起動元ロール（roles/run.invoker）があります。
  • BigQuery DataFrames ML リモートモデルを使用している場合、サービス アカウントにはプロジェクトに対する Vertex AI ユーザーロール（roles/aiplatform.user）が付与されています。

ノートブック、Python REPL、コマンドラインなどのインタラクティブ環境でエンドユーザー認証を実行する場合は、必要に応じて BigQuery DataFrames が認証を要求します。それ以外の場合は、さまざまな環境でアプリケーションのデフォルト認証情報を設定する方法をご覧ください。

インストール オプションを構成する

BigQuery DataFrames をインストールしたら、次のオプションを指定できます。

場所とプロジェクト

BigQuery DataFrames を使用するロケーションとプロジェクトを指定する必要があります。

ノートブックのロケーションとプロジェクトは、次の方法で定義できます。

import bigframes.pandas as bpd

PROJECT_ID = "bigframes-dev"  # @param {type:"string"}
REGION = "US"  # @param {type:"string"}

# Set BigQuery DataFrames options
# Note: The project option is not required in all environments.
# On BigQuery Studio, the project ID is automatically detected.
bpd.options.bigquery.project = PROJECT_ID

# Note: The location option is not required.
# It defaults to the location of the first table or query
# passed to read_gbq(). For APIs where a location can't be
# auto-detected, the location defaults to the "US" location.
bpd.options.bigquery.location = REGION

データ処理のロケーション

BigQuery DataFrames はスケールすることを考慮して設計されており、BigQuery サービス上にデータと処理を保持することで実現しています。ただし、DataFrame オブジェクトや Series オブジェクトで .to_pandas() を呼び出すと、クライアント マシンのメモリにデータを取り込むことができます。この方法を選択した場合は、クライアント マシンのメモリ制限が適用されます。

セッションの場所

BigQuery DataFrames は、メタデータの管理に内部的にローカル セッション オブジェクトを使用します。このセッションはロケーションに関連付けられます。BigQuery DataFrames は、デフォルトのロケーションとして US マルチリージョンを使用しますが、session_options.location を使用して別のロケーションを設定できます。セッション内の各クエリは、そのセッションが作成されたロケーションで実行されます。ユーザーが read_gbq/read_gbq_table/read_gbq_query() で開始し、直接または SQL ステートメントでテーブルを指定すると、BigQuery DataFrames により、テーブルのロケーションが bf.options.bigquery.location に自動的に入力されます。

作成した DataFrame オブジェクトや Series オブジェクトのロケーションをリセットする場合は、bigframes.pandas.close_session() を実行してセッションを閉じます。その後、bigframes.pandas.options.bigquery.location を再利用して別のロケーションを指定できます。

read_gbq() では、クエリ対象のデータセットが US のマルチリージョンにない場合は、ロケーションを指定する必要があります。別のロケーションからテーブルを読み取ろうとすると、NotFound 例外が発生します。

BigQuery DataFrames バージョン 2.0 に移行する

BigQuery DataFrames のバージョン 2.0 では、BigQuery DataFrames API のセキュリティとパフォーマンスが改善され、新機能が追加され、互換性のない変更が導入されています。このドキュメントでは、変更点と移行のガイダンスについて説明します。これらの推奨事項は、BigQuery DataFrames の最新のバージョン 1.x を使用して、バージョン 2.0 をインストールする前に適用できます。

BigQuery DataFrames バージョン 2.0 には、次の利点があります。

  • allow_large_results のデフォルトは False であるため、結果をクライアントに返すクエリを実行すると、クエリが高速になり、作成されるテーブルの数が少なくなります。これにより、特に物理バイト課金を使用している場合に、ストレージ費用を削減できます。
  • BigQuery DataFrames によってデプロイされたリモート関数のデフォルトのセキュリティが強化されました。

BigQuery DataFrames バージョン 2.0 をインストールする

互換性のない変更を避けるため、requirements.txt ファイル（bigframes==1.42.0 など）または pyproject.toml ファイル（dependencies = ["bigframes = 1.42.0"] など）で BigQuery DataFrames の特定のバージョンに固定します。最新バージョンを試す準備ができたら、pip install --upgrade bigframes を実行して BigQuery DataFrames の最新バージョンをインストールできます。

allow_large_results オプションを使用する

BigQuery には、クエリジョブの最大レスポンス サイズの上限があります。BigQuery DataFrames バージョン 2.0 以降では、BigQuery DataFrames は、peek()、to_pandas()、to_pandas_batches() など、結果をクライアントに返すメソッドでこの上限をデフォルトで適用します。ジョブから大きな結果が返される場合は、変更を回避するために、BigQueryOptions オブジェクトで allow_large_results を True に設定できます。BigQuery DataFrames バージョン 2.0 では、このオプションはデフォルトで False に設定されています。

import bigframes.pandas as bpd

bpd.options.bigquery.allow_large_results = True

to_pandas() などのメソッドで allow_large_results パラメータを使用すると、allow_large_results オプションをオーバーライドできます。次に例を示します。

bf_df = bpd.read_gbq(query)
# ... other operations on bf_df ...
pandas_df = bf_df.to_pandas(allow_large_results=True)

@remote_function デコレータを使用する

BigQuery DataFrames バージョン 2.0 では、@remote_function デコレーターのデフォルトの動作が変更されています。

曖昧なパラメータに対してキーワード引数が強制される

意図しないパラメータに値が渡されないように、BigQuery DataFrames バージョン 2.0 以降では、次のパラメータにキーワード引数を使用する必要があります。

  • bigquery_connection
  • reuse
  • name
  • packages
  • cloud_function_service_account
  • cloud_function_kms_key_name
  • cloud_function_docker_repository
  • max_batching_rows
  • cloud_function_timeout
  • cloud_function_max_instances
  • cloud_function_vpc_connector
  • cloud_function_memory_mib
  • cloud_function_ingress_settings

これらのパラメータを使用する場合は、パラメータ名を指定します。次に例を示します。

@remote_function(
  name="my_remote_function",
  ...
)
def my_remote_function(parameter: int) -> str:
  return str(parameter)

サービス アカウントを設定する

バージョン 2.0 以降、BigQuery DataFrames は、デプロイする Cloud Run functions にデフォルトで Compute Engine サービス アカウントを使用しなくなりました。デプロイする関数の権限を制限するには、

  1. 最小限の権限を持つサービス アカウントを作成します。
  2. @remote_function デコレータの cloud_function_service_account パラメータにサービス アカウントのメールアドレスを指定します。

次に例を示します。

@remote_function(
  cloud_function_service_account="[email protected]",
  ...
)
def my_remote_function(parameter: int) -> str:
  return str(parameter)

Compute Engine サービス アカウントを使用する場合は、@remote_function デコレーターの cloud_function_service_account パラメータを "default" に設定します。次に例を示します。

# This usage is discouraged. Use only if you have a specific reason to use the
# default Compute Engine service account.
@remote_function(cloud_function_service_account="default", ...)
def my_remote_function(parameter: int) -> str:
  return str(parameter)

上り（内向き）設定を行う

バージョン 2.0 以降、BigQuery DataFrames は、デプロイする Cloud Run functions の上り（内向き）設定を "internal-only" に設定します。以前は、上り（内向き）設定はデフォルトで "all" に設定されていました。上り（内向き）設定を変更するには、@remote_function デコレータの cloud_function_ingress_settings パラメータを設定します。次に例を示します。

@remote_function(cloud_function_ingress_settings="internal-and-gclb", ...)
def my_remote_function(parameter: int) -> str:
  return str(parameter)

カスタム エンドポイントを使用する

2.0 より前の BigQuery DataFrames バージョンでは、リージョンがリージョン サービス エンドポイントと bigframes.pandas.options.bigquery.use_regional_endpoints = True をサポートしていない場合、BigQuery DataFrames はロケーション エンドポイントにフォールバックしていました。BigQuery DataFrames のバージョン 2.0 では、このフォールバック動作が削除されています。バージョン 2.0 のロケーション エンドポイントに接続するには、bigframes.pandas.options.bigquery.client_endpoints_override オプションを設定します。次に例を示します。

import bigframes.pandas as bpd

bpd.options.bigquery.client_endpoints_override = {
  "bqclient": "https://LOCATION-bigquery.googleapis.com",
  "bqconnectionclient": "LOCATION-bigqueryconnection.googleapis.com",
  "bqstoragereadclient": "LOCATION-bigquerystorage.googleapis.com",
}

LOCATION は、接続する BigQuery ロケーションの名前に置き換えます。

bigframes.ml.llm モジュールを使用する

BigQuery DataFrames バージョン 2.0 では、GeminiTextGenerator のデフォルトの model_name が "gemini-2.0-flash-001" に更新されました。今後デフォルト モデルが変更された場合に破損を回避するため、model_name を直接指定することをおすすめします。

import bigframes.ml.llm

model = bigframes.ml.llm.GeminiTextGenerator(model_name="gemini-2.0-flash-001")

入力と出力

bigframes.pandas ライブラリを使用すると、ローカル CSV ファイル、Cloud Storage ファイル、pandas DataFrame、BigQuery モデル、BigQuery 関数など、さまざまなソースのデータにアクセスできます。その後、そのデータを BigQuery DataFrames DataFrame に読み込むことができます。BigQuery DataFrames から BigQuery テーブルを作成することもできます。

BigQuery テーブルまたはクエリからデータを読み込む

次の方法で、BigQuery テーブルまたはクエリから DataFrame を作成できます。

# Create a DataFrame from a BigQuery table:
import bigframes.pandas as bpd

query_or_table = "bigquery-public-data.ml_datasets.penguins"
bq_df = bpd.read_gbq(query_or_table)

CSV ファイルからデータを読み込む

DataFrame は、ローカルまたは Cloud Storage CSV ファイルから次の方法で作成できます。

import bigframes.pandas as bpd

filepath_or_buffer = "gs://cloud-samples-data/bigquery/us-states/us-states.csv"
df_from_gcs = bpd.read_csv(filepath_or_buffer)
# Display the first few rows of the DataFrame:
df_from_gcs.head()

データ型

BigQuery DataFrames は、次の numpy と pandas の dtype をサポートしています。

BigQuery BigQuery DataFrames と pandas
ARRAY pandas.ArrowDtype(pa.list_())
BOOL pandas.BooleanDtype()
DATE pandas.ArrowDtype(pa.date32())
DATETIME pandas.ArrowDtype(pa.timestamp("us"))
FLOAT64 pandas.Float64Dtype()
GEOGRAPHY

geopandas.array.GeometryDtype()

to_pandas() でのみサポート
INT64 pandas.Int64Dtype()
JSON pandas バージョン 3.0 以降と pyarrow バージョン 19.0 以降では pandas.ArrowDtype(pa.json_(pa.string())。それ以外の場合は、JSON 列は pandas.ArrowDtype(db_dtypes.JSONArrowType()) として公開されます。
STRING pandas.StringDtype(storage="pyarrow")
STRUCT pandas.ArrowDtype(pa.struct())
TIME pandas.ArrowDtype(pa.time64("us"))
TIMESTAMP pandas.ArrowDtype(pa.timestamp("us", tz="UTC"))

BigQuery DataFrames では、以下の BigQuery データ型をサポートしていません。

  • NUMERIC

  • BIGNUMERIC

  • INTERVAL

  • RANGE

他のすべての BigQuery データ型はオブジェクト型として表示されます。

データの操作

以降のセクションでは、BigQuery DataFrames のデータ操作機能について説明します。bigframes.bigquery ライブラリに記載されている関数を確認できます。

pandas API

BigQuery DataFrames の注目すべき機能は、bigframes.pandas API が pandas ライブラリの API と同様に設計されていることです。この設計により、データ操作タスクに使い慣れた構文パターンを使用できます。BigQuery DataFrames API を介して定義されたオペレーションはサーバーサイドで実行され、BigQuery 内に保存されたデータを直接操作するため、データセットを BigQuery から転送する必要がなくなります。

BigQuery DataFrames でサポートされている pandas API を確認するには、サポートされている pandas API をご覧ください。

データの検査と操作

bigframes.pandas API を使用して、データの検査と計算のオペレーションを実行できます。次のコードサンプルでは、bigframes.pandas ライブラリを使用して body_mass_g 列を検査し、平均 body_mass を計算して、species ごとの平均 body_mass を計算します。

import bigframes.pandas as bpd

# Load data from BigQuery
query_or_table = "bigquery-public-data.ml_datasets.penguins"
bq_df = bpd.read_gbq(query_or_table)

# Inspect one of the columns (or series) of the DataFrame:
bq_df["body_mass_g"]

# Compute the mean of this series:
average_body_mass = bq_df["body_mass_g"].mean()
print(f"average_body_mass: {average_body_mass}")

# Find the heaviest species using the groupby operation to calculate the
# mean body_mass_g:
(
    bq_df["body_mass_g"]
    .groupby(by=bq_df["species"])
    .mean()
    .sort_values(ascending=False)
    .head(10)
)

BigQuery ライブラリ

BigQuery ライブラリには、pandas に相当するものが存在しない BigQuery SQL 関数が用意されています。以降のセクションでは、いくつかの例を紹介します。

配列値を処理する

bigframes.bigquery ライブラリの bigframes.bigquery.array_agg() 関数を使用すると、groupby オペレーションの後に値を集計できます。

import bigframes.bigquery as bbq
import bigframes.pandas as bpd

s = bpd.Series([0, 1, 2, 3, 4, 5])

# Group values by whether they are divisble by 2 and aggregate them into arrays
bbq.array_agg(s.groupby(s % 2 == 0))
# False    [1 3 5]
# True     [0 2 4]
# dtype: list<item: int64>[pyarrow]

array_length() と array_to_string() の配列関数も使用できます。

構造体シリーズを作成する

bigframes.bigquery ライブラリの bigframes.bigquery.struct() 関数を使用して、DataFrame 内の各列のサブフィールドを含む新しい構造体シリーズを作成できます。

import bigframes.bigquery as bbq
import bigframes.pandas as bpd

# Load data from BigQuery
query_or_table = "bigquery-public-data.ml_datasets.penguins"
bq_df = bpd.read_gbq(query_or_table)

# Create a new STRUCT Series with subfields for each column in a DataFrames.
lengths = bbq.struct(
    bq_df[["culmen_length_mm", "culmen_depth_mm", "flipper_length_mm"]]
)

lengths.peek()
# 146	{'culmen_length_mm': 51.1, 'culmen_depth_mm': ...
# 278	{'culmen_length_mm': 48.2, 'culmen_depth_mm': ...
# 337	{'culmen_length_mm': 36.4, 'culmen_depth_mm': ...
# 154	{'culmen_length_mm': 46.5, 'culmen_depth_mm': ...
# 185	{'culmen_length_mm': 50.1, 'culmen_depth_mm': ...
# dtype: struct[pyarrow]

タイムスタンプを Unix エポックに変換する

bigframes.bigquery ライブラリの bigframes.bigquery.unix_micros() 関数を使用して、タイムスタンプを Unix マイクロ秒に変換できます。

import pandas as pd

import bigframes.bigquery as bbq
import bigframes.pandas as bpd

# Create a series that consists of three timestamps: [1970-01-01, 1970-01-02, 1970-01-03]
s = bpd.Series(pd.date_range("1970-01-01", periods=3, freq="d", tz="UTC"))

bbq.unix_micros(s)
# 0               0
# 1     86400000000
# 2    172800000000
# dtype: Int64

unix_seconds() と unix_millis() の時間関数を使用することもできます。

SQL スカラー関数を使用する

bigframes.bigquery ライブラリの bigframes.bigquery.sql_scalar() 関数を使用して、単一列の式を表す任意の SQL 構文にアクセスできます。

import bigframes.bigquery as bbq
import bigframes.pandas as bpd

# Load data from BigQuery
query_or_table = "bigquery-public-data.ml_datasets.penguins"

# The sql_scalar function can be used to inject SQL syntax that is not supported
# or difficult to express with the bigframes.pandas APIs.
bq_df = bpd.read_gbq(query_or_table)
shortest = bbq.sql_scalar(
    "LEAST({0}, {1}, {2})",
    columns=[
        bq_df["culmen_depth_mm"],
        bq_df["culmen_length_mm"],
        bq_df["flipper_length_mm"],
    ],
)

shortest.peek()
#         0
# 149	18.9
# 33	16.3
# 296	17.2
# 287	17.0
# 307	15.0
# dtype: Float64

カスタム Python 関数

BigQuery DataFrames を使用すると、カスタム Python 関数を BigQuery アーティファクトに変換して、BigQuery DataFrames オブジェクトで大規模に実行できます。この拡張機能のサポートにより、BigQuery DataFrames と SQL API で可能な操作を超えた操作を実行できるため、オープンソース ライブラリを活用できる可能性があります。この拡張メカニズムの 2 つのバリエーションについては、以降のセクションで説明します。

ユーザー定義関数（UDF）

UDF（プレビュー）を使用すると、カスタム Python 関数を Python UDF に変換できます。使用例については、永続的な Python UDF を作成するをご覧ください。

BigQuery DataFrames で UDF を作成すると、指定されたデータセットに Python UDF として BigQuery ルーティンが作成されます。サポートされているパラメータの一覧については、udf をご覧ください。

クリーンアップ

Google Cloud コンソールまたは他のツールでクラウド アーティファクトを直接クリーンアップするだけでなく、bigframes.pandas.get_global_session().bqclient.delete_routine(routine_id) コマンドを使用して、明示的な名前引数で作成された BigQuery DataFrames UDF をクリーンアップすることもできます。

要件

BigQuery DataFrames UDF を使用するには、プロジェクトで BigQuery API を有効にします。プロジェクトで bigquery_connection パラメータを指定する場合は、BigQuery Connection API も有効にする必要があります。

制限事項

  • UDF のコードは自己完結型である必要があります。つまり、関数本体の外で定義されたインポートや変数への参照を含んではなりません。
  • UDF のコードは、Python 3.11 と互換性がある必要があります。これは、コードがクラウドで実行される環境であるためです。
  • 関数コードでの些細な変更（変数の名前変更や新しい行の挿入など）の後に UDF 定義コードを再実行すると、これらの変更が関数の動作に影響しない場合でも、UDF が再作成されます。
  • ユーザーコードは、BigQuery ルーティンに対する読み取りアクセス権を持つユーザーに表示されるため、機密性の高いコンテンツは慎重に含める必要があります。
  • プロジェクトには、BigQuery ロケーションに一度に最大 1,000 個の Cloud Run 関数を含めることができます。

BigQuery DataFrames UDF はユーザー定義の BigQuery Python 関数をデプロイするため、関連する制限事項が適用されます。

リモート関数

BigQuery DataFrames を使用すると、カスタム スカラー関数を BigQuery リモート関数に変換できます。使用例については、リモート関数を作成するをご覧ください。サポートされているパラメータの一覧については、remote_function をご覧ください。

BigQuery DataFrames でリモート関数を作成すると、次のものが作成されます。

  • Cloud Run 関数。
  • BigQuery 接続。デフォルトでは、bigframes-default-connection という名前の接続が使用されます。必要に応じて、事前構成済みの BigQuery 接続も使用できます。この場合、接続の作成はスキップされます。デフォルト接続のサービス アカウントには、Cloud Run ロール（roles/run.invoker）が付与されます。
  • BigQuery 接続で作成された Cloud Run 関数を使用する BigQuery リモート関数。

BigQuery 接続は、BigQuery DataFrames セッションと同じロケーションに、カスタム関数定義で指定した名前を使用して作成されます。接続を表示して管理するには、次の手順を行います。

  1. Google Cloud コンソールで、[BigQuery] ページに移動します。

    BigQuery に移動

  2. リモート関数を作成したプロジェクトを選択します。

  3. [エクスプローラ] ペインで、プロジェクトを開き、[外部接続] を開きます。

BigQuery リモート関数は、指定したデータセットに作成されるか、匿名データセット（非表示のデータセットの一種）に作成されます。作成時にリモート関数の名前を設定しないと、BigQuery DataFrames は bigframes で始まるデフォルトの名前を適用します。ユーザー指定のデータセットに作成されたリモート関数を表示して管理するには、次の操作を行います。

  1. Google Cloud コンソールで、[BigQuery] ページに移動します。

    BigQuery に移動

  2. リモート関数を作成したプロジェクトを選択します。

  3. [エクスプローラ] ペインで、プロジェクトを開き、リモート関数を作成したデータセットを開いて、[ルーティン] を開きます。

Cloud Run functions を表示して管理するには、次の操作を行います。

  1. [Cloud Run] ページに移動します。

    Cloud Run に移動します。

  2. 関数を作成したプロジェクトを選択します。

  3. 使用可能なサービスのリストで、[関数デプロイタイプ] でフィルタします。

  4. BigQuery DataFrames で作成された関数を識別するには、bigframes 接頭辞が付いた関数名を探します。

クリーンアップ

Google Cloud コンソールまたは他のツールでクラウド アーティファクトを直接クリーンアップするだけでなく、明示的な名前引数なしで作成された BigQuery リモート関数とそれに関連付けられた Cloud Run 関数は、次の方法でクリーンアップできます。

  • BigQuery DataFrames セッションの場合は、session.close() コマンドを使用します。
  • デフォルトの BigQuery DataFrames セッションの場合は、bigframes.pandas.close_session() コマンドを使用します。
  • session_id を使用した過去のセッションの場合は、bigframes.pandas.clean_up_by_session_id(session_id) コマンドを使用します。

明示的な名前引数を使用して作成された BigQuery リモート関数と、それに関連付けられた Cloud Run functions は、bigframes.pandas.get_global_session().bqclient.delete_routine(routine_id) コマンドを使用してクリーンアップすることもできます。

要件

BigQuery DataFrames リモート関数を使用するには、次の API を有効にする必要があります。

制限事項

  • リモート関数を初めて作成してから、使用可能になるまでに約 90 秒かかります。パッケージの依存関係を追加すると、レイテンシが増加する可能性があります。
  • 関数コードとその周辺で些細な変更（変数の名前変更、新しい行の挿入、ノートブックでの新しいセルの挿入など）を行った後にリモート関数定義コードを再実行すると、これらの変更が関数の動作に影響しない場合でも、リモート関数が再作成されることがあります。
  • ユーザーコードは、Cloud Run functions に対する読み取りアクセス権を持つユーザーに表示されるため、機密性の高いコンテンツは慎重に含める必要があります。
  • プロジェクトには、リージョンごとに最大 1,000 個の Cloud Run 関数を一度に含めることができます。詳しくは、割り当てをご覧ください。

ML と AI

以降のセクションでは、BigQuery DataFrames の ML と AI の機能について説明します。これらの機能は bigframes.ml ライブラリを使用します。

ML のロケーション

bigframes.ml ライブラリは、BigQuery ML と同じロケーションをサポートしています。BigQuery ML モデル予測および他の ML 関数は、すべての BigQuery リージョンでサポートされています。モデル トレーニングのサポートはリージョンによって異なります。詳細については、BigQuery ML のロケーションをご覧ください。

データを前処理する

bigframes.ml.preprocessing モジュールと bigframes.ml.compose モジュールを使用して、推定ツール（モデル）で使用するデータを準備するために変換ツールを作成します。BigQuery DataFrames では、次の変換が用意されています。

  • bigframes.ml.preprocessing モジュールの KBinsDiscretizer クラスを使用して、連続データを区間データにビン化します。

  • bigframes.ml.preprocessing モジュールの LabelEncoder クラスを使用し、ターゲット ラベルを整数値として正規化します。

  • bigframes.ml.preprocessing モジュールの MaxAbsScaler クラスを使用し、各特徴量を最大絶対値で [-1, 1] の範囲にスケールします。

  • bigframes.ml.preprocessing モジュールの MinMaxScaler クラスを使用し、各特徴量を範囲 [0, 1] にスケーリングすることで特徴量を標準化します。

  • bigframes.ml.preprocessing モジュールの StandardScaler クラスを使用し、平均値を除去して、単位分散にスケーリングすることで特徴を標準化します。

  • bigframes.ml.preprocessing モジュールの OneHotEncoder クラスを使用し、カテゴリ値を数値形式に変換します。

  • bigframes.ml.compose モジュールの ColumnTransformer クラスを使用して、DataFrame 列にトランスフォーマーを適用します。

モデルのトレーニング

BigQuery DataFrames でモデルをトレーニングする推定ツールを作成できます。

クラスタ化モデル

bigframes.ml.cluster モジュールを使用して、クラスタリング モデルの推定ツールを作成できます。

  • KMeans クラスを使用して、K 平均法クラスタリング モデルを作成します。これらのモデルはデータのセグメンテーションに使用します。たとえば、お客様のセグメントを特定します。K 平均法は教師なし学習にあたるため、モデルのトレーニングを行う際にラベルは必要なく、トレーニングや評価用にデータの分割を行う必要もありません。

bigframes.ml.cluster モジュールを使用して、クラスタリング モデル用の推定ツールを作成できます。

次のコードサンプルでは、データ セグメンテーション用の K 平均法クラスタリング モデルを作成するために bigframes.ml.cluster KMeans クラスを使用する場合を示します。

from bigframes.ml.cluster import KMeans
import bigframes.pandas as bpd

# Load data from BigQuery
query_or_table = "bigquery-public-data.ml_datasets.penguins"
bq_df = bpd.read_gbq(query_or_table)

# Create the KMeans model
cluster_model = KMeans(n_clusters=10)
cluster_model.fit(bq_df["culmen_length_mm"], bq_df["sex"])

# Predict using the model
result = cluster_model.predict(bq_df)
# Score the model
score = cluster_model.score(bq_df)

分解モデル

bigframes.ml.decomposition モジュールを使用して、分解モデルの推定ツールを作成できます。

  • PCA クラスを使用して、主成分分析（PCA）モデルを作成します。このモデルは、主成分を計算し、その結果を使用してデータに基底変換を行うために使用します。これにより、データのバリエーションをできるだけ多く保持しながら、各データポイントを最初のいくつかの主成分にのみ射影して低次元のデータを取得することで、次元数を削減します。

モデルのアンサンブル

bigframes.ml.ensemble モジュールを使用して、アンサンブル モデルの推定ツールを作成できます。

  • RandomForestClassifier クラスを使用して、ランダム フォレスト分類モデルを作成します。このモデルは、分類を目的とする複数の学習方法のディシジョン ツリーを構築するために使用します。

  • RandomForestRegressor クラスを使用して、ランダム フォレスト回帰モデルを作成します。このモデルは、回帰を目的とする複数の学習方法のディシジョン ツリーを構築するために使用します。

  • XGBClassifier クラスを使用して、勾配ブーストツリー分類モデルを作成します。このモデルは、分類を目的とする複数の学習方法のディシジョン ツリーを追加的に構築するために使用します。

  • XGBRegressor クラスを使用して、勾配ブーストツリー回帰モデルを作成します。このモデルは、回帰を目的とする複数の学習方法のディシジョン ツリーを追加的に構築するために使用します。

予測のモデル

bigframes.ml.forecasting モジュールを使用して、予測モデルの推定ツールを作成できます。

インポートされたモデル

bigframes.ml.imported モジュールを使用して、インポートしたモデルの推定ツールを作成できます。

線形モデル

bigframes.ml.linear_model モジュールを使用して、線形モデルの推定ツールを作成します。

  • LinearRegression クラスを使用して、線形回帰モデルを作成します。このモデルは予測に使用します。たとえば、特定の日の商品の売上を予測します。

  • LogisticRegression クラスを使用して、ロジスティック回帰モデルを作成します。このモデルは、入力が low-value、medium-value、high-value のいずれであるかなど、2 つ以上の有効な値を分類するために使用します。

次のコードサンプルは、次の処理を行うために bigframes.ml を使用する場合を示しています。

  • BigQuery からデータを読み込む
  • トレーニング データをクリーニングして準備する
  • bigframes.ml.LinearRegression 回帰モデルを作成して適用する
from bigframes.ml.linear_model import LinearRegression
import bigframes.pandas as bpd

# Load data from BigQuery
query_or_table = "bigquery-public-data.ml_datasets.penguins"
bq_df = bpd.read_gbq(query_or_table)

# Filter down to the data to the Adelie Penguin species
adelie_data = bq_df[bq_df.species == "Adelie Penguin (Pygoscelis adeliae)"]

# Drop the species column
adelie_data = adelie_data.drop(columns=["species"])

# Drop rows with nulls to get training data
training_data = adelie_data.dropna()

# Specify your feature (or input) columns and the label (or output) column:
feature_columns = training_data[
    ["island", "culmen_length_mm", "culmen_depth_mm", "flipper_length_mm", "sex"]
]
label_columns = training_data[["body_mass_g"]]

test_data = adelie_data[adelie_data.body_mass_g.isnull()]

# Create the linear model
model = LinearRegression()
model.fit(feature_columns, label_columns)

# Score the model
score = model.score(feature_columns, label_columns)

# Predict using the model
result = model.predict(test_data)

大規模言語モデル

bigframes.ml.llm モジュールを使用して、LLM の推定ツールを作成できます。

GeminiTextGenerator クラスを使用して、Gemini テキスト生成モデルを作成します。このモデルは、テキスト生成タスクに使用します。

bigframes.ml.llm モジュールを使用して、リモート大規模言語モデル（LLM）用の推定ツールを作成します。
次のコードサンプルでは、bigframes.ml.llm GeminiTextGenerator クラスを使用して、コード生成用の Gemini モデルを作成します。

from bigframes.ml.llm import GeminiTextGenerator
import bigframes.pandas as bpd

# Create the Gemini LLM model
session = bpd.get_global_session()
connection = f"{PROJECT_ID}.{REGION}.{CONN_NAME}"
model = GeminiTextGenerator(
    session=session, connection_name=connection, model_name="gemini-2.0-flash-001"
)

df_api = bpd.read_csv("gs://cloud-samples-data/vertex-ai/bigframe/df.csv")

# Prepare the prompts and send them to the LLM model for prediction
df_prompt_prefix = "Generate Pandas sample code for DataFrame."
df_prompt = df_prompt_prefix + df_api["API"]

# Predict using the model
df_pred = model.predict(df_prompt.to_frame(), max_output_tokens=1024)

リモートモデル

BigQuery DataFrames ML リモートモデル（bigframes.ml.remote または bigframes.ml.llm）を使用するには、次の API を有効にする必要があります。

BigQuery DataFrames でリモートモデルを作成すると、BigQuery 接続が作成されます。デフォルトでは、bigframes-default-connection という名前の接続が使用されます。必要に応じて、事前構成済みの BigQuery 接続も使用できます。この場合、接続の作成はスキップされます。デフォルト接続のサービス アカウントには、プロジェクトに対する Vertex AI ユーザーロール（roles/aiplatform.user）が付与されます。

パイプラインの作成

bigframes.ml.pipeline モジュールを使用して、ML パイプラインを作成できます。パイプラインを使用すると、さまざまなパラメータを設定しながら、複数の ML ステップを組み合わせてクロス検証できます。これにより、コードが簡素化され、データの前処理ステップと推定ツールを一緒にデプロイできます。

Pipeline クラスを使用して、最終的な推定ツールを含む変換のパイプラインを作成します。

モデルを選択する

bigframes.ml.model_selection モジュールを使用して、トレーニング データセットとテスト データセットを分割し、最適なモデルを選択します。

  • 次のコードサンプルに示すように、train_test_split 関数を使用して、データをトレーニング セットとテスト（評価）セットに分割します。

    X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2)

  • 次のコードサンプルに示すように、KFold クラスと KFold.split メソッドを使用して、モデルをトレーニングして評価するための多重交差検定のトレーニング セットとテストセットを作成します。この機能は、小規模なデータセットに役立ちます。

    kf = KFold(n_splits=5)
for i, (X_train, X_test, y_train, y_test) in enumerate(kf.split(X, y)):
# Train and evaluate models with training and testing sets

  • 次のコードサンプルに示すように、cross_validate 関数を使用して、多重交差検定のトレーニング セットとテストセットを自動的に作成し、モデルをトレーニングして評価し、各フォールドの結果を取得します。

    scores = cross_validate(model, X, y, cv=5)

パフォーマンスの最適化

このセクションでは、BigQuery DataFrames のパフォーマンスを最適化する方法について説明します。

部分順序モード

BigQuery DataFrames には順序モード機能が用意されています。より効率的なクエリを生成するには、ordering_mode プロパティを partial に設定します。

partial 順序モードと対照的に、デフォルトの strict モードでは、すべての行に全順序を作成します。全順序では、DataFrame.iloc プロパティを使用して行に順序ベースでアクセスできるため、BigQuery DataFrames と pandas の互換性が向上します。ただし、全順序とその順序のデフォルトのシーケンシャル インデックスの場合、列フィルタも行フィルタも、read_gbq 関数と read_gbq_table 関数にパラメータとして適用されない限り、スキャンされるバイト数は削減されません。DataFrame 内のすべての行に全順序を設定するため、BigQuery DataFrames はすべての行のハッシュを作成します。これにより、行フィルタと列フィルタが無視され、データ全体がスキャンされる可能性があります。

ordering_mode プロパティを partial に設定すると、BigQuery DataFrame がすべての行の全順序を生成しなくなります。部分順序モードでは、DataFrame.iloc プロパティなど、すべての行の全順序を必要とする機能も無効になります。部分順序モードでは、順序付けでシーケンシャル インデックスではなく、DefaultIndexKind クラスが null インデックスに設定されます。

ordering_mode プロパティが partial に設定された DataFrame をフィルタリングする場合、BigQuery DataFrames はシーケンシャル インデックスに欠落している行を計算する必要がないため、より高速で効率的なクエリを生成できます。BigQuery DataFrames API は、厳密な順序モードのデフォルト エクスペリエンスと同様に、使い慣れた pandas API です。ただし、部分順序モードは一般的な pandas の動作とは異なります。たとえば、部分順序モードではインデックスによる暗黙的な結合は実行されません。

部分順序モードと厳密な順序モードの両方で、使用した BigQuery リソースに対して料金が発生します。ただし、部分順序モードを使用すると、クラスタ列とパーティション列の行フィルタによって処理されるバイト数が減るため、大規模なクラスタ化テーブルやパーティション分割テーブルを操作する際の費用を削減できます。

用途

部分順序を使用するには、次のコードサンプルに示すように、BigQuery DataFrames で他のオペレーションを実行する前に ordering_mode プロパティを partial に設定します。

import bigframes.pandas as bpd

bpd.options.bigquery.ordering_mode = "partial"

部分順序モードにはシーケンシャル インデックスがないため、関連のない BigQuery DataFrame は暗黙的に結合されません。代わりに、DataFrame.merge メソッドを明示的に呼び出して、異なるテーブル式から派生した 2 つの BigQuery DataFrame を結合する必要があります。

Series.unique() 機能と Series.drop_duplicates() 機能は、部分順序モードに対応していません。代わりに、groupby メソッドを使用して、次のように一意の値を検索します。

# Avoid order dependency by using groupby instead of drop_duplicates.
unique_col = df.groupby(["column"], as_index=False).size().drop(columns="size")

部分順序モードでは、DataFrame.head(n) 関数と Series.head(n) 関数の出力はすべての呼び出しでべき等ではありません。小さな任意のデータサンプルをダウンロードするには、DataFrame.peek() メソッドまたは Series.peek() メソッドを使用します。

ordering_mode = "partial" プロパティを使用する詳細なチュートリアルについては、部分順序モードの使用方法を示す BigQuery DataFrames ノートブックをご覧ください。

トラブルシューティング

部分順序モードの DataFrame には順序やインデックスが常に存在するとは限らないため、pandas 互換のメソッドを使用すると、次の問題が発生することがあります。

順序必須エラー

一部の機能（DataFrame.head() 関数や DataFrame.iloc 関数など）では、順序が必須です。順序が必要な機能の一覧については、サポートされている pandas API で「順序が必要」列をご覧ください。

オブジェクトに順序がない場合、オペレーションは失敗し、次のような OrderRequiredError メッセージが表示されます。

OrderRequiredError: Op iloc requires an ordering. Use .sort_values or .sort_index to provide an ordering.

エラー メッセージに記載されているように、DataFrame.sort_values() メソッドを使用して順序を指定し、列または列で並べ替えることができます。DataFrame.groupby() オペレーションなどの他のオペレーションは、グループキー全体の全順序を暗黙的に提供します。

すべての行に対する完全な安定した全順序であることが決定できない場合、後続のオペレーションで次のような AmbiguousWindowWarning メッセージが表示されることがあります。

AmbiguousWindowWarning: Window ordering may be ambiguous, this can cause unstable results.

ワークロードが非決定的結果に対応している場合、または指定した順序が全順序であることを手動で確認できる場合は、次の方法で AmbiguousWindowWarning メッセージをフィルタできます。

import warnings

import bigframes.exceptions

warnings.simplefilter(
    "ignore", category=bigframes.exceptions.AmbiguousWindowWarning
)
null インデックス エラー

DataFrame.unstack() プロパティや Series.interpolate() プロパティなど、インデックスが必要な機能もあります。インデックスが必要な機能の一覧については、サポートされている pandas API で「インデックスが必要」列をご覧ください。

部分順序モードでインデックスを必要とするオペレーションを使用すると、オペレーションは次のような NullIndexError メッセージを生成します。

NullIndexError: DataFrame cannot perform interpolate as it has no index. Set an index using set_index.

エラー メッセージに記載されているように、DataFrame.set_index() メソッドを使用してインデックスを指定し、列または列で並べ替えることができます。DataFrame.groupby() オペレーションなどの他のオペレーションでは、as_index=False パラメータが設定されていない限り、インデックスはグループキーに基づいて暗黙的に指定されます。

次のステップ