Usar DataFrames do BigQuery

O BigQuery DataFrames fornece um DataFrame e uma API de machine learning (ML) em Python com tecnologia do mecanismo do BigQuery. O DataFrames do BigQuery é um pacote de código aberto. Execute pip install --upgrade bigframes para instalar a versão mais recente.

O DataFrames do BigQuery 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 de pandas para 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.
  • bigframes.bigquery fornece 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 DataFrames do BigQuery, é 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 concluir as tarefas neste documento, peça ao administrador para conceder a você os seguintes papéis do IAM no 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 por meio de papéis personalizados ou de outros papéis predefinidos.

Além disso, ao usar funções remotas do DataFrames do BigQuery ou modelos remotos de ML do DataFrames do BigQuery, você precisa da função de administrador do IAM do projeto (roles/resourcemanager.projectIamAdmin) se estiver usando uma conexão padrão do BigQuery ou a função de navegador (roles/browser) se estiver usando uma conexão pré-configurada. Para evitar esse requisito, defina a opção bigframes.pandas.options.bigquery.skip_bq_connection_check como True. Nesse caso, a conexão (padrão ou pré-configurada) será usada no estado em que se encontra, sem qualquer existência ou verificação de permissão. Se você estiver usando a conexão pré-configurada e pulando a verificação de conexão, verifique o seguinte:

  • A conexão é criada no local certo.
  • Se você estiver usando funções remotas do BigQuery DataFrames, a conta de serviço terá o papel de invocação do Cloud Run (roles/run.invoker) no projeto.
  • Se você estiver usando modelos remotos do BigQuery ML para DataFrames, a conta de serviço terá a função de usuário da Vertex AI (roles/aiplatform.user) no projeto.

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 DataFrames do BigQuery solicita autenticação, se necessário. Caso contrário, consulte como configurar as credenciais padrão do aplicativo para vários ambientes.

Configurar opções de instalação

Depois de instalar o BigQuery DataFrames, você pode especificar as seguintes opções.

Localização e projeto

É necessário 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 processamento dos dados

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

Local da sessão

O BigQuery DataFrames usa um objeto de sessão local para gerenciar metadados internamente. Essa sessão está vinculada a um local. O DataFrames do BigQuery usa a multirregião US como o local padrão, mas é possível usar session_options.location para definir um local diferente. Cada consulta em uma sessão é executada no local em que a sessão foi criada. O BigQuery DataFrames preenche automaticamente bf.options.bigquery.location com o local da tabela se o usuário começar com read_gbq/read_gbq_table/read_gbq_query() e especificar uma tabela, diretamente ou em uma instrução SQL.

Caso queira redefinir o local dos objetos DataFrame ou Series criados, encerre a sessão executando bigframes.pandas.close_session(). Depois disso, você poderá reutilizar bigframes.pandas.options.bigquery.location para especificar outro local.

read_gbq() requer que você especifique um local se o conjunto de dados que você está consultando não estiver na multirregião US. Se você tentar ler uma tabela de outro local, será gerada uma exceção NotFound.

Migrar para a versão 2.0 dos DataFrames do BigQuery

A versão 2.0 do BigQuery DataFrames oferece melhorias de segurança e desempenho à API BigQuery DataFrames, adiciona novos recursos e introduz mudanças importantes. Este documento descreve as mudanças e fornece 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 dos BigQuery DataFrames.

O DataFrames do BigQuery versão 2.0 tem os seguintes benefícios:

  • Consultas mais rápidas e menos tabelas são criadas quando você executa consultas que retornam resultados para o cliente, porque allow_large_results é o padrão para False. Isso pode reduzir os custos de armazenamento, especialmente se você usa o faturamento de bytes físicos.
  • Melhoria na segurança padrão nas funções remotas implantadas pelo DataFrames do BigQuery.

Instalar a versão 2.0 do BigQuery DataFrames

Para evitar mudanças, fixe uma versão específica dos DataFrames do BigQuery 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 dos DataFrames do BigQuery.

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 dos DataFrames do BigQuery, esse limite é aplicado 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 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 DataFrames do BigQuery 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 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 do parâmetro. 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,

  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 decorador @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

Nas versões anteriores à 2.0 do BigQuery DataFrames, 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 voltariam 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 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". É recomendado fornecer um model_name diretamente para evitar problemas se o modelo padrão mudar no futuro.

