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

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

allow_large_results オプションをオーバーライドするには、to_pandas() メソッドなどの 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="my-service-account@my-project.s3ns-system.iam.gserviceaccount.com",
  ...
)
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 は、"internal-only" にデプロイする Cloud Run functions の Ingress 設定を設定します。以前は、上り（内向き）の設定はデフォルトで "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)

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

BigQuery DataFrames バージョン 2.0 より前では、リージョンがリージョン サービス エンドポイントと 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 DataFrame のデータ操作機能について説明します。説明されている関数は 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 をご覧ください。

クリーンアップ

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

要件

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

制限事項

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

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. Trusted Cloud コンソールで、[BigQuery] ページに移動します。

    BigQuery に移動

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

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

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

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

    BigQuery に移動

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

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

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

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

    Cloud Run に移動します。

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

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

  4. BigQuery DataFrames によって作成された関数を特定するには、bigframes 接頭辞が付いた関数名を探します。

クリーンアップ

Trusted 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 関数は、bigframes.pandas.get_global_session().bqclient.delete_routine(routine_id) コマンドを使用してクリーンアップすることもできます。

要件

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

制限事項

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

ML と AI

以降のセクションでは、BigQuery DataFrame の 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）が付与されます。

パイプラインの作成

ML パイプラインは、bigframes.ml.pipeline モジュールを使用して作成できます。パイプラインを使用すると、さまざまなパラメータを設定しながら、複数の 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 DataFrame のパフォーマンスを最適化する方法について説明します。

部分順序モード

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 パラメータが設定されていない限り、インデックスはグループキーに基づいて暗黙的に指定されます。

可視化

bigframes.pandas API は、ツールの Python エコシステム全体へのゲートウェイになります。この API は高度な統計オペレーションをサポートし、BigQuery DataFrames から生成された集計を可視化できます。また、組み込みのサンプリング オペレーションを使用して、BigQuery DataFrames の DataFrame から pandas DataFrame に切り替えることもできます。

次のステップ