自訂 BigQuery DataFrames 的 Python 函式

透過 BigQuery DataFrames，您可以將自訂 Python 函式轉換為 BigQuery 構件，並大規模在 BigQuery DataFrames 物件上執行。這項擴充性支援功能可讓您執行 BigQuery DataFrames 和 SQL API 無法執行的作業，因此您可能會想善用開放原始碼程式庫。

這項擴充機制有兩種變體：使用者定義函式和遠端函式。

必要的角色

如要取得完成本文件工作所需的權限，請要求管理員在專案中授予您下列 IAM 角色：

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

使用者定義的函式 (UDF)

透過 UDF (預先發布版)，您可以將自訂 Python 函式轉換為 Python UDF。如需使用範例，請參閱「建立永久性 Python UDF」。

在 BigQuery DataFrames 中建立 UDF 時，系統會在指定資料集中建立 BigQuery 常式，做為 Python UDF。如需完整的支援參數集，請參閱 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 函式。

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 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 DataFrame 工作階段相同的位置建立。如要查看及管理連結，請按照下列步驟操作：

  1. 前往 Google Cloud 控制台的「BigQuery」頁面。

    前往「BigQuery」

  2. 選取您建立遠端函式的專案。

  3. 點選左側窗格中的 「Explorer」。

    醒目顯示「Explorer」窗格的按鈕。

  4. 在「Explorer」窗格中展開專案，然後按一下「Connections」。

BigQuery 遠端函式會在您指定的資料集中建立，或是在匿名資料集中建立，這是一種隱藏資料集。如果在建立遠端函式時未設定名稱，BigQuery DataFrames 會套用以 bigframes 前置字元開頭的預設名稱。如要查看及管理在使用者指定資料集中建立的遠端函式，請執行下列操作：

  1. 前往 Google Cloud 控制台的「BigQuery」頁面。

    前往「BigQuery」

  2. 選取您建立遠端函式的專案。

  3. 點選左側窗格中的 「Explorer」。

    醒目顯示「Explorer」窗格的按鈕。

  4. 在「Explorer」窗格中展開專案，然後按一下「Datasets」。

  5. 按一下您建立遠端函式的資料集。

  6. 按一下「日常安排」分頁標籤。

如要查看及管理 Cloud Run 函式，請按照下列步驟操作：

  1. 前往「Cloud Run」頁面。

    前往 Cloud Run。

  2. 選取您建立函式的專案。

  3. 在可用服務清單中，依「函式部署類型」篩選。

  4. 如要找出 BigQuery DataFrames 建立的函式，請尋找具有 bigframes 前置字串的函式名稱。

清除所用資源

除了直接在 Google 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) 指令。

您也可以使用 bigframes.pandas.get_global_session().bqclient.delete_routine(routine_id) 指令，清除以明確名稱引數建立的 BigQuery 遠端函式，以及相關聯的 Cloud Run 函式。

限制

  • 首次建立遠端函式時，大約需要 90 秒才能使用。額外的套件依附元件可能會增加延遲時間。
  • 在函式程式碼中或附近進行微小變更後，重新執行遠端函式定義程式碼 (例如重新命名變數、插入新行或在筆記本中插入新儲存格)，可能會導致系統重新建立遠端函式，即使這些變更對函式的行為沒有影響也一樣。
  • 使用者程式碼會向具備 Cloud Run 函式讀取權的使用者顯示，因此請務必謹慎處理敏感內容。
  • 每個專案在一個區域中，最多可同時有 1,000 個 Cloud Run 函式。詳情請參閱配額的相關說明。

後續步驟