Migra a la versión 2.0 de BigQuery DataFrames

La versión 2.0 de BigQuery DataFrames incluye mejoras de seguridad y rendimiento en la API de BigQuery DataFrames, agrega funciones nuevas y presenta cambios rotundos. En este documento, se describen los cambios y se proporcionan instrucciones para la migración. Puedes aplicar estas recomendaciones antes de instalar la versión 2.0 con la versión 1.x más reciente de BigQuery DataFrames.

La versión 2.0 de BigQuery DataFrames ofrece los siguientes beneficios:

  • Cuando ejecutas consultas que devuelven resultados al cliente, se crean consultas más rápidas y menos tablas, ya que allow_large_results se establece de forma predeterminada en False. Este diseño puede reducir los costos de almacenamiento, en especial si usas la facturación de bytes físicos.
  • Seguridad mejorada de forma predeterminada en las funciones remotas implementadas por BigQuery DataFrames.

Instala la versión 2.0 de BigQuery DataFrames

Para evitar cambios breaking, fija una versión específica de BigQuery DataFrames en tu archivo requirements.txt (por ejemplo, bigframes==1.42.0) o en tu archivo pyproject.toml (por ejemplo, dependencies = ["bigframes = 1.42.0"]). Cuando esté todo listo para probar la versión más reciente, puedes ejecutar pip install --upgrade bigframes para instalar la versión más reciente de BigQuery DataFrames.

Usa la opción allow_large_results

BigQuery tiene un límite de tamaño máximo de respuesta para los trabajos de consulta. A partir de la versión 2.0 de BigQuery DataFrames, BigQuery DataFrames aplica este límite de forma predeterminada en los métodos que devuelven resultados al cliente, como peek(), to_pandas() y to_pandas_batches(). Si tu trabajo devuelve resultados grandes, puedes establecer allow_large_results en True en tu objeto BigQueryOptions para evitar cambios que generen errores. Esta opción se establece en False de forma predeterminada en la versión 2.0 de BigQuery DataFrames.

import bigframes.pandas as bpd

bpd.options.bigquery.allow_large_results = True

Puedes anular la opción allow_large_results con el parámetro allow_large_results en to_pandas() y otros métodos. Por ejemplo:

bf_df = bpd.read_gbq(query)
# ... other operations on bf_df ...
pandas_df = bf_df.to_pandas(allow_large_results=True)

Usa el decorador @remote_function

La versión 2.0 de BigQuery DataFrames realiza algunos cambios en el comportamiento predeterminado del decorador @remote_function.

Los argumentos de palabras clave se aplican a los parámetros ambiguos

Para evitar pasar valores a un parámetro no deseado, BigQuery DataFrames versión 2.0 y versiones posteriores exigen el uso de argumentos de palabras clave para los siguientes parámetros:

  • 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

Cuando uses estos parámetros, proporciona el nombre del parámetro. Por ejemplo:

@remote_function(
  name="my_remote_function",
  ...
)
def my_remote_function(parameter: int) -> str:
  return str(parameter)

Configura una cuenta de servicio

A partir de la versión 2.0, BigQuery DataFrames ya no usa la cuenta de servicio de Compute Engine de forma predeterminada para las funciones de Cloud Run que implementa. Para limitar los permisos de la función que implementas, haz lo siguiente:

  1. Crea una cuenta de servicio con permisos mínimos.
  2. Proporciona el correo electrónico de la cuenta de servicio al parámetro cloud_function_service_account del decorador @remote_function.

Por ejemplo:

@remote_function(
  cloud_function_service_account="my-service-account@my-project.iam.gserviceaccount.com",
  ...
)
def my_remote_function(parameter: int) -> str:
  return str(parameter)

Si deseas usar la cuenta de servicio de Compute Engine, puedes establecer el parámetro cloud_function_service_account del decorador @remote_function en "default". Por ejemplo:

# 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)

Establece la configuración de entrada

A partir de la versión 2.0, BigQuery DataFrames establece la configuración de entrada de las funciones de Cloud Run que implementa en "internal-only". Anteriormente, la configuración de entrada se establecía en "all" de forma predeterminada. Puedes cambiar la configuración de entrada estableciendo el parámetro cloud_function_ingress_settings del decorador @remote_function. Por ejemplo:

@remote_function(cloud_function_ingress_settings="internal-and-gclb", ...)
def my_remote_function(parameter: int) -> str:
  return str(parameter)

Usa extremos personalizados

En las versiones de BigQuery DataFrames anteriores a la 2.0, si una región no admitía endpoints de servicio regionales ni bigframes.pandas.options.bigquery.use_regional_endpoints = True, BigQuery DataFrames recurría a los endpoints de ubicación. La versión 2.0 de BigQuery DataFrames quita este comportamiento de resguardo. Para conectarte a extremos de ubicación en la versión 2.0, configura la opción bigframes.pandas.options.bigquery.client_endpoints_override. Por ejemplo:

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",
}

Reemplaza LOCATION por el nombre de la ubicación de BigQuery a la que deseas conectarte.

Usa el módulo bigframes.ml.llm

En la versión 2.0 de BigQuery DataFrames, el valor predeterminado de model_name para GeminiTextGenerator se actualizó a "gemini-2.0-flash-001". Te recomendamos que proporciones un model_name directamente para evitar interrupciones si el modelo predeterminado cambia en el futuro.

import bigframes.ml.llm

model = bigframes.ml.llm.GeminiTextGenerator(model_name="gemini-2.0-flash-001")

¿Qué sigue?