import bigframes.ml.llm

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

Entrada e saída

Usando a biblioteca bigframes.pandas, é possível acessar dados de várias fontes, incluindo arquivos CSV locais, arquivos do Cloud Storage, DataFrames pandas, modelos do BigQuery e funções do BigQuery. Em seguida, carregue esses dados em um DataFrame do BigQuery DataFrames. Também é possível criar tabelas do BigQuery usando DataFrames do BigQuery.

Carregar dados de uma tabela ou consulta do BigQuery

É possível criar um DataFrame com base em uma tabela ou consulta do BigQuery da seguinte maneira:

# Create a DataFrame from a BigQuery table:
import bigframes.pandas as bpd

query_or_table = "bigquery-public-data.ml_datasets.penguins"
bq_df = bpd.read_gbq(query_or_table)

Carregar dados de um arquivo CSV

É possível criar um DataFrame com base em um arquivo CSV local ou do Cloud Storage da seguinte maneira:

import bigframes.pandas as bpd

filepath_or_buffer = "gs://cloud-samples-data/bigquery/us-states/us-states.csv"
df_from_gcs = bpd.read_csv(filepath_or_buffer)
# Display the first few rows of the DataFrame:
df_from_gcs.head()

Tipos de dados

O DataFrames do BigQuery oferece suporte aos seguintes dtypes numpy e pandas:

BigQuery DataFrames do BigQuery e pandas
ARRAY pandas.ArrowDtype(pa.list_())
BOOL pandas.BooleanDtype()
DATE pandas.ArrowDtype(pa.date32())
DATETIME pandas.ArrowDtype(pa.timestamp("us"))
FLOAT64 pandas.Float64Dtype()
GEOGRAPHY

geopandas.array.GeometryDtype()

