Migrar para o BigQuery DataFrames 2.0

Em 16 de abril de 2025, a equipe do BigQuery DataFrames planeja lançar a versão 2.0 do BigQuery DataFrames. Esta versão melhora a segurança e o desempenho da API BigQuery DataFrames e adiciona novos recursos. Este documento descreve as mudanças e fornece orientações sobre a migração. É possível aplicar essas recomendações antes do lançamento usando a versão 1.x mais recente dos DataFrames do BigQuery ou instalando versões de pré-lançamento do pacote 2.0.

Instalar a versão 2.0 do BigQuery DataFrames

Para evitar mudanças, fixe uma versão específica do BigQuery DataFrames no arquivo requirements.txt (por exemplo, bigframes==1.38.0) ou pyproject.toml (por exemplo, dependencies = ["bigframes = 1.38.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 do BigQuery DataFrames, os DataFrames do BigQuery aplicam esse limite por padrão em métodos que retornam resultados para o 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. 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 no to_pandas() e em 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 DataFrames do BigQuery faz algumas mudanças no comportamento padrão do decorador @remote_function.

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,

  1. Crie uma conta de serviço com permissões mínimas.
  2. Em seguida, 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 decorador @remote_function como "default". Por 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 no "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

Antes, se uma região não oferecesse suporte a endpoints de serviço regionais e bigframes.pandas.options.bigquery.use_regional_endpoints = True, os DataFrames do BigQuery voltavam a usar endpoints de localização. A versão 2.0 do DataFrames do BigQuery remove esse comportamento alternativo. 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 modo de ordenação parcial

Com a versão 2.0 do DataFrames do BigQuery, o modo de ordenação parcial está disponível para todos, mas não é ativado por padrão. Para usar a ordenação parcial, defina ordering_mode como partial antes de realizar qualquer outra operação com os DataFrames do BigQuery, conforme mostrado no exemplo de código a seguir:

import bigframes.pandas as bpd

bpd.options.bigquery.ordering_mode = "partial"

Esse modo gera consultas mais eficientes na maioria dos casos e consultas idênticas em outros, como as que usam a função groupby(). Algumas funções compatíveis com pandas que exigem ordenação, como .iloc[row_index], não são compatíveis com o modo de ordenação parcial. Para mais informações, consulte Modo de ordenação parcial.

A seguir