Tutorial dbt: SQL versionado, testado e documentado

meu_projeto/
├── dbt_project.yml
├── models/
│   ├── staging/          # 1 model por tabela de origem, só limpeza
│   │   ├── stg_pedidos.sql
│   │   ├── stg_clientes.sql
│   │   └── _staging.yml   # sources + testes
│   ├── intermediate/     # joins e regras reutilizáveis
│   │   └── int_pedidos_enriquecidos.sql
│   └── marts/            # o que o negócio consome
│       ├── fct_pedidos.sql
│       └── dim_clientes.sql
├── macros/
├── snapshots/
└── tests/

Regra de ouro: staging não faz join, marts não fazem limpeza. Isso sozinho evita metade da bagunça em projetos dbt.

-- models/staging/stg_pedidos.sql
{{ config(materialized='view') }}

select
    id                        as pedido_id,
    cliente_id,
    lower(trim(status))       as status,
    valor_centavos / 100.0    as valor,
    cast(criado_em as date)   as data_pedido
from {{ source('loja', 'pedidos') }}
where criado_em is not null

-- models/marts/fct_pedidos.sql
{{ config(materialized='table') }}

with pedidos as (
    select * from {{ ref('stg_pedidos') }}
),
clientes as (
    select * from {{ ref('stg_clientes') }}
)

select
    p.pedido_id,
    p.data_pedido,
    p.valor,
    c.uf,
    c.segmento
from pedidos p
left join clientes c on c.cliente_id = p.cliente_id
where p.status = 'pago'

Você nunca escreve o nome físico da tabela. O ref() resolve o schema certo em dev e em prod e monta o grafo de execução sozinho.

# models/staging/_staging.yml
version: 2

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

models:
  - name: stg_pedidos
    columns:
      - name: pedido_id
        tests: [unique, not_null]
      - name: cliente_id
        tests:
          - not_null
          - relationships:
              to: ref('stg_clientes')
              field: cliente_id
      - name: status
        tests:
          - accepted_values:
              values: ['pago', 'pendente', 'cancelado']

dbt build          # roda models + testes na ordem do grafo
dbt run --select marts+   # só marts e o que depende deles
dbt test --select stg_pedidos
dbt docs generate && dbt docs serve

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

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

{% if is_incremental() %}
  where data_pedido >= (select coalesce(max(data_pedido), '1900-01-01') from {{ this }})
{% endif %}

Na primeira execução o dbt cria a tabela inteira; nas seguintes, processa só o novo e faz MERGE pela unique_key. É o que derruba custo de warehouse de verdade.

• Usar nome de tabela cru em vez de ref() — quebra o grafo e o ambiente de dev.
• Model de 400 linhas fazendo tudo. Quebre em staging → intermediate → mart.
• Zero testes: sem unique e not_null nas chaves, duplicata chega no dashboard.
• Tudo como table: custo alto sem necessidade. Comece com view.
• Regra de negócio escondida no BI em vez de estar no mart, versionada no Git.