Suporte apenas para to_pandas()
INT64 pandas.Int64Dtype()
JSON pandas.ArrowDtype(pa.json_(pa.string()) na versão 3.0 ou mais recente do pandas e na versão 19.0 ou mais recente do pyarrow. Caso contrário, as colunas JSON são expostas como pandas.ArrowDtype(db_dtypes.JSONArrowType()).
STRING pandas.StringDtype(storage="pyarrow")
STRUCT pandas.ArrowDtype(pa.struct())
TIME pandas.ArrowDtype(pa.time64("us"))
TIMESTAMP pandas.ArrowDtype(pa.timestamp("us", tz="UTC"))

O DataFrames do BigQuery não oferece suporte aos seguintes tipos de dados do BigQuery:

  • NUMERIC

  • BIGNUMERIC

  • INTERVAL

  • RANGE

Todos os outros tipos de dados do BigQuery são mostrados como o tipo de objeto.

Manipulação de dados

As seções a seguir descrevem os recursos de manipulação de dados para BigQuery DataFrames. Encontre as funções descritas na biblioteca bigframes.bigquery.

API pandas

Um recurso importante do BigQuery DataFrames é que a API bigframes.pandas foi projetada para ser semelhante às APIs na biblioteca pandas. Esse design permite que você use padrões de sintaxe conhecidos para tarefas de manipulação de dados. As operações definidas pela API BigQuery DataFrames são executadas no servidor, operando diretamente nos dados armazenados no BigQuery e eliminando a necessidade de transferir conjuntos de dados para fora do BigQuery.

Para conferir quais APIs pandas são compatíveis com o BigQuery DataFrames, consulte APIs pandas compatíveis.

Inspecionar e manipular dados

É possível usar a API bigframes.pandas para realizar operações de inspeção e cálculo de dados. O exemplo de código a seguir usa a biblioteca bigframes.pandas para inspecionar a coluna body_mass_g, calcular a média body_mass e calcular a média body_mass por species:

import bigframes.pandas as bpd

# Load data from BigQuery
query_or_table = "bigquery-public-data.ml_datasets.penguins"
bq_df = bpd.read_gbq(query_or_table)

# Inspect one of the columns (or series) of the DataFrame:
bq_df["body_mass_g"]

# Compute the mean of this series:
average_body_mass = bq_df["body_mass_g"].mean()
print(f"average_body_mass: {average_body_mass}")

# Find the heaviest species using the groupby operation to calculate the
# mean body_mass_g:
(
    bq_df["body_mass_g"]
    .groupby(by=bq_df["species"])
    .mean()
    .sort_values(ascending=False)
    .head(10)
)

Biblioteca do BigQuery

A biblioteca do BigQuery fornece funções SQL do BigQuery que podem não ter um equivalente do Pandas. As seções a seguir apresentam alguns exemplos.

Processar valores de matriz

Você pode usar a função bigframes.bigquery.array_agg() na biblioteca bigframes.bigquery para agregar valores após uma operação groupby:

import bigframes.bigquery as bbq
import bigframes.pandas as bpd

s = bpd.Series([0, 1, 2, 3, 4, 5])

# Group values by whether they are divisble by 2 and aggregate them into arrays
bbq.array_agg(s.groupby(s % 2 == 0))
# False    [1 3 5]
# True     [0 2 4]
# dtype: list<item: int64>[pyarrow]

Também é possível usar as funções de matriz array_length() e array_to_string().

Criar uma série de structs

É possível usar a função bigframes.bigquery.struct() na biblioteca bigframes.bigquery para criar uma nova série de structs com subcampos para cada coluna em um DataFrame:

import bigframes.bigquery as bbq
import bigframes.pandas as bpd

# Load data from BigQuery
query_or_table = "bigquery-public-data.ml_datasets.penguins"
bq_df = bpd.read_gbq(query_or_table)

# Create a new STRUCT Series with subfields for each column in a DataFrames.
lengths = bbq.struct(
    bq_df[["culmen_length_mm", "culmen_depth_mm", "flipper_length_mm"]]
)

lengths.peek()
# 146	{'culmen_length_mm': 51.1, 'culmen_depth_mm': ...
# 278	{'culmen_length_mm': 48.2, 'culmen_depth_mm': ...
# 337	{'culmen_length_mm': 36.4, 'culmen_depth_mm': ...
# 154	{'culmen_length_mm': 46.5, 'culmen_depth_mm': ...
# 185	{'culmen_length_mm': 50.1, 'culmen_depth_mm': ...
# dtype: struct[pyarrow]

Converter carimbos de data/hora em épocas Unix

Você pode usar a função bigframes.bigquery.unix_micros() na biblioteca bigframes.bigquery para converter carimbos de data/hora em microssegundos do Unix:

import pandas as pd

import bigframes.bigquery as bbq
import bigframes.pandas as bpd

# Create a series that consists of three timestamps: [1970-01-01, 1970-01-02, 1970-01-03]
s = bpd.Series(pd.date_range("1970-01-01", periods=3, freq="d", tz="UTC"))

bbq.unix_micros(s)
# 0               0
# 1     86400000000
# 2    172800000000
# dtype: Int64

Também é possível usar as funções de tempo unix_seconds() e unix_millis().

Usar a função escalar SQL

É possível usar a função bigframes.bigquery.sql_scalar() na biblioteca bigframes.bigquery para acessar uma sintaxe SQL arbitrária que representa uma expressão de coluna única:

import bigframes.bigquery as bbq
import bigframes.pandas as bpd

# Load data from BigQuery
query_or_table = "bigquery-public-data.ml_datasets.penguins"

# The sql_scalar function can be used to inject SQL syntax that is not supported
# or difficult to express with the bigframes.pandas APIs.
bq_df = bpd.read_gbq(query_or_table)
shortest = bbq.sql_scalar(
    "LEAST({0}, {1}, {2})",
    columns=[
        bq_df["culmen_depth_mm"],
        bq_df["culmen_length_mm"],
        bq_df["flipper_length_mm"],
    ],
)

shortest.peek()
#         0
# 149	18.9
# 33	16.3
# 296	17.2
# 287	17.0
# 307	15.0
# dtype: Float64

Funções personalizadas do Python

Com o BigQuery DataFrames, você pode transformar suas funções personalizadas do Python em artefatos do BigQuery que podem ser executados em objetos do BigQuery DataFrames em escala. Esse suporte à extensibilidade permite que você realize operações além do que é possível com as APIs SQL e o BigQuery DataFrames, para que você possa aproveitar as bibliotecas de código aberto. As duas variantes desse mecanismo de extensibilidade são descritas nas seções a seguir.

Funções definidas pelo usuário (UDFs)

Com as UDFs (pré-lançamento), você pode transformar sua função Python personalizada em uma UDF do Python. Para conferir um exemplo de uso, consulte Criar uma UDF Python permanente.

A criação de uma UDF no BigQuery DataFrames cria uma rotina do BigQuery como a UDF do Python no conjunto de dados especificado. Para conferir um conjunto completo de parâmetros aceitos, consulte udf.

Limpar

Além de limpar os artefatos da nuvem diretamente no console Google Cloud ou com outras ferramentas, é possível limpar as UDFs do DataFrames do BigQuery que foram criadas com um argumento de nome explícito usando o comando bigframes.pandas.get_global_session().bqclient.delete_routine(routine_id).

Requisitos

Para usar um UDF do BigQuery DataFrames, ative a API BigQuery no seu projeto. Se você estiver fornecendo o parâmetro bigquery_connection no seu projeto, também precisará ativar a API BigQuery Connection.

Limitações

  • O código na UDF precisa ser independente, ou seja, não pode conter nenhuma referência a uma importação ou variável definida fora do corpo da função.
  • O código na UDF precisa ser compatível com o Python 3.11, porque é o ambiente em que o código é executado na nuvem.
  • A reexecução do código de definição da UDF após mudanças triviais no código da função, como renomear uma variável ou inserir uma nova linha, faz com que a UDF seja recriada, mesmo que essas mudanças não afetem o comportamento da função.
  • O código do usuário fica visível para usuários com acesso de leitura nas rotinas do BigQuery. Portanto, inclua conteúdo confidencial apenas com cuidado.
  • Um projeto pode ter até 1.000 funções do Cloud Run por vez em um local do BigQuery.

A UDF do BigQuery DataFrames implanta uma função do Python do BigQuery definida pelo usuário, e as limitações relacionadas são aplicadas.

Funções remotas

Com o BigQuery DataFrames, é possível transformar as funções escalares personalizadas em funções remotas do BigQuery. Para conferir um exemplo de uso, consulte Criar uma função remota. Para conferir um conjunto completo de parâmetros com suporte, consulte remote_function.

Ao criar uma função remota no BigQuery DataFrames, você cria o seguinte:

  • Uma função do Cloud Run.
  • Uma conexão com o BigQuery Por padrão, uma conexão com o nome bigframes-default-connection é usada. Se preferir, use uma conexão pré-configurada do BigQuery. Nesse caso, a criação da conexão é ignorada. A conta de serviço da conexão padrão recebe o papel do Cloud Run (roles/run.invoker).
  • Uma função remota do BigQuery que usa a função do Cloud Run criada com a conexão do BigQuery.

As conexões do BigQuery são criadas no mesmo local que a sessão do DataFrames do BigQuery, usando o nome que você informou na definição da função personalizada. Para visualizar e gerenciar conexões, faça o seguinte:

  1. No console Google Cloud , acesse a página BigQuery.

    Acessar o BigQuery

  2. Selecione o projeto em que você criou a função remota.

  3. No painel Explorer, expanda o projeto e, em seguida, as Conexões externas.

As funções remotas do BigQuery são criadas no conjunto de dados que você especifica ou em um conjunto de dados anônimo, que é um tipo de conjunto de dados oculto. Se você não definir um nome para uma função remota durante a criação, os DataFrames do BigQuery vão aplicar um nome padrão que começa com o prefixo bigframes. Para visualizar e gerenciar funções remotas criadas em um conjunto de dados especificado pelo usuário, faça o seguinte:

  1. No console Google Cloud , acesse a página BigQuery.

    Acessar o BigQuery

  2. Selecione o projeto em que você criou a função remota.

  3. No painel Explorer, expanda o projeto, o conjunto de dados em que você criou a função remota e Rotinas.

Para visualizar e gerenciar as funções do Cloud Run, faça o seguinte:

  1. Acessar a página Cloud Run

    Acessar o Cloud Run

  2. Selecione o projeto em que você criou a função.

  3. Filtre pelo Tipo de implantação de função na lista de serviços disponíveis.

  4. Para identificar funções criadas pelo BigQuery DataFrames, procure nomes de função com o prefixo bigframes.

Limpar

Além de limpar os artefatos da nuvem diretamente no console Google Cloud ou com outras ferramentas, você pode limpar as funções remotas do BigQuery que foram criadas sem um argumento de nome explícito e as funções associadas do Cloud Run das seguintes maneiras:

  • Para uma sessão do BigQuery DataFrames, use o comando session.close().
  • Para a sessão padrão do BigQuery DataFrames, use o comando bigframes.pandas.close_session().
  • Para uma sessão anterior com session_id, use o comando bigframes.pandas.clean_up_by_session_id(session_id).

Também é possível limpar as funções remotas do BigQuery que foram criadas com um argumento de nome explícito e as funções do Cloud Run associadas usando o comando bigframes.pandas.get_global_session().bqclient.delete_routine(routine_id).

Requisitos

Para usar as funções remotas do DataFrames do BigQuery, ative as seguintes APIs:

Limitações

  • As funções remotas levam cerca de 90 segundos para ficarem utilizáveis quando você as cria. Outras dependências de pacotes podem aumentar a latência.
  • A reexecução do código de definição da função remota após mudanças triviais no código da função e em torno dele, como renomear uma variável, inserir uma nova linha ou inserir uma nova célula no notebook, pode fazer com que a função remota seja recriada, mesmo que essas mudanças não sejam importantes para o comportamento da função.
  • O código do usuário fica visível para usuários com acesso de leitura às funções do Cloud Run. Portanto, inclua conteúdo sensível apenas com cuidado.
  • Um projeto pode ter até 1.000 funções do Cloud Run por vez em uma região. Para mais informações, consulte Cotas.

ML e IA

As seções a seguir descrevem os recursos de ML e IA para DataFrames do BigQuery. Esses recursos usam a biblioteca bigframes.ml.

Locais ML

A biblioteca bigframes.ml oferece suporte aos mesmos locais que o BigQuery ML. A previsão do modelo do BigQuery ML e outras funções de ML são aceitas em todas as regiões do BigQuery. O suporte para treinamento de modelo varia de acordo com a região. Para mais informações, consulte Locais do BigQuery ML.

Pré-processar dados

Crie transformadores para preparar dados para uso em estimadores (modelos) usando o módulo bigframes.ml.preprocessing e o módulo bigframes.ml.compose. O DataFrames do BigQuery oferece as seguintes transformações:

  • Use a classe KBinsDiscretizer no módulo bigframes.ml.preprocessing para agrupar dados contínuos em intervalos.

  • Use a classe LabelEncoder no módulo bigframes.ml.preprocessing para normalizar os rótulos de destino como valores inteiros.

  • Use a classe MaxAbsScaler no módulo bigframes.ml.preprocessing para dimensionar cada recurso para o intervalo [-1, 1] de acordo com o valor absoluto máximo.

  • Use a classe MinMaxScaler no módulo bigframes.ml.preprocessing para padronizar recursos dimensionando cada recurso para o intervalo [0, 1].

  • Use a classe StandardScaler no módulo bigframes.ml.preprocessing para padronizar recursos removendo a média e o dimensionamento para a variância da unidade.

  • Use a classe OneHotEncoder no módulo bigframes.ml.preprocessing para transformar valores categóricos em formato numérico.

  • Use a classe ColumnTransformer no módulo bigframes.ml.compose para aplicar transformadores a colunas do DataFrames.

Treinar modelos

É possível criar estimadores para treinar modelos nos DataFrames do BigQuery.

Modelos de clustering

É possível criar estimadores para modelos de clustering usando o módulo bigframes.ml.cluster.

  • Use a classe KMeans (link em inglês) para criar modelos de clustering K-means. Use esses modelos para segmentação de dados. Por exemplo, identificar segmentos de clientes. K-means é uma técnica de aprendizado não supervisionado, portanto, treinamento de modelo não requer rótulos ou dados divididos para treinamento ou avaliação.

Use o módulo bigframes.ml.cluster para criar estimadores para modelos de agrupamento.

O exemplo de código a seguir mostra o uso da classe bigframes.ml.cluster KMeans para criar um modelo de clusterização K-means para segmentação de dados:

from bigframes.ml.cluster import KMeans
import bigframes.pandas as bpd

# Load data from BigQuery
query_or_table = "bigquery-public-data.ml_datasets.penguins"
bq_df = bpd.read_gbq(query_or_table)

# Create the KMeans model
cluster_model = KMeans(n_clusters=10)
cluster_model.fit(bq_df["culmen_length_mm"], bq_df["sex"])

# Predict using the model
result = cluster_model.predict(bq_df)
# Score the model
score = cluster_model.score(bq_df)

Modelos de decomposição

É possível criar estimadores para modelos de decomposição usando o módulo bigframes.ml.decomposition.

  • Use a classe PCA para criar modelos de análise de componentes principais (PCA, na sigla em inglês). Use esses modelos para calcular os componentes principais e usá-los para realizar uma mudança de base nos dados. Isso reduz a dimensionalidade, projetando cada ponto de dados apenas nos primeiros componentes principais. Assim, você consegue dados de dimensões menores, preservando o máximo possível da variação deles.

Modelos do conjunto

É possível criar estimadores para modelos de conjunto usando o módulo bigframes.ml.ensemble.

  • Use a classe RandomForestClassifier para criar modelos de classificador de floresta aleatória. Use esses modelos para construir várias árvores de decisão de método de aprendizado para classificação.

  • Use a classe RandomForestRegressor para criar modelos de regressão de floresta aleatória. Use esses modelos para construir várias árvores de decisão de método de aprendizado para regressão.

  • Use a classe XGBClassifier para criar modelos de classificador de árvore otimizados com gradiente. Use esses modelos para construir aditivamente várias árvores de decisão de método de aprendizado para classificação.

  • Use a classe XGBRegressor para criar modelos de regressão de árvore otimizada com gradiente. Use esses modelos para construir aditivamente várias árvores de decisão de método de aprendizado para regressão.

Modelos de previsão

É possível criar estimadores para modelos de previsão usando o módulo bigframes.ml.forecasting.

Modelos importados

É possível criar estimadores para modelos importados usando o módulo bigframes.ml.imported.

Modelos lineares

Crie estimadores para modelos lineares usando o módulo bigframes.ml.linear_model.

  • Use a classe LinearRegression para criar modelos de regressão linear. Use esses modelos para previsão. Por exemplo, a previsão das vendas de um item em um determinado dia.

  • Use a classe LogisticRegression para criar modelos de regressão logística. Use esses modelos para a classificação de dois ou mais valores possíveis, por exemplo, se uma entrada é low-value, medium-value ou high-value.

O exemplo de código abaixo mostra o uso de bigframes.ml para fazer o seguinte:

from bigframes.ml.linear_model import LinearRegression
import bigframes.pandas as bpd

# Load data from BigQuery
query_or_table = "bigquery-public-data.ml_datasets.penguins"
bq_df = bpd.read_gbq(query_or_table)

# Filter down to the data to the Adelie Penguin species
adelie_data = bq_df[bq_df.species == "Adelie Penguin (Pygoscelis adeliae)"]

# Drop the species column
adelie_data = adelie_data.drop(columns=["species"])

# Drop rows with nulls to get training data
training_data = adelie_data.dropna()

# Specify your feature (or input) columns and the label (or output) column:
feature_columns = training_data[
    ["island", "culmen_length_mm", "culmen_depth_mm", "flipper_length_mm", "sex"]
]
label_columns = training_data[["body_mass_g"]]

test_data = adelie_data[adelie_data.body_mass_g.isnull()]

# Create the linear model
model = LinearRegression()
model.fit(feature_columns, label_columns)

# Score the model
score = model.score(feature_columns, label_columns)

# Predict using the model
result = model.predict(test_data)

Modelos de linguagem grande

É possível criar estimadores para LLMs usando o módulo bigframes.ml.llm.

Use a classe GeminiTextGenerator para criar modelos geradores de texto do Gemini. Use esses modelos para tarefas de geração de texto.

Use o módulo bigframes.ml.llm para criar estimadores para modelos de linguagem grandes (LLMs) remotos.
O exemplo de código abaixo mostra como usar a classe bigframes.ml.llm GeminiTextGenerator para criar um modelo do Gemini para geração de código:

from bigframes.ml.llm import GeminiTextGenerator
import bigframes.pandas as bpd

# Create the Gemini LLM model
session = bpd.get_global_session()
connection = f"{PROJECT_ID}.{REGION}.{CONN_NAME}"
model = GeminiTextGenerator(
    session=session, connection_name=connection, model_name="gemini-2.0-flash-001"
)

df_api = bpd.read_csv("gs://cloud-samples-data/vertex-ai/bigframe/df.csv")

# Prepare the prompts and send them to the LLM model for prediction
df_prompt_prefix = "Generate Pandas sample code for DataFrame."
df_prompt = df_prompt_prefix + df_api["API"]

# Predict using the model
df_pred = model.predict(df_prompt.to_frame(), max_output_tokens=1024)

Modelos remotos

Para usar modelos remotos de ML do DataFrames do BigQuery (bigframes.ml.remote ou bigframes.ml.llm), ative as seguintes APIs:

A criação de um modelo remoto no DataFrames do BigQuery cria uma conexão com o BigQuery. Por padrão, uma conexão com o nome bigframes-default-connection é usada. Se preferir, use uma conexão pré-configurada do BigQuery. Nesse caso, a criação da conexão é ignorada. A conta de serviço da conexão padrão recebe o papel de usuário da Vertex AI (roles/aiplatform.user) no projeto.

Criar pipelines

É possível criar pipelines de ML usando o módulo bigframes.ml.pipeline. Os pipelines permitem montar várias etapas de ML para validação cruzada ao definir parâmetros diferentes. Isso simplifica o código e permite implantar etapas de pré-processamento de dados e um estimador juntos.

Use a classe Pipeline para criar um pipeline de transformações com um estimador final.

Selecionar modelos

Use o módulo bigframes.ml.model_selection para dividir os conjuntos de dados de treinamento e teste e selecionar os melhores modelos:

  • Use a função train_test_split para dividir os dados em conjuntos de treinamento e teste (avaliação), conforme mostrado no exemplo de código abaixo:

    X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2)

  • Use a classe KFold e o método KFold.split para criar conjuntos de treinamento e teste com várias camadas para treinar e avaliar modelos, conforme mostrado no exemplo de código abaixo. Esse recurso é valioso para pequenos conjuntos de dados.

    kf = KFold(n_splits=5)
