Construindo Modelos dbt

O que Construindo Modelos dbt faz?

Quando usar

• Ao criar ou refatorar modelos .sql em um projeto dbt.
• Ao decidir a materialização (view / table / incremental / ephemeral).
• Ao estruturar camadas (staging → intermediate → marts).
• Ao escrever modelos incrementais para tabelas grandes e crescentes.
• NÃO use para criação de testes (use testing-dbt-projects) ou falhas de execução (use debugging-dbt-runs).

Fluxo de trabalho

- [ ] Coloque o modelo na camada correta (staging/intermediate/marts)
- [ ] Referencie upstream apenas via ref()/source() — nunca nomes fixos
- [ ] Escolha a materialização com base no tamanho e na necessidade de atualização
- [ ] Para incremental, defina unique_key + filtro is_incremental()
- [ ] Adicione uma entrada em schema.yml com testes

1. Camadas. staging/ = um modelo por tabela de origem, renomeação/tipagem leve, materializado como views. intermediate/ = lógica de negócio reutilizável. marts/ = modelos dimensionais finais consumidos por BI, materializados como tables.
2. Referencie corretamente. Use {{ ref('stg_orders') }} e {{ source('shop', 'orders') }} para que o dbt construa o DAG e gerencie ambientes. Nunca escreva schema.table diretamente.
3. Escolha a materialização: view (barata, sempre fresca, pequena), table (leituras rápidas, reconstruída a cada execução), incremental (tabelas grandes com append/update), ephemeral (CTE inline, sem objeto).
4. Modelos incrementais processam apenas linhas novas/alteradas.

Padrões

Modelo de staging — um por fonte, enxuto e consistente:

-- models/staging/shop/stg_orders.sql
with source as (select * from {{ source('shop', 'orders') }})
select
    order_id,
    customer_id,
    cast(order_ts as timestamp) as ordered_at,
    round(amount_cents / 100.0, 2) as amount
from source

Modelo incremental — filtra linhas novas e define uma chave de merge idempotente:

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

select * from {{ ref('stg_orders') }}
{% if is_incremental() %}
  -- apenas linhas mais recentes que as já carregadas, com lookback para dados tardios
  where ordered_at >= (select coalesce(max(ordered_at), '1900-01-01') from {{ this }})
                      - interval '3 days'
{% endif %}

unique_key + merge torna reexecuções idempotentes; o lookback captura linhas que chegam atrasadas. No BigQuery/Spark, prefira insert_overwrite em uma partição de data.

Armadilhas comuns

• Nomes de tabela fixos em vez de ref()/source() — quebra o DAG, a linhagem e a troca de ambientes.
• Incremental sem unique_key — reexecuções geram duplicatas.
• Filtro incremental max(id) sem lookback — descarta silenciosamente dados tardios.
• Lógica de negócio no staging — mantenha o staging enxuto; joins/agregações pertencem ao intermediate/marts.
• Tudo materializado como table — desperdiça tempo de warehouse; use views para modelos pequenos/baratos e incremental para grandes.
• Modelo gigante único — divida em etapas intermediárias para testabilidade e reuso.

Referências

• Convenções de estrutura de projeto dbt