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="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 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")

次のステップ