for i, (X_train, X_test, y_train, y_test) in enumerate(kf.split(X, y)):
# Train and evaluate models with training and testing sets

  • Use a função cross_validate para criar automaticamente conjuntos de treinamento e testes com várias divisões, treinar e avaliar o modelo e receber o resultado de cada divisão, conforme mostrado no exemplo de código abaixo:

    scores = cross_validate(model, X, y, cv=5)

Otimização de desempenho

Esta seção apresenta maneiras de otimizar a performance do BigQuery DataFrames.

Modo de ordenação parcial

O DataFrames do BigQuery oferece um recurso de modo de ordenação. Defina a propriedade ordering_mode como partial para gerar consultas mais eficientes.

O modo de ordenação partial contrasta com o modo strict padrão, que cria uma ordenação total em todas as linhas. Uma ordenação total torna os DataFrames do BigQuery mais compatíveis com o pandas, fornecendo acesso baseado em ordem às linhas com a propriedade DataFrame.iloc. No entanto, a ordenação total e o índice sequencial padrão sobre essa ordenação significam que nem os filtros de coluna nem os de linha reduzem o número de bytes verificados, a menos que esses filtros sejam aplicados como parâmetros às funções read_gbq e read_gbq_table. Para fornecer uma ordenação total em todas as linhas do DataFrame, o BigQuery DataFrames cria um hash de todas as linhas. Isso pode resultar em uma verificação de dados completa que ignora os filtros de linha e coluna.

