迁移到 BigQuery DataFrames 2.0

BigQuery DataFrames 团队计划于 2025 年 4 月 16 日发布 BigQuery DataFrames 2.0 版。此版本改进了 BigQuery DataFrames API 的安全性和性能，并添加了新功能。本文档介绍了这些变更，并提供了迁移指南。您可以在发布之前应用这些建议，方法是使用最新版本的 1.x BigQuery DataFrames 或安装 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

您可以通过在 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 修饰符的默认行为进行了一些更改。

设置服务账号

从版本 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 会设置其部署到 "internal-only" 的 Cloud Run 函数的入站设置。以前，入站设置默认设置为 "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 中，部分排序模式已正式发布，但默认情况下处于停用状态。如需使用部分排序，请先将 ordering_mode 设置为 partial，然后再使用 BigQuery DataFrames 执行任何其他操作，如以下代码示例所示：

import bigframes.pandas as bpd

bpd.options.bigquery.ordering_mode = "partial"

在大多数情况下，此模式会生成更高效的查询，在其他情况下（例如使用 groupby() 函数的查询），则会生成完全相同的查询。部分排序模式不支持某些需要排序的与 Pandas 兼容的函数，例如 .iloc[row_index]。如需了解详情，请参阅部分有序模式。

后续步骤