BigQuery DataFrames 2.0 に移行する

BigQuery DataFrames チームは、2025 年 4 月 16 日に BigQuery DataFrames のバージョン 2.0 をリリースする予定です。このバージョンでは、BigQuery DataFrames API のセキュリティとパフォーマンスが改善され、新機能が追加されています。このドキュメントでは、変更点と移行ガイダンスについて説明します。これらの推奨事項は、BigQuery DataFrames の最新バージョン 1.x を使用するか、2.0 パッケージのプレリリース バージョンをインストールすることで、リリース前に適用できます。

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

破壊的な変更を回避するには、requirements.txt ファイル（bigframes==1.38.0 など）または pyproject.toml ファイル（dependencies = ["bigframes = 1.38.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 デコレーターのデフォルトの動作が変更されています。

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

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

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

次に例を示します。


  @remote_function(
    cloud_function_service_account="my-service-account@my-project.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 は、デプロイする Cloud Run 関数の上り（内向き）設定を "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)

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

以前は、リージョンがリージョン サービス エンドポイントと 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 ロケーションの名前に置き換えます。

部分順序モードを使用する

BigQuery DataFrames バージョン 2.0 では、部分順序モードが一般提供されていますが、デフォルトでは有効になっていません。部分順序を使用するには、次のコードサンプルに示すように、BigQuery DataFrames で他のオペレーションを実行する前に ordering_mode を partial に設定します。

import bigframes.pandas as bpd

bpd.options.bigquery.ordering_mode = "partial"

このモードでは、ほとんどの場合、より効率的なクエリが生成されます。また、groupby() 関数を使用するクエリなど、他のクエリでは同じクエリが生成されます。.iloc[row_index] など、順序が必要な pandas 互換関数の一部は、部分順序モードではサポートされていません。詳細については、部分順序モードをご覧ください。

次のステップ