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()eref() - 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,relationshipseaccepted_valuesem YAML - Usar
dbt run,dbt testedbt builde 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 viewstg_pedidos. Nada deCREATEouINSERT.
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: clientesfct_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_pedidoComplete 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_idCamadas: 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_IDparacliente_ide 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_diariasque o financeiro consulta - A tabela
dim_clientescom 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,statusedata_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.
| Materialização | O que o dbt cria | Bom para |
|---|---|---|
view | Uma consulta salva. Nada é guardado; roda toda vez que alguém lê | Staging e modelos leves |
table | Uma tabela de verdade, reconstruída inteira a cada execução | Marts lidos por painéis, de tamanho moderado |
incremental | Uma tabela que recebe só as linhas novas ou alteradas a cada execução | Tabelas 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
tablee 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:
uniqueprocura valores repetidos;not_nullprocura valores vazios. Juntos garantem quepedido_idé uma boa chave. - relationships: Procura pedidos cujo
cliente_idnão existe emstg_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, semarguments.
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.
Entre na pasta do projeto
loja_dbt.cd loja_dbtConstrua todos os modelos no banco.
dbt runRunning 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=4Agora rode os testes declarados no YAML.
dbt testRunning 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=7Você 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=8Gere o site de documentação, que inclui o gráfico de linhagem.
dbt docs generateRunning 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
- loja.pedidos → stg_pedidos: source('loja','pedidos'). O staging lê a tabela bruta carregada pelo pipeline.
- stg_pedidos → stg_pedidos: unique, not_null: PASS. Os testes do staging rodam antes de qualquer modelo que dependa dele.
- stg_pedidos → fct_vendas_dia: ref('stg_pedidos'). O mart soma o faturamento por dia a partir do staging.
- 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.
- loja.pedidos → stg_pedidos: Pedido 103 repetido. No dia seguinte, a fonte manda um pedido duplicado.
- stg_pedidos → stg_pedidos: unique: FAIL. O teste de unicidade encontra a linha repetida.
- stg_pedidos → fct_vendas_dia: fct pulado (SKIP). O
dbt buildnã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_pedidoscomuniqueenot_null - Cria
int_pedidos_com_cliente, que usaref('stg_pedidos') - Cria a tabela
fct_vendas_diarias - Testa
fct_vendas_diarias
Fechamento
- O dbt cuida do T do ELT: cada modelo é um
SELECTnum arquivo, e o dbt cria a tabela ou view no banco. source()aponta para tabelas brutas eref()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,relationshipseaccepted_valuesprocuram linhas problemáticas, e odbt buildnã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ê.
- Instale
dbt-duckdbnum ambiente virtual Python e crie o projeto comdbt init - Declare suas tabelas brutas em
_sources.ymle crie um modelostg_para cada uma - Crie um modelo de marts que junte duas tabelas usando
ref() - Adicione
uniqueenot_nullna chave de cada modelo e umrelationshipsentre eles - Rode
dbt build, provoque uma falha inserindo uma linha duplicada na fonte e veja o mart ser pulado - Gere a documentação com
dbt docs generatee tire um print do gráfico de linhagem para o README