Transformações com dbt

Organize suas transformações SQL em modelos versionados, com dependências, camadas, testes e linhagem documentada.

Cerca de 16 min · Revisado em

Ao final, você vai conseguir

  • Escrever um modelo dbt usando source() e ref()
  • Escrever a consulta de um modelo de staging que renomeia, converte e padroniza dados brutos
  • Organizar modelos nas camadas staging, intermediate e marts e escolher a materialização
  • Declarar os testes unique, not_null, relationships e accepted_values em YAML
  • Usar dbt run, dbt test e dbt build e interpretar a linhagem

Em muita empresa, o “número oficial” de faturamento vive numa consulta SQL de 300 linhas, salva no computador de uma pessoa, que só ela sabe rodar. Quando essa pessoa sai de férias, o relatório para. O dbt existe para acabar com isso: transforma consultas soltas em um projeto versionado, testado e documentado, que qualquer pessoa do time consegue rodar com um comando. Ele aparece em boa parte das vagas de engenharia e análise de dados.

SQL solto, SQL organizado

Na aula de pipelines batch você viu o ELT: o dado bruto é carregado no banco e transformado lá dentro. O dbt (data build tool) cuida desse T. Você escreve cada transformação como um SELECT num arquivo; ele cria as tabelas e views no banco, na ordem certa, e roda testes sobre o resultado.

O dbt não busca dados em APIs nem copia arquivos: ele só trabalha com o que já está no banco. A extração continua sendo papel do pipeline. E ele roda em vários bancos: PostgreSQL, DuckDB, BigQuery, Snowflake e outros, por meio de adaptadores.

Qual destas tarefas o dbt faz?

  • Criar uma tabela de faturamento diário a partir de uma tabela de pedidos que já está no banco
  • Baixar os pedidos da API da loja toda madrugada
  • Mostrar gráficos de vendas para a diretoria

Um modelo é só um SELECT

No dbt, cada arquivo .sql dentro da pasta models/ é um modelo: um SELECT que vira uma tabela ou view com o mesmo nome do arquivo. Você nunca escreve CREATE TABLE; o dbt escreve por você.

O arquivo models/staging/stg_pedidos.sql

{{ config(materialized='view') }}

with origem as (
    select * from {{ source('loja', 'pedidos') }}
),

renomeado as (
    select
        cast(id as integer) as pedido_id,
        cast(cliente_id as integer) as cliente_id,
        valor_centavos / 100.0 as valor,
        lower(trim(status)) as status,
        cast(criado_em as date) as data_pedido
    from origem
)

select * from renomeado
  • Configuração: Diz como o resultado vira objeto no banco. Aqui, uma view. As chaves duplas {{ }} são Jinja, uma linguagem de modelos que o dbt processa antes de mandar o SQL ao banco.
  • source(): Aponta para uma tabela bruta, carregada pelo pipeline. As fontes são declaradas num arquivo YAML, então o dbt sabe de onde cada dado vem.
  • CTE de limpeza: Uma CTE (with ... as) dá nome a um passo intermediário, como você viu em SQL analítico. Aqui ela renomeia colunas, converte tipos e padroniza textos.
  • Resultado: O último SELECT é o que vira a view stg_pedidos. Nada de CREATE ou INSERT.

Outro modelo usa esse resultado com ref(). Escrever {{ ref('stg_pedidos') }} em vez do nome da tabela faz duas coisas: o dbt troca pelo nome certo no banco (de desenvolvimento ou de produção) e anota que um modelo depende do outro. É dessas anotações que sai a ordem de execução.

Fonte, staging e o modelo final, lado a lado

_sources.yml

version: 2

sources:
  - name: loja
    schema: bruto
    tables:
      - name: pedidos
      - name: clientes

fct_vendas_diarias.sql

{{ config(materialized='table') }}

select
    data_pedido,
    count(*) as pedidos,
    sum(valor) as faturamento
from {{ ref('stg_pedidos') }}
where status = 'pago'
group by data_pedido

Complete o modelo que junta pedidos e clientes. O modelo de clientes se chama stg_clientes.

select
    p.pedido_id,
    p.valor,
    c.cidade
