Usar DataFrames do BigQuery no dbt

O dbt (data build tool) é uma estrutura de linha de comando de código aberto projetada para transformação de dados em data warehouses modernos. O dbt facilita transformações de dados modulares com a criação de modelos reutilizáveis baseados em SQL e Python. A ferramenta orquestra a execução dessas transformações no data warehouse de destino, com foco na etapa de transformação do pipeline ELT. Para mais informações, consulte a documentação do dbt.

No dbt, um modelo Python é uma transformação de dados definida e executada usando código Python no projeto dbt. Em vez de escrever SQL para a lógica de transformação, você escreve scripts Python que o dbt orquestra para serem executados no ambiente do data warehouse. Um modelo em Python permite realizar transformações de dados que podem ser complexas ou ineficientes para expressar em SQL. Isso aproveita os recursos do Python, mas ainda se beneficia da estrutura de projeto, da orquestração, do gerenciamento de dependências, dos testes e dos recursos de documentação do dbt. Para mais informações, consulte Modelos do Python.

O adaptador dbt-bigquery permite executar código Python definido em DataFrames do BigQuery. Esse recurso está disponível no dbt Cloud e no dbt Core. Também é possível clonar a versão mais recente do adaptador dbt-bigquery.

Funções exigidas

O adaptador dbt-bigquery é compatível com a autenticação baseada em OAuth e em conta de serviço.

Se você planeja se autenticar no adaptador dbt-bigquery usando o OAuth, peça ao administrador para conceder os seguintes papéis:

Se você planeja autenticar no adaptador dbt-bigquery usando uma conta de serviço, peça ao administrador para conceder os seguintes papéis à conta de serviço que você planeja usar:

Se você estiver fazendo a autenticação usando uma conta de serviço, verifique se tem o papel de usuário da conta de serviço (roles/iam.serviceAccountUser) concedido para a conta de serviço que você planeja usar.

Ambiente de execução do Python

O adaptador dbt-bigquery usa o serviço de executor de notebooks do Colab Enterprise para executar o código Python do BigQuery DataFrames. Um notebook do Colab Enterprise é criado e executado automaticamente pelo adaptador dbt-bigquery para cada modelo do Python. É possível escolher o projetoTrusted Cloud em que o notebook será executado. O notebook executa o código Python do modelo, que é convertido em SQL do BigQuery pela biblioteca DataFrames do BigQuery. O SQL do BigQuery é executado no projeto configurado. O diagrama a seguir apresenta o fluxo de controle:

Ambiente de execução do Python do BigQuery DataFrames para um notebook

Se não houver um modelo de notebook disponível no projeto e o usuário que executa o código tiver as permissões para criar o modelo, o adaptador dbt-bigquery vai criar e usar automaticamente o modelo de notebook padrão. Também é possível especificar um modelo de notebook diferente usando uma configuração do dbt.

A execução do notebook exige um bucket de teste do Cloud Storage para armazenar o código e os registros. No entanto, o adaptador dbt-bigquery copia os registros para os registros do dbt, então não é necessário procurar no bucket.

Recursos compatíveis

O adaptador dbt-bigquery oferece suporte aos seguintes recursos para modelos do dbt Python que executam DataFrames do BigQuery:

  • Carregar dados de uma tabela do BigQuery usando a macro dbt.source().
  • Carregar dados de outros modelos do dbt com a macro dbt.ref() para criar dependências e gráficos acíclicos direcionados (DAGs) com modelos do Python.
  • Especificar e usar pacotes Python do PyPi que podem ser usados com a execução de código Python. Para mais informações, consulte Configurações.
  • Especificar um modelo de ambiente de execução de notebook personalizado para seus modelos de DataFrames do BigQuery.

O adaptador dbt-bigquery é compatível com as seguintes estratégias de materialização:

  • Materialização de tabela, em que os dados são recriados como uma tabela em cada execução.
  • Materialização incremental com uma estratégia de mesclagem, em que dados novos ou atualizados são adicionados a uma tabela existente, geralmente usando uma estratégia de mesclagem para processar mudanças.

Como configurar o dbt para usar o BigQuery DataFrames

Se você estiver usando o dbt Core, use um arquivo profiles.yml para usar com o BigQuery DataFrames. O exemplo a seguir usa o método oauth:

