BigQuery DataFrames を使用する

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

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

  • bigframes.pandas: 分析用の pandas 互換 API を提供します。

  • bigframes.ml: scikit-learn に似た ML 用の API を提供します。

必要な権限

オプション

インストールした後は、BigQuery DataFrames を使用するロケーションとプロジェクトを指定する必要があります。ノートブックのロケーションとプロジェクトは、次の方法で定義できます。
import bigframes.pandas as bpd

PROJECT_ID = "bigframes-dec"  # @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

bf.options.bigquery.project が設定されていない場合は、$GOOGLE_CLOUD_PROJECT 環境変数が使用されます。これは、BigQuery Studio と Vertex AI ノートブックを提供するノートブック ランタイムで設定されます。

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

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 は、次の numpy と pandas の dtype をサポートしています。

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

geopandas.array.GeometryDtype()

to_pandas() only でサポート
INT64 pandas.Int64Dtype()
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 データ型をサポートしていません。

  • ARRAY

  • NUMERIC

  • BIGNUMERIC

  • INTERVAL

  • RANGE

  • JSON

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

bigframes.pandas ライブラリを使用する

bigframes.pandas ライブラリは、BigQuery でデータの分析と操作に使用できる pandas のような API を提供します。bigframes.pandas API は、テラバイト単位の BigQuery データの処理をサポートするようにスケーラブルで、BigQuery クエリエンジンを使用して計算を実行します。
bigframes.pandas API には次の機能があります。

入力と出力

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

データの操作

開発には、SQL の代わりに Python を使用できます。BigQuery データ操作はすべて Python で開発でき、言語を切り替えて SQL ステートメントをテキスト文字列としてキャプチャする必要がなくなります。bigframes.pandas API には 750 を超える pandas 関数が用意されています。

Python エコシステムと可視化

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

カスタム Python 関数

BigQuery DataFrames を使用すると、カスタム スカラー関数を BigQuery リモート関数に変換できます。BigQuery DataFrames でリモート関数を作成すると、次のものが作成されます。

  1. Cloud Functions（第 2 世代）の関数。

  2. BigQuery 接続。デフォルトでは、bigframes-default-connection という名前の接続が使用されます。必要に応じて、事前構成済みの BigQuery 接続も使用できます。この場合、接続の作成はスキップされます。

    デフォルト接続のサービス アカウントには、Cloud Run 起動元（roles/run.invoker）の IAM ロールが付与されます。

  3. BigQuery 接続（2）を使用して Cloud Functions の関数（1）を使用する BigQuery リモート関数。

例については、リモート関数を作成するをご覧ください。

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

  1. Google Cloud コンソールで BigQuery に移動します。

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

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

BigQuery リモート関数は、指定したデータセットか、コードで匿名データセットと呼ばれる特別な種類の非表示のデータセットに作成されます。ユーザーが提供するデータセットで作成されたリモート関数を表示して管理するには、次の操作を行います。

  1. Google Cloud コンソールで BigQuery に移動します。

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

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

Cloud Functions の関数を表示して管理するには、[関数] ページで、プロジェクト ピッカーを使用して、関数を作成したプロジェクトを選択します。簡単に識別できるように、BigQuery DataFrames で作成される関数名の先頭には bigframes が付加されます。

要件

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

BigQuery DataFrames リモート関数を使用するには、プロジェクトで次の IAM ロールを付与する必要があります。

  • BigQuery データ編集者（roles/bigquery.dataEditor）

  • BigQuery Connection Admin（roles/bigquery.connectionAdmin）

  • Cloud Functions 開発者（roles/cloudfunctions.developer）

  • サービス アカウント ユーザー（roles/iam.serviceAccountUser）

  • Storage オブジェクト閲覧者（roles/storage.objectViewer）

  • デフォルトの BigQuery 接続を使用する場合はプロジェクト IAM 管理者（roles/resourcemanager.projectIamAdmin）、事前構成済みの接続を使用する場合は参照者（roles/browser）。この要件は、bigframes.pandas.options.bigquery.skip_bq_connection_check オプションを True に設定することで回避できます。この場合、接続（デフォルトまたは事前構成）は存在チェックや権限チェックなしでそのまま使用されます。事前構成された接続を使用して接続チェックを省略する場合は、接続が正しいロケーションで作成され、そのサービス アカウントにプロジェクトの Cloud Run 起動元（roles/run.invoker）ロールが付与されていることを確認してください。

制限事項

  • リモート関数を初めて作成してから、使用可能になるまでに約 90 秒かかります。

  • 新しいセルの挿入や変数の名前変更など、ノートブックでの些細な変更によって、これらの変更がリモート関数コードに関係ない場合でもリモート関数が再作成されることがあります。

  • BigQuery DataFrames では、リモート関数コードに含める個人データが区別されません。リモート関数コードは不透明ボックスとしてシリアル化され、Cloud Functions の関数としてデプロイされます。

  • BigQuery DataFrames によって作成された Cloud Functions（第 2 世代）の関数、BigQuery 接続、BigQuery リモート関数は Google Cloud に保持されます。これらのリソースを保持しない場合は、適切な Cloud Functions や BigQuery インターフェースを使用して個別に削除する必要があります。

  • プロジェクトには、一度に最大 1,000 個の Cloud Functions（第 2 世代）の関数を含めることができます。すべての上限については、Cloud Functions の割り当てをご覧ください。

bigframes.pandas の例

次の例では、bigframes.pandas の一般的な使用方法を示します。

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

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

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

データの検査と操作

bigframes.pandas を使用して、データの検査と計算のオペレーションを実行できます。
次のコードサンプルでは、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)
)

bigframes.ml ライブラリを使用する

BigQuery DataFrames の 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 テキスト生成モデルを作成します。このモデルは、テキスト生成タスクに使用します。

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

  • PaLM2TextEmbeddingGenerator クラスを使用して、PaLM2 テキスト エンベディング生成モデルを作成します。このモデルは、テキスト エンベディング生成タスクに使用します。

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)

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 を有効にする必要があります。

また、プロジェクトで次の IAM ロールが付与されている必要もあります。

  • BigQuery Connection Admin（roles/bigquery.connectionAdmin）
  • デフォルトの BigQuery 接続を使用する場合はプロジェクト IAM 管理者（roles/resourcemanager.projectIamAdmin）、事前構成済みの接続を使用する場合は参照者（roles/browser）。この要件は、bigframes.pandas.options.bigquery.skip_bq_connection_check オプションを True に設定することで回避できます。この場合、接続（デフォルトまたは事前構成）は存在の確認や権限の確認なしでそのまま使用されます。事前構成された接続を使用して接続チェックを省略する場合は、接続が正しいロケーションで作成され、そのサービス アカウントにプロジェクトの Vertex AI ユーザー（roles/aiplatform.user）ロールが付与されていることを確認してください。

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

パイプラインを作成する

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

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

次のステップ