BigQuery DataFrames 用に Python 関数をカスタマイズする

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

この拡張メカニズムには、ユーザー定義関数とリモート関数の 2 つのバリエーションがあります。

必要なロール

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

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

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

ユーザー定義関数（UDF）

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

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

要件

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

クリーンアップ

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

制限事項

  • 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 functions の関数。

  • BigQuery 接続。

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

  • BigQuery 接続で作成された Cloud Run functions の関数を使用する BigQuery リモート関数。

要件

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

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

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

接続を表示して管理する

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

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

    [BigQuery] に移動

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

  3. 左側のペインで、 [エクスプローラ] をクリックします。

    ハイライト表示されたエクスプローラ ペインのボタン。

  4. [エクスプローラ] ペインで、プロジェクトを開き、[接続] をクリックします。

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

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

    [BigQuery] に移動

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

  3. 左側のペインで、 [エクスプローラ] をクリックします。

    エクスプローラ ペインのボタンがハイライト表示されている。

  4. [エクスプローラ] ペインでプロジェクトを開き、[データセット] をクリックします。

  5. リモート関数を作成したデータセットをクリックします。

  6. [ルーティン] タブをクリックします。

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

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

    Cloud Run に移動します。

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

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

  4. BigQuery DataFrames で作成された関数を識別するには、bigframes で始まる関数名を探します。

クリーンアップ

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

  • 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) コマンドを使用してクリーンアップすることもできます。

制限事項

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

次のステップ