your_project_name:
  outputs:
    dev:
      compute_region: us-central1
      dataset: your_bq_dateset
      gcs_bucket: your_gcs_bucket
      job_execution_timeout_seconds: 300
      job_retries: 1
      location: US
      method: oauth
      priority: interactive
      project: your_gcp_project
      threads: 1
      type: bigquery
  target: dev

Se você estiver usando o dbt Cloud, é possível conectar-se à sua plataforma de dados diretamente na interface do dbt Cloud. Nesse cenário, você não precisa de um arquivo profiles.yml. Para mais informações, consulte Sobre profiles.yml

Este é um exemplo de configuração no nível do projeto para o arquivo dbt_project.yml:

# Name your project! Project names should contain only lowercase characters
# and underscores. A good package name should reflect your organization's
# name or the intended use of these models.
name: 'your_project_name'
version: '1.0.0'

# Configuring models
# Full documentation: https://docs.getdbt.com/docs/configuring-models

# In this example config, we tell dbt to build all models in the example/
# directory as views. These settings can be overridden in the individual model
# files using the config(...) macro.

models:
  your_project_name:
    submission_method: bigframes
    notebook_template_id: 7018811640745295872
    packages: ["scikit-learn", "mlflow"]
    timeout: 3000
    # Config indicated by + and applies to all files under models/example/
    example:
      +materialized: view

Alguns parâmetros também podem ser configurados usando o método dbt.config no código Python. Se essas configurações entrarem em conflito com o arquivo dbt_project.yml, as configurações com dbt.config terão precedência.

Para mais informações, consulte Configurações de modelo e dbt_project.yml.

Configurações

É possível configurar o seguinte usando o método dbt.config no modelo do Python. Essas configurações substituem a configuração no nível do projeto.

Configuração Obrigatório Uso
submission_method Sim submission_method=bigframes
notebook_template_id Não Se não for especificado, um modelo padrão será criado e usado.
packages Não Especifique a lista adicional de pacotes Python, se necessário.
timeout Não Opcional: estenda o tempo limite de execução do job.

Exemplos de modelos em Python

As seções a seguir apresentam exemplos de cenários e modelos do Python.

Carregar dados de uma tabela do BigQuery

Para usar dados de uma tabela do BigQuery como origem no seu modelo do Python, primeiro defina essa origem em um arquivo YAML. O exemplo a seguir é definido em um arquivo source.yml.

version: 2

sources:
  - name: my_project_source   # A custom name for this source group
    database: bigframes-dev   # Your Google Cloud project ID
    schema: yyy_test_us       # The BigQuery dataset containing the table
    tables:
      - name: dev_sql1        # The name of your BigQuery table

Em seguida, crie seu modelo em Python, que pode usar as fontes de dados configuradas neste arquivo YAML:

def model(dbt, session):
    # Configure the model to use BigFrames for submission
    dbt.config(submission_method="bigframes")

    # Load data from the 'dev_sql1' table within 'my_project_source'
    source_data = dbt.source('my_project_source', 'dev_sql1')

    # Example transformation: Create a new column 'id_new'
    source_data['id_new'] = source_data['id'] * 10

    return source_data

Referenciar outro modelo

É possível criar modelos que dependem da saída de outros modelos do dbt, conforme mostrado no exemplo a seguir. Isso é útil para criar pipelines de dados modulares.

def model(dbt, session):
    # Configure the model to use BigFrames
    dbt.config(submission_method="bigframes")

    # Reference another dbt model named 'dev_sql1'.
    # It assumes you have a model defined in 'dev_sql1.sql' or 'dev_sql1.py'.
    df_from_sql = dbt.ref("dev_sql1")

    # Example transformation on the data from the referenced model
    df_from_sql['id'] = df_from_sql['id'] * 100

    return df_from_sql

Como especificar uma dependência de pacote

Se o modelo Python exigir bibliotecas específicas de terceiros, como MLflow ou Boto3, declare o pacote na configuração do modelo, conforme mostrado no exemplo a seguir. Esses pacotes são instalados no ambiente de execução.