Definir a propriedade ordering_mode como partial impede que os DataFrames do BigQuery gerem uma ordenação total em todas as linhas. O modo de ordenação parcial também desativa recursos que exigem uma ordenação total em todas as linhas, como a propriedade DataFrame.iloc. O modo de ordenação parcial define a classe DefaultIndexKind como um índice nulo, em vez de um índice sequencial sobre a ordenação.

Ao filtrar um DataFrame com a propriedade ordering_mode definida como partial, o BigQuery DataFrames não precisa mais calcular quais linhas estão ausentes no índice sequencial. Assim, ele gera consultas mais rápidas e eficientes. A API DataFrames do BigQuery ainda é a API familiar do pandas, assim como a experiência padrão com o modo de ordenação rígida. No entanto, o modo de ordenação parcial é diferente do comportamento comum do pandas. Por exemplo, o modo de ordenação parcial não realiza mesclagens implícitas por índice.

Com os modos de ordenação parcial e estrito, você paga pelos recursos do BigQuery que usa. No entanto, o uso do modo de ordenação parcial pode reduzir os custos ao trabalhar com tabelas agrupadas e particionadas grandes, porque os filtros de linha em colunas de cluster e de partição reduzem o número de bytes processados.

Uso

Para usar a ordenação parcial, defina a propriedade ordering_mode como partial antes de realizar qualquer outra operação com os BigQuery DataFrames, conforme mostrado no exemplo de código a seguir:

import bigframes.pandas as bpd

bpd.options.bigquery.ordering_mode = "partial"

Como não há um índice sequencial com o modo de ordenação parcial, os DataFrames do BigQuery não relacionados não são mesclados implicitamente. Em vez disso, é necessário chamar explicitamente o método DataFrame.merge para mesclar dois DataFrames do BigQuery que derivam de diferentes expressões de tabela.

Os recursos Series.unique() e Series.drop_duplicates() não são compatíveis com o modo de ordenação parcial. Em vez disso, use o método groupby para encontrar valores exclusivos desta forma:

# Avoid order dependency by using groupby instead of drop_duplicates.
unique_col = df.groupby(["column"], as_index=False).size().drop(columns="size")

Com o modo de ordenação parcial, a saída das funções DataFrame.head(n) e Series.head(n) não é idempotente em todas as invocações. Para fazer o download de uma amostra pequena e arbitrária dos dados, use os métodos DataFrame.peek() ou Series.peek().

Para conferir um tutorial detalhado em que você usa a propriedade ordering_mode = "partial", consulte este notebook do BigQuery DataFrames que demonstra o uso do modo de ordenação parcial.

Solução de problemas

Como os DataFrames no modo de ordenação parcial nem sempre têm uma ordenação ou índice, você pode encontrar os seguintes problemas ao usar alguns métodos compatíveis com pandas.

Erro de pedido obrigatório

Alguns recursos exigem uma ordenação, como as funções DataFrame.head() e DataFrame.iloc. Para conferir uma lista de recursos que exigem ordenação, consulte a coluna Requires ordering em APIs pandas compatíveis.

Quando não há ordenação no objeto, a operação falha com uma mensagem OrderRequiredError semelhante a esta:

OrderRequiredError: Op iloc requires an ordering. Use .sort_values or .sort_index to provide an ordering.

Conforme descrito na mensagem de erro, é possível fornecer uma ordenação usando o método DataFrame.sort_values() para classificar por uma ou mais colunas. Outras operações, como a DataFrame.groupby(), fornecem implicitamente uma ordenação total sobre o grupo por chaves.

Se não for possível determinar se a ordenação é totalmente estável em todas as linhas, as operações subsequentes poderão avisar com uma mensagem AmbiguousWindowWarning como esta:

AmbiguousWindowWarning: Window ordering may be ambiguous, this can cause unstable results.

Se a sua carga de trabalho puder acomodar resultados não determinísticos ou se você puder verificar manualmente se a ordenação fornecida é uma ordenação total, é possível filtrar a mensagem AmbiguousWindowWarning desta forma:

import warnings

import bigframes.exceptions

warnings.simplefilter(
    "ignore", category=bigframes.exceptions.AmbiguousWindowWarning
)
Erro de índice nulo

Alguns recursos exigem um índice, como as propriedades DataFrame.unstack() e Series.interpolate(). Para uma lista de recursos que exigem um índice, consulte a coluna Requires index em APIs do Pandas compatíveis.

Quando você usa uma operação que exige um índice com o modo de ordenação parcial, a operação gera uma mensagem NullIndexError semelhante a esta:

NullIndexError: DataFrame cannot perform interpolate as it has no index. Set an index using set_index.

Conforme descrito na mensagem de erro, é possível fornecer um índice usando o método DataFrame.set_index() para classificar por uma ou mais colunas. Outras operações, como a DataFrame.groupby(), fornecem implicitamente um índice sobre o grupo por chaves, a menos que o parâmetro as_index=False esteja definido.

Visualizações

A API bigframes.pandas é um gateway para o ecossistema completo de ferramentas do Python. A API permite operações estatísticas avançadas, e é possível visualizar as agregações geradas pelo BigQuery DataFrames. Também é possível alternar de um DataFrame do BigQuery DataFrames para um pandas com operações de amostragem integradas.

A seguir