from {{ ____('stg_pedidos') }} as p
join {{ ref('____') }} as c
    on c.cliente_id = p.cliente_id

Camadas: staging, intermediate e marts

Projetos dbt costumam organizar os modelos em três camadas, cada uma com uma função. É a mesma ideia de separar bruto e tratado, levada um passo adiante.

Camada 1

Staging (stg_)

Um modelo por tabela bruta. Só limpeza leve: renomear, converter tipos, padronizar. Nada de juntar tabelas.

Camada 2

Intermediate (int_)

Passos de lógica reutilizáveis: juntar pedidos com clientes, deduplicar eventos. Ninguém de fora consulta direto.

Camada 3

Marts (fct_, dim_)

Tabelas prontas para consumo, como fatos e dimensões da aula de modelagem analítica. É o que painéis e analistas leem.

Em que camada cada transformação deve ficar?

Staging · Intermediate · Marts

  • Renomear CLI_ID para cliente_id e converter para inteiro
  • Converter centavos em reais
  • Remover da fonte os pedidos marcados como teste
  • Juntar pedidos com clientes para calcular o frete por cidade
  • Deduplicar eventos de pagamento antes de combinar com pedidos
  • A tabela fct_vendas_diarias que o financeiro consulta
  • A tabela dim_clientes com cidade e data do primeiro pedido

Escreva o modelo de staging

A tabela bruta raw_pedidos veio com nomes em maiúsculas, tudo como texto e um pedido de teste. Escreva o SELECT do staging com as colunas pedido_id e cliente_id (inteiros), valor (em reais), status (minúsculo e sem espaços) e data_pedido (só a data), sem o pedido de status teste. Este banco é SQLite: use CAST, LOWER, TRIM e DATE.

SELECT
  ID AS pedido_id,
  CLIENTE_ID AS cliente_id,
  VALOR_CENTAVOS,
  STATUS,
  CRIADO_EM
FROM raw_pedidos;
  • O resultado tem as colunas pedido_id, cliente_id, valor, status e data_pedido
  • O pedido de teste ficou de fora (5 pedidos)
  • Os IDs viraram números
  • O valor está em reais: o pedido 101 vale 35.9
  • Os status estão padronizados: 3 pedidos pago
  • A data do pedido não tem hora

View, table ou incremental

A materialização é como o dbt guarda o resultado de um modelo no banco. O SELECT é o mesmo; muda o custo de construir e o custo de consultar.

As três materializações mais usadas
MaterializaçãoO que o dbt criaBom para
viewUma consulta salva. Nada é guardado; roda toda vez que alguém lêStaging e modelos leves
tableUma tabela de verdade, reconstruída inteira a cada execuçãoMarts lidos por painéis, de tamanho moderado
incrementalUma tabela que recebe só as linhas novas ou alteradas a cada execuçãoTabelas enormes que crescem todo dia

Um modelo incremental: a marca d’água da aula anterior, escrita em dbt

{{ config(materialized='incremental', unique_key='pedido_id') }}

select * from {{ ref('stg_pedidos') }}

{% if is_incremental() %}
where atualizado_em > (select max(atualizado_em) from {{ this }})
{% endif %}

Na primeira execução, is_incremental() é falso e a tabela é criada inteira. Nas seguintes, o filtro traz só o que mudou, e o unique_key faz o dbt atualizar em vez de duplicar. {{ this }} é a própria tabela do modelo.

O modelo fct_cliques tem 2 bilhões de linhas e recebe 5 milhões por dia. Como table, cada execução leva 3 horas. O que você faria?

  • Trocar para incremental, com uma chave única e um filtro de data
  • Trocar para view, que não guarda nada
  • Manter table e rodar uma vez por semana

Testes que vigiam os dados

Um teste no dbt é uma consulta que procura linhas problemáticas. Se ela devolve zero linhas, o teste passa. Os mais comuns vêm prontos e você só declara em YAML, ao lado da descrição de cada coluna.

O arquivo models/staging/_staging.yml

version: 2