def model(dbt, session):
    # Configure the model for BigFrames and specify required packages
    dbt.config(
        submission_method="bigframes",
        packages=["mlflow", "boto3"]  # List the packages your model needs
    )

    # Import the specified packages for use in your model
    import mlflow
    import boto3

    # Example: Create a DataFrame showing the versions of the imported packages
    data = {
        "mlflow_version": [mlflow.__version__],
        "boto3_version": [boto3.__version__],
        "note": ["This demonstrates accessing package versions after import."]
    }
    bdf = bpd.DataFrame(data)

    return bdf

Como especificar um modelo não padrão

Para ter mais controle sobre o ambiente de execução ou usar configurações pré-configuradas, especifique um modelo de notebook não padrão para seu modelo do DataFrames do BigQuery, conforme mostrado no exemplo a seguir.

def model(dbt, session):
    dbt.config(
        submission_method="bigframes",
     # ID of your pre-created notebook template
        notebook_template_id="857350349023451yyyy",
    )

    data = {"int": [1, 2, 3], "str": ['a', 'b', 'c']}
    return bpd.DataFrame(data=data)

Materializar as tabelas

Quando o dbt executa seus modelos Python, ele precisa saber como salvar os resultados no data warehouse. Isso é chamado de materialização.

Para a materialização de tabelas padrão, o dbt cria ou substitui completamente uma tabela no seu data warehouse com a saída do modelo sempre que ele é executado. Isso é feito por padrão ou definindo explicitamente a propriedade materialized='table', conforme mostrado no exemplo a seguir.

def model(dbt, session):
    dbt.config(
        submission_method="bigframes",
     # Instructs dbt to create/replace this model as a table
        materialized='table',
    )

    data = {"int_column": [1, 2], "str_column": ['a', 'b']}
    return bpd.DataFrame(data=data)

A materialização incremental com uma estratégia de mesclagem permite que o dbt atualize sua tabela apenas com linhas novas ou modificadas. Isso é útil para grandes conjuntos de dados, porque reconstruir completamente uma tabela a cada vez pode ser ineficiente. A estratégia de mesclagem é uma maneira comum de lidar com essas atualizações.

Essa abordagem integra as mudanças de forma inteligente fazendo o seguinte:

  • Atualizar as linhas que foram alteradas.
  • Adicionar novas linhas.
  • Opcional, dependendo da configuração: excluir linhas que não estão mais presentes na origem.

Para usar a estratégia de mesclagem, especifique uma propriedade unique_key que o dbt pode usar para identificar as linhas correspondentes entre a saída do modelo e a tabela atual, conforme mostrado no exemplo a seguir.

def model(dbt, session):
    dbt.config(
        submission_method="bigframes",
        materialized='incremental',
        incremental_strategy='merge',
        unique_key='int',  # Specifies the column to identify unique rows
    )

    # In this example:
    # - Row with 'int' value 1 remains unchanged.
    # - Row with 'int' value 2 has been updated.
    # - Row with 'int' value 4 is a new addition.
    # The 'merge' strategy will ensure that only the updated row ('int 2')
    # and the new row ('int 4') are processed and integrated into the table.
    data = {"int": [1, 2, 4], "str": ['a', 'bbbb', 'd']}
    return bpd.DataFrame(data=data)

Solução de problemas

É possível observar a execução do Python nos registros do dbt.

Além disso, é possível conferir o código e os registros (incluindo execuções anteriores) na página Execuções do Colab Enterprise.

Acessar as execuções do Colab Enterprise

Faturamento

Ao usar o adaptador dbt-bigquery com o BigQuery DataFrames, há Trusted Cloud by S3NS cobranças dos seguintes itens:

  • Execução de notebook: há cobrança pela execução do ambiente de execução do notebook. Para mais informações, consulte Preços de tempo de execução do notebook.

  • Execução de consultas do BigQuery: no notebook, o BigQuery DataFrames converte Python em SQL e executa o código no BigQuery. Você recebe cobranças de acordo com a configuração do projeto e a consulta, conforme descrito nos preços do BigQuery DataFrames.

É possível usar o seguinte marcador de faturamento no console de faturamento do BigQuery para filtrar o relatório de faturamento da execução do notebook e das execuções do BigQuery acionadas pelo adaptador dbt-bigquery:

  • Rótulo de execução do BigQuery: bigframes-dbt-api

A seguir