Migrar para a versão 2.0 do BigQuery DataFrames

A versão 2.0 do BigQuery DataFrames faz melhorias de segurança e desempenho na API BigQuery DataFrames, adiciona novos recursos e introduz mudanças incompatíveis. Este documento descreve as mudanças e fornece orientações para a migração. Você pode aplicar essas recomendações antes de instalar a versão 2.0 usando a versão 1.x mais recente do BigQuery DataFrames.

A versão 2.0 do BigQuery DataFrames oferece os seguintes benefícios:

  • Consultas mais rápidas e menos tabelas são criadas quando você executa consultas que retornam resultados ao cliente, porque allow_large_results usa False como padrão. Esse design pode reduzir os custos de armazenamento, principalmente se você usar o faturamento por bytes físicos.
  • Segurança aprimorada por padrão nas funções remotas implantadas pelo BigQuery DataFrames.

Instalar a versão 2.0 do BigQuery DataFrames

Para evitar mudanças incompatíveis, fixe uma versão específica do BigQuery DataFrames no arquivo requirements.txt (por exemplo, bigframes==1.42.0) ou pyproject.toml (por exemplo, dependencies = ["bigframes = 1.42.0"]). Quando estiver tudo pronto para testar a versão mais recente, execute pip install --upgrade bigframes para instalar a versão mais recente do BigQuery DataFrames.

Usar a opção allow_large_results

O BigQuery tem um limite máximo de tamanho de resposta para jobs de consulta. A partir da versão 2.0, o BigQuery DataFrames impõe esse limite por padrão em métodos que retornam resultados ao cliente, como peek(), to_pandas() e to_pandas_batches(). Se o job retornar resultados grandes, defina allow_large_results como True no objeto BigQueryOptions para evitar mudanças incompatíveis. Essa opção é definida como False por padrão no BigQuery DataFrames versão 2.0.

import bigframes.pandas as bpd

bpd.options.bigquery.allow_large_results = True

É possível substituir a opção allow_large_results usando o parâmetro allow_large_results em to_pandas() e outros métodos. Exemplo:

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

Usar o decorador @remote_function

A versão 2.0 do BigQuery DataFrames faz algumas mudanças no comportamento padrão do decorador @remote_function.

Argumentos de palavra-chave são obrigatórios para parâmetros ambíguos

Para evitar a transmissão de valores a um parâmetro não intencional, o BigQuery DataFrames versão 2.0 e mais recentes exigem o uso de argumentos de palavra-chave para os seguintes 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

Ao usar esses parâmetros, forneça o nome deles. Exemplo:

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

Definir uma conta de serviço

A partir da versão 2.0, o BigQuery DataFrames não usa mais a conta de serviço do Compute Engine por padrão para as funções do Cloud Run que ele implanta. Para limitar as permissões da função implantada, faça o seguinte:

  1. Crie uma conta de serviço com permissões mínimas.
  2. Forneça o e-mail da conta de serviço ao parâmetro cloud_function_service_account do decorador @remote_function.

Exemplo:

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

Se você quiser usar a conta de serviço do Compute Engine, defina o parâmetro cloud_function_service_account do decorator @remote_function como "default". Exemplo:

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

Definir configurações de entrada

A partir da versão 2.0, o BigQuery DataFrames define as configurações de entrada das funções do Cloud Run que ele implanta em "internal-only". Antes, as configurações de entrada eram definidas como "all" por padrão. Para mudar as configurações de entrada, defina o parâmetro cloud_function_ingress_settings do decorador @remote_function. Exemplo:

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

Usar endpoints personalizados

Em versões do BigQuery DataFrames anteriores à 2.0, se uma região não oferecesse suporte a endpoints de serviço regionais e bigframes.pandas.options.bigquery.use_regional_endpoints = True, o BigQuery DataFrames voltaria para endpoints de localização. A versão 2.0 do BigQuery DataFrames remove esse comportamento de substituição. Para se conectar a endpoints de localização na versão 2.0, defina a opção bigframes.pandas.options.bigquery.client_endpoints_override. Exemplo:

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

Substitua LOCATION pelo nome do local do BigQuery a que você quer se conectar.

Usar o módulo bigframes.ml.llm

Na versão 2.0 dos DataFrames do BigQuery, o model_name padrão para GeminiTextGenerator foi atualizado para "gemini-2.0-flash-001". Recomendamos que você forneça um model_name diretamente para evitar falhas se o modelo padrão mudar no futuro.

import bigframes.ml.llm

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

A seguir