models:
  - name: stg_pedidos
    description: Um pedido por linha, já limpo.
    columns:
      - name: pedido_id
        data_tests:
          - unique
          - not_null
      - name: cliente_id
        data_tests:
          - relationships:
              arguments:
                to: ref('stg_clientes')
                field: cliente_id
      - name: status
        data_tests:
          - accepted_values:
              arguments:
                values: ['pago', 'pendente', 'cancelado']
  • Documentação: O texto vai para o site de documentação que o dbt gera. Quem chega no time descobre o que cada tabela significa sem perguntar.
  • unique e not_null: unique procura valores repetidos; not_null procura valores vazios. Juntos garantem que pedido_id é uma boa chave.
  • relationships: Procura pedidos cujo cliente_id não existe em stg_clientes: os chamados órfãos.
  • accepted_values: Procura qualquer valor fora da lista. Se a fonte começar a mandar estornado, você descobre no teste, não no painel. Em versões antigas do dbt, os valores ficam direto, sem arguments.

Que teste pegaria cada problema?

unique · not_null · relationships · accepted_values

  • O pedido 1002 aparece duas vezes
  • Um cliente foi cadastrado duas vezes com o mesmo cliente_id
  • Um pedido chegou sem pedido_id
  • Um pedido aponta para o cliente 9, que não existe
  • Um pedido veio com status Pago!!
  • Uma loja aparece com UF XX

Rodar, testar e enxergar a linhagem

O dbt é usado pela linha de comando. Três comandos fazem quase tudo: dbt run constrói os modelos, dbt test roda os testes e dbt build faz os dois juntos, na ordem das dependências, pulando o que depende de algo que falhou.

Um dia de trabalho com dbt

Construa o projeto, encontre o teste que falha e reconstrua só o que precisa.

  1. Entre na pasta do projeto loja_dbt.

    cd loja_dbt
  2. Construa todos os modelos no banco.

    dbt run
    Running with dbt=1.10.11
    Registered adapter: duckdb=1.10.0
    Found 4 models, 7 data tests, 2 sources, 512 macros
    
    Concurrency: 1 threads (target='dev')
    
    1 of 4 OK created sql view model main.stg_clientes ........ [OK in 0.04s]
    2 of 4 OK created sql view model main.stg_pedidos ......... [OK in 0.03s]
    3 of 4 OK created sql view model main.int_pedidos_com_cliente [OK in 0.03s]
    4 of 4 OK created sql table model main.fct_vendas_diarias . [OK in 0.09s]
    
    Finished running 3 view models, 1 table model in 0.52s.
    Completed successfully
    Done. PASS=4 WARN=0 ERROR=0 SKIP=0 TOTAL=4
  3. Agora rode os testes declarados no YAML.

    dbt test
    Running with dbt=1.10.11
    Found 4 models, 7 data tests, 2 sources, 512 macros
    
    1 of 7 PASS accepted_values_stg_pedidos_status ........ [PASS in 0.03s]
    2 of 7 PASS not_null_stg_clientes_cliente_id ........... [PASS in 0.02s]
    3 of 7 PASS not_null_stg_pedidos_pedido_id ............. [PASS in 0.02s]
    4 of 7 PASS relationships_stg_pedidos_cliente_id ....... [PASS in 0.03s]
    5 of 7 PASS unique_stg_clientes_cliente_id ............. [PASS in 0.02s]
    6 of 7 FAIL 1 unique_stg_pedidos_pedido_id ............. [FAIL 1 in 0.02s]
    7 of 7 PASS not_null_fct_vendas_diarias_data_pedido .... [PASS in 0.02s]
    
    Completed with 1 error, 0 partial successes, and 0 warnings:
    
    Failure in test unique_stg_pedidos_pedido_id (models/staging/_staging.yml)
      Got 1 result, configured to fail if != 0
    
    Done. PASS=6 WARN=0 ERROR=1 SKIP=0 TOTAL=7
  4. Você investigou: um pedido veio repetido da fonte, e já acrescentou a deduplicação em stg_pedidos. Construa e teste só esse modelo e tudo o que depende dele (o + depois do nome).

    dbt build --select stg_pedidos+
    Running with dbt=1.10.11
    Found 4 models, 7 data tests, 2 sources, 512 macros
    
    1 of 8 OK created sql view model main.stg_pedidos ......... [OK in 0.03s]
    2 of 8 PASS accepted_values_stg_pedidos_status ............ [PASS in 0.02s]
    3 of 8 PASS not_null_stg_pedidos_pedido_id ................ [PASS in 0.02s]
    4 of 8 PASS relationships_stg_pedidos_cliente_id .......... [PASS in 0.02s]
    5 of 8 PASS unique_stg_pedidos_pedido_id .................. [PASS in 0.02s]
    6 of 8 OK created sql view model main.int_pedidos_com_cliente [OK in 0.03s]
    7 of 8 OK created sql table model main.fct_vendas_diarias . [OK in 0.08s]
    8 of 8 PASS not_null_fct_vendas_diarias_data_pedido ....... [PASS in 0.02s]
    
    Completed successfully
    Done. PASS=8 WARN=0 ERROR=0 SKIP=0 TOTAL=8
  5. Gere o site de documentação, que inclui o gráfico de linhagem.

    dbt docs generate
    Running with dbt=1.10.11
    Found 4 models, 7 data tests, 2 sources, 512 macros
    
    Building catalog
    Catalog written to /home/voce/loja_dbt/target/catalog.json

Repare na ordem do dbt build: o teste de stg_pedidos rodou antes dos modelos que dependem dele. Se tivesse falhado, fct_vendas_diarias seria pulado (SKIP) e o painel continuaria com os números de ontem, em vez de números errados.

Linhagem: de onde vem cada número do painel

  1. loja.pedidos → stg_pedidos: source('loja','pedidos'). O staging lê a tabela bruta carregada pelo pipeline.
  2. stg_pedidos → stg_pedidos: unique, not_null: PASS. Os testes do staging rodam antes de qualquer modelo que dependa dele.
  3. stg_pedidos → fct_vendas_dia: ref('stg_pedidos'). O mart soma o faturamento por dia a partir do staging.
  4. fct_vendas_dia → Painel: Faturamento por dia. O painel lê só o mart. Quem olha o gráfico pode seguir a linhagem de volta até a fonte.
  5. loja.pedidos → stg_pedidos: Pedido 103 repetido. No dia seguinte, a fonte manda um pedido duplicado.
  6. stg_pedidos → stg_pedidos: unique: FAIL. O teste de unicidade encontra a linha repetida.
  7. stg_pedidos → fct_vendas_dia: fct pulado (SKIP). O dbt build não reconstrói o mart. O painel mostra dados de ontem, corretos, em vez de dados de hoje, errados.

Em que ordem o dbt build executa este projeto?

  • Lê a fonte loja.pedidos (declarada em _sources.yml)
  • Cria a view stg_pedidos
  • Testa stg_pedidos com unique e not_null
  • Cria int_pedidos_com_cliente, que usa ref('stg_pedidos')
  • Cria a tabela fct_vendas_diarias
  • Testa fct_vendas_diarias

Fechamento

  • O dbt cuida do T do ELT: cada modelo é um SELECT num arquivo, e o dbt cria a tabela ou view no banco.
  • source() aponta para tabelas brutas e ref() para outros modelos; dessas referências saem a ordem de execução e a linhagem.
  • Staging limpa cada fonte, intermediate combina e reaproveita lógica, marts entregam tabelas prontas para consumo.
  • A materialização (view, table, incremental) troca custo de construção por custo de consulta.
  • Testes como unique, not_null, relationships e accepted_values procuram linhas problemáticas, e o dbt build não deixa um erro chegar aos marts.

Seu primeiro projeto dbt local

Use o dbt com DuckDB, que roda no seu computador sem servidor nem custo, sobre um conjunto de dados público ou sintético já carregado por você.

  1. Instale dbt-duckdb num ambiente virtual Python e crie o projeto com dbt init
  2. Declare suas tabelas brutas em _sources.yml e crie um modelo stg_ para cada uma
  3. Crie um modelo de marts que junte duas tabelas usando ref()
  4. Adicione unique e not_null na chave de cada modelo e um relationships entre eles
  5. Rode dbt build, provoque uma falha inserindo uma linha duplicada na fonte e veja o mart ser pulado
  6. Gere a documentação com dbt docs generate e tire um print do gráfico de linhagem para o README

Referências

Cursos relacionados