Instalar o BigQuery DataFrames

O BigQuery DataFrames é um pacote de código aberto que permite realizar tarefas de análise de dados e machine learning (ML) usando APIs Python conhecidas. Ao instalar esse pacote, você pode usar o mecanismo do BigQuery para escalonar seus fluxos de trabalho do pandas e do scikit-learn para processar conjuntos de dados imensos.

Instalar o BigQuery DataFrames

Para instalar a versão mais recente do BigQuery DataFrames, execute pip install --upgrade bigframes.

Bibliotecas disponíveis

O BigQuery DataFrames oferece três bibliotecas:

  • O bigframes.pandas fornece uma API pandas que pode ser usada para analisar e manipular dados no BigQuery. Muitas cargas de trabalho podem ser migradas do pandas para o bigframes apenas mudando algumas importações. A API bigframes.pandas é escalonável para permitir o processamento de terabytes de dados do BigQuery e usa o mecanismo de consulta do BigQuery para realizar cálculos.
  • O bigframes.bigquery oferece muitas funções SQL do BigQuery que podem não ter um equivalente do pandas.
  • bigframes.ml fornece uma API semelhante à API scikit-learn para ML. Com os recursos de ML do BigQuery DataFrames, é possível pré-processar dados e treinar modelos neles. Você também pode encadear essas ações para criar pipelines de dados.

Funções exigidas

Para receber as permissões necessárias para realizar as tarefas neste documento, peça ao administrador para conceder a você os seguintes papéis do IAM no seu projeto:

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Quando você está executando a autenticação de usuário final em um ambiente interativo, como um notebook, REPL do Python ou a linha de comando, o BigQuery DataFrames solicita autenticação, se necessário. Caso contrário, consulte como configurar o Application Default Credentials para vários ambientes.

Configurar opções de instalação

Depois de instalar o BigQuery DataFrames, é possível especificar as seguintes opções.

Local e projeto

É preciso especificar o local e o projeto em que você quer usar o BigQuery DataFrames.

É possível definir o local e o projeto no notebook da seguinte maneira:

import bigframes.pandas as bpd

PROJECT_ID = "bigframes-dev"  # @param {type:"string"}
REGION = "US"  # @param {type:"string"}

# Set BigQuery DataFrames options
# Note: The project option is not required in all environments.
# On BigQuery Studio, the project ID is automatically detected.
bpd.options.bigquery.project = PROJECT_ID

# Note: The location option is not required.
# It defaults to the location of the first table or query
# passed to read_gbq(). For APIs where a location can't be
# auto-detected, the location defaults to the "US" location.
bpd.options.bigquery.location = REGION

Local de tratamento de dados

O BigQuery DataFrames foi projetado para escalonar, o que é alcançado mantendo os dados e o processamento no serviço BigQuery. No entanto, é possível transferir dados para a memória da máquina cliente chamando .to_pandas() em um objeto DataFrame ou Series. Nesse caso, a limitação de memória da máquina cliente será aplicada.

Migrar para o BigQuery DataFrames versão 2.0

A versão 2.0 do BigQuery DataFrames traz melhorias de segurança e desempenho para a API BigQuery DataFrames, adiciona novos recursos e introduz alterações interruptivas. As seções a seguir descrevem as mudanças e fornecem orientações sobre a migração. É possível aplicar essas recomendações antes de instalar a versão 2.0 usando a versão 1.x mais recente do BigQuery DataFrames.

Instalar o BigQuery DataFrames versão 2.0

Para evitar alterações interruptivas, fixe uma versão específica do BigQuery DataFrames no arquivo requirements.txt (por exemplo, bigframes==1.42.0) ou no arquivo 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 do BigQuery DataFrames, esse limite é aplicado 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 alterações interruptivas. Essa opção é definida como False por padrão na versão 2.0 do BigQuery DataFrames.

import bigframes.pandas as bpd

bpd.options.bigquery.allow_large_results = True

É possível modificar essa opção usando o parâmetro allow_large_results em to_pandas() e outros métodos:

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.

Os argumentos de palavra-chave são aplicados para parâmetros ambíguos.

Para evitar a transmissão de valores para um parâmetro não intencional, a versão 2.0 e posteriores do BigQuery DataFrames impõem 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, informe o nome deles:

@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 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 que você implanta, 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)

Para usar a conta de serviço do Compute Engine, defina o parâmetro cloud_function_service_account do decorador @remote_function como "default". Use essa opção apenas se tiver um motivo específico para usar a conta de serviço do Compute Engine. Exemplo:

@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 como "internal-only". Anteriormente, as configurações de entrada eram definidas como "all" por padrão. É possível mudar as configurações de entrada definindo o parâmetro cloud_function_ingress_settings do decorador @remote_function:

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

Usar endpoints personalizados

Nas 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 usaria endpoints de local. A versão 2.0 do BigQuery DataFrames remove esse comportamento de fallback. Para se conectar a endpoints de local na versão 2.0, defina a opção 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",
}

Substitua LOCATION pelo nome do local do BigQuery ao qual você quer se conectar.

Usar o módulo bigframes.ml.llm

Para evitar falhas se o modelo padrão mudar no futuro, forneça um model_name compatível diretamente, como "gemini-3.5-flash":

import bigframes.ml.llm

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

A seguir