为 BigQuery DataFrames 自定义 Python 函数

借助 BigQuery DataFrames，您可以将自定义 Python 函数转换为可以在 BigQuery DataFrames 对象上大规模运行的 BigQuery 制品。这种可扩展性支持使您可以执行超出 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 远程函数。

要求

如需使用 BigQuery DataFrames 远程函数，您必须启用以下 API：

使用 BigQuery DataFrames 远程函数时，如果您使用的是默认 BigQuery 连接，则需要Project IAM Admin 角色 (roles/resourcemanager.projectIamAdmin)；如果您使用的是预配置连接，则需要Browser 角色 (roles/browser)。您可以通过将 bigframes.pandas.options.bigquery.skip_bq_connection_check 选项设置为 True 来避免此要求，在这种情况下，连接（默认连接或预配置连接）会按原样使用，而不会进行任何存在或权限检查。如果您使用的是预配置连接并跳过连接检查，请验证以下各项：

  • 连接是在正确的位置创建的。
  • 如果您使用的是 BigQuery DataFrames 远程函数，则服务账号在项目中具有 Cloud Run Invoker 角色 (roles/run.invoker)。

查看和管理连接

系统会使用您在自定义函数定义中提供的名称，在 BigQuery DataFrames 会话所在的相同位置创建 BigQuery 连接。如需查看和管理连接，请执行以下操作：

  1. 在 Google Cloud 控制台中，前往 BigQuery 页面。

    转到 BigQuery

  2. 选择您在其中创建了远程函数的项目。

  3. 在左侧窗格中，点击 探索器：

    突出显示的“探索器”窗格按钮。

  4. 在探索器窗格中，展开该项目，然后点击连接。

BigQuery 远程函数在您指定的数据集中创建，或在匿名数据集（一种隐藏数据集类型）中创建。如果您在创建远程函数期间没有为其设置名称，BigQuery DataFrames 会应用以 bigframes 前缀开头的默认名称。如需查看和管理在用户指定的数据集中创建的远程函数，请执行以下操作：

  1. 在 Google Cloud 控制台中，前往 BigQuery 页面。

    转到 BigQuery

  2. 选择您在其中创建了远程函数的项目。

  3. 在左侧窗格中，点击 探索器：

    突出显示的“探索器”窗格按钮。

  4. 在探索器窗格中，展开项目，然后点击数据集。

  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 函数。如需了解详情，请参阅配额。

后续步骤