dbt Cheat Sheet: comandos, flags e seleção de nós

Comandos

Não é o manual. Os verbos e flags que realmente merecem um lugar na memória muscular.

Verbos principais: o seu dia a dia

dbt build: Roda, testa, faz seed e snapshot de cada resource selecionado em ordem do DAG; o comando que a maioria dos times mais usa.
dbt run: Materializa os models (view / table / incremental …) no warehouse.
dbt test: Executa os data tests e unit tests definidos no projeto.
dbt seed: Carrega os arquivos CSV de seeds/ no warehouse.
dbt snapshot: Captura o histórico de slowly-changing-dimension das sources.

Mnemônico: build = run + test + seed + snapshot, todos intercalados na ordem de dependência.

Vale lembrar

dbt list: Mostra quais resources um selector seleciona (sem rodar nada).
dbt show: Faz um preview das linhas de um model depois da transformação.
dbt retry: Roda de novo a última invocação a partir do ponto de falha.
dbt clone: Copia os nós selecionados de um state para o(s) schema(s) de destino.
dbt compile: Renderiza o SQL sem executar. Inspecione o Jinja.
dbt source freshness: Verifica se as sources estão dentro do SLA de freshness declarado.
dbt parse: Faz o parse do projeto e emite os tempos; útil em CI.

Setup e utilitários

dbt init: Cria a estrutura de um novo projeto e configura a conexão no seu profiles.yml.
dbt deps: Instala os packages declarados em packages.yml / dependencies.yml.
dbt debug: Verifica a instalação, o profile ativo e a conexão com o warehouse.
dbt clean: Apaga as pastas em clean-targets: target/, dbt_packages/.
dbt docs generate: Gera o site de documentação e o artefato catalog.json.
dbt docs serve: Serve o site de docs gerado localmente no seu navegador.
dbt run-operation: Invoca uma macro diretamente: dbt run-operation my_macro --args '{k: v}'.

Flags que vale lembrar

--select / -s: Escolhe em quais resources agir. Veja Seleção de nós.
--exclude: Remove resources do conjunto do --select; mesma sintaxe.
--target / -t: Escolhe um target do profiles.yml: -t prod.
--defer: Resolve refs não selecionados a partir de outro state em vez de rebuildá-los.
--state: Caminho para um manifest.json, exigido por selectors que usam state e pelo --defer.
--full-refresh: Rebuilda os incremental models e seeds do zero.
--vars: Passa vars do projeto: --vars '{"start_date": "2024-01-01"}'.
--threads: Sobrescreve o número de threads do seu profile.
--store-failures: Persiste as linhas que falharam nos testes em uma tabela para debug.
--empty: Builda models só com o schema (zero linhas): uma checagem estrutural rápida para CI.
--sql 1.12+: No dbt run-operation, executa SQL ad-hoc diretamente. Sem precisar de arquivo de macro.

Como o `dbt build` roda

O dbt build roda cada model e, logo depois, os testes dele, na ordem de dependência. Avance passo a passo, alargue cada tick com --threads e faça um teste falhar para ver o que é pulado.

--threads um teste falha

rodando
passou
falhou
pulado

Flags triviais / de uso pontual: --help, --version, --debug, --log-level, --profiles-dir, --project-dir.

Essenciais

Materializações, testes e packages: os blocos de construção em que todo projeto dbt se apoia.

Materializações

Defina com {{ config(materialized='…') }} ou no dbt_project.yml.

view: Padrão. Um CREATE VIEW: sem armazenamento, sempre atualizada, recalculada a cada leitura.
table: CREATE TABLE AS: reconstruída do zero a cada execução.
incremental: Buildada uma vez; depois cada execução só insere / faz merge das linhas novas ou alteradas.
ephemeral: Não é buildada. É embutida como CTE nos models que a referenciam com ref().
materialized_view: Uma materialized view gerenciada pelo warehouse: o dbt é dono da definição, o warehouse mantém os dados atualizados.

Testes

generic: Data tests reutilizáveis declarados em YAML: unique, not_null, accepted_values, relationships.
singular: Um arquivo .sql avulso em tests/: qualquer query que retorne linhas com falha.
unit 1.8+: Testa a lógica de um model contra inputs mockados e output esperado, declarado com unit_tests:.

O dbt build roda os testes de cada model logo depois dele; falhas interrompem os dependentes. Use --store-failures para guardar as linhas problemáticas.

Packages que vale instalar

Adicione no packages.yml e rode dbt deps. Veja os demais no dbt Package hub.

dbt_utils: A caixa de ferramentas padrão: SQL cross-database, generic tests e macros auxiliares.
dbt_project_evaluator: Audita o seu projeto contra as regras de boas práticas do dbt.
dbt_expectations: Testes de qualidade de dados no estilo Great Expectations.
audit_helper: Compara duas relations para validar um refactor ou uma migração.
elementary: Testes de detecção de anomalias e relatórios de observabilidade de dados.
dbt_artifacts: Modela os resultados das suas execuções e metadados para monitoramento.

Modelos incrementais

A materialização que transforma só as linhas novas, e a que mais dá dor de cabeça. Estratégias, microbatch e mudanças de schema.

Estratégias de incremental

Escolha com config(materialized='incremental', incremental_strategy='…').

merge: Upsert pela unique_key: atualiza as linhas existentes, insere as novas.
append: Só insere linhas novas. Mais rápido, mas sem deduplicação.
delete+insert: Apaga as linhas que batem com o novo lote e depois insere: um merge sem MERGE nativo.
insert_overwrite: Substitui partições inteiras (por partition_by), não linhas. Sem unique_key; específico do warehouse (BigQuery, Spark, Snowflake).
microbatch 1.9+: Divide a carga em lotes por tempo, usando event_time: backfills robustos e que podem ser repetidos.

O is_incremental() controla um filtro where; a incremental_strategy decide como as linhas que ele deixa passar entram na tabela. Alterne os switches para ver o que cada execução grava em fct_orders.

a tabela já existe --full-refresh unique_key configurada Estratégia

select * from {{ source('shop', 'orders') }}
{% if is_incremental() %}
  where updated_at > (select max(updated_at) from {{ this }})
{% endif %}

dbt run -s fct_orders

fct_orders: antes

linhas que esta execução processa

fct_orders: depois

is_incremental() só é true quando a tabela já existe e você não passou --full-refresh.

Microbatch

Uma estratégia para tabelas de eventos grandes: uma execução, várias queries pequenas por data.

O microbatch é para tabelas grandes de série temporal. Em vez de uma query só com um filtro is_incremental(), o dbt divide a execução em uma query delimitada por período, aqui por dia. Cada batch é independente, então o dbt pode rodá-los em paralelo e dar retry só nos que falham.

{{ config(
    materialized='incremental',
    incremental_strategy='microbatch',
    event_time='session_start',
    batch_size='day',
    begin='2024-01-01',
) }}
select * from {{ ref('page_views') }}

Lookback um batch falha

Jun 9

Jun 10

Jun 11

Jun 12

Jun 13

Jun 14

Jun 15hoje

já carregado
batches desta execução
batch que falhou

Quando as colunas de um model mudam

Uma execução incremental não reconstrói a tabela, então uma lista de colunas alterada precisa de tratamento. A config on_schema_change decide o que acontece:

`on_schema_change`	Você adiciona uma coluna	Você remove uma coluna
`ignore`	Padrão. A nova coluna é descartada silenciosamente: ela nunca chega na tabela.	O `dbt run` falha.
`fail`	A execução falha com um erro de mudança de schema.	A execução falha com um erro de mudança de schema.
`append_new_columns`	A coluna é adicionada à tabela.	A coluna é mantida; ela não é removida.
`sync_all_columns`	A coluna é adicionada à tabela.	A coluna é removida da tabela (incluindo mudanças de tipo de dado).

Nenhum modo preenche a nova coluna nas linhas antigas: elas ficam NULL até um --full-refresh.

Padrões comuns

Receitas prontas para copiar e colar nas coisas que você faz toda semana.

Slim CI: builda só o que mudou desde a prod dbt build -s state:modified+ --defer --state path/to/prod
Build de produção, pulando unit tests e views não modificadas dbt build --exclude "test_type:unit state:unmodified,config.materialized:view" --state path/to/prod
Retomar depois de uma falha (pega o que falhou / foi pulado) dbt retry
Rebuildar os incremental models do zero dbt run --full-refresh -s config.materialized:incremental
Testar só o que você acabou de mexer dbt test -s state:modified+ --state path/to/prod
Visualizar o que um selector selecionaria (sem rodar) dbt list -s "tag:nightly,config.materialized:table"
Atualizar só o que tem dados de source mais recentes dbt source freshness && dbt build -s source_status:fresher+ --state path/
Deixe o Claude ou o Cursor operarem o seu projeto com segurança (veja dbt + AI) uvx dbt-mcp

Seleção de nós

O canto mais pesquisado no Google do dbt. Digite um selector abaixo e veja ele acender o DAG.

dbt run -s

selecionado não selecionado source

Especificando resources

A flag --select aceita um ou mais argumentos. Cada argumento pode ser um destes:

O nome de um package
O nome de um model
Um caminho totalmente qualificado para um diretório de models
Um método de seleção (path:, tag:, config:, test_type:, test_name: etc)

Exemplos:

$ dbt run --select my_dbt_project_nametodos os models do seu projeto
$ dbt run --select my_dbt_modelum model específico
$ dbt run --select path.to.my.modelstodos os models de um diretório específico
$ dbt run --select my_package.some_modelum model específico de um package específico
$ dbt run --select tag:nightlymodels com a tag “nightly”
$ dbt run --select path/to/modelsmodels contidos em path/to/models
$ dbt run --select path/to/my_model.sqlum model específico pelo seu caminho

Operadores de grafo

Operador plus (`+`)

$ dbt run --select my_model+seleciona my_model e todos os filhos
$ dbt run --select +my_modelseleciona my_model e todos os pais
$ dbt run --select +my_model+seleciona my_model e todos os seus pais e filhos

Operador N-plus

$ dbt run --select my_model+1seleciona my_model e os filhos de primeiro grau
$ dbt run --select 2+my_modelseleciona my_model, os pais de primeiro grau e os pais de segundo grau (os “avós”)
$ dbt run --select 3+my_model+4seleciona my_model, os pais até o 3º grau e os filhos até o 4º grau

Operador at (`@`)

$ dbt run -s @my_modelseleciona my_model, todos os seus descendentes e os ancestrais desses descendentes

Wildcards (*, ?, [abc]) funcionam dentro das strings de selector. Não são operadores de grafo. Use-os dentro de um nome ou de um method:value.

Exemplos de métodos

tag: dbt run -s "tag:nightly"
source: dbt run -s "source:snowplow+"
resource_type: dbt list -s "resource_type:test"
path: dbt run -s "models/staging/github"
package: dbt run -s "package:snowplow"
config.X: dbt run -s "config.materialized:incremental"
fqn: dbt run -s "fqn:my_project.marts.finance.fct_orders"
file: dbt run -s "file:fct_orders.sql"
semantic_model: dbt parse -s "semantic_model:orders"
saved_query: dbt sl list -s "saved_query:weekly_revenue"
test_type: dbt test -s "test_type:generic"
test_name: dbt test -s "test_name:unique"
state: dbt run -s "state:modified" --state path/to/artifacts
exposure: dbt run -s "+exposure:weekly_kpis"
metric: dbt build -s "+metric:weekly_active_users"
result: dbt run -s "result:error" --state path/to/artifacts
source_status: dbt build -s "source_status:fresher+"
group: dbt run -s "group:finance"
access: dbt list -s "access:public"
version: dbt list -s "version:latest"
unit_test: dbt list -s "unit_test:*"
selector 1.12+: dbt run -s "selector:nightly_marts"

Operadores de conjunto

Unions (separadas por espaço)

$ dbt run --select +snowplow_sessions +fct_ordersroda snowplow_sessions, todos os ancestrais de snowplow_sessions, fct_orders e todos os ancestrais de fct_orders

Intersections (separadas por vírgula)

$ dbt run --select +snowplow_sessions,+fct_ordersroda todos os ancestrais em comum de snowplow_sessions e fct_orders
$ dbt run --select marts.finance,tag:nightlyroda os models que estão no subdiretório marts/finance e têm a tag nightly

Excluindo models

O dbt oferece uma flag --exclude com a mesma semântica do --select. Os models indicados na flag --exclude são removidos do conjunto de models selecionado com --select.

Exemplo:

$ dbt run --select path:models/marts/finance --exclude fct_orders+os marts de finance, menos fct_orders e tudo que está downstream dele

State

Alguns métodos comparam o projeto com um manifest.json de outra execução (uma invocação anterior, ou produção), passado pela flag --state.

$ dbt build -s "state:modified+" --defer --state path/to/artifacts

Selectors

state:newausente do manifest de comparação
state:modifiednós novos, mais qualquer nó existente que mudou
state:unmodifiednós existentes sem mudanças
state:oldpresente no manifest de comparação

Restrinja state:modified a um tipo de mudança com sub-selectors: .body, .configs, .relation, .macros, .contract.

Defer

--defer permite buildar um model sem buildar os pais dele antes: um ref() para um pai não buildado resolve para o state de outro ambiente. Ele precisa do --state. Alterne os switches para ver onde o ref('model_b') de model_c resolve.

--defer model_b buildado em dev --favor-state

dbt build -s model_c

Sem --defer: ref('model_b') resolve para o seu schema de dev, onde model_b nunca foi buildado. model_c falha com um erro 'relation not found'.

dbt + AI · 2026

A parte que o cheat sheet original não podia ter: como o dbt funciona na era dos agentes.

dbt MCP server

Um servidor Model Context Protocol que permite que agentes de AI (Claude, Cursor, VS Code) operem o seu projeto dbt, com segurança e governança.

Rode localmente:

uvx dbt-mcpservidor local: acesso completo à dbt CLI

Grupos de ferramentas que ele expõe:

dbt CLI: run, build, test, compile, list, parse, show …
Discovery: get_model_details, get_lineage, get_model_health, get_mart_models …
Semantic Layer: list_metrics, query_metrics, get_dimensions …
SQL: execute_sql, text_to_sql
Admin API: trigger_job_run, list_jobs, retry_job_run …
Codegen: generate_model_yaml, generate_source, generate_staging_model

Também há um MCP server remoto (um endpoint por ambiente) para ferramentas de consumo de dados, sem nenhuma configuração local.

Agents e Copilot

Developer Agent: Escreve e refatora models, gera testes e valida mudanças a partir de linguagem natural dentro da Studio IDE.
Analyst Agent: Responde perguntas em linguagem natural com números governados, usando o dbt Semantic Layer.
dbt Copilot: Geração inline de SQL, models, testes e documentação com um clique.
dbt Canvas: Construção visual de models com arrastar e soltar. Governança e lineage mantidos automaticamente.
dbt Insights: Uma interface de queries com AI para explorar, validar e compartilhar resultados com consciência total de lineage.

Fusion engine

O engine do dbt, reescrito em Rust: o que muda quando o seu projeto roda nele.

O que o Fusion traz

Uma reescrita do zero do engine do dbt em Rust, entregue como um único binário (v2.0).

Compreensão de SQL: o Fusion realmente faz o parse do seu SQL, então pega erros de coluna e de tipo antes de uma execução.
Language server (LSP): go-to-definition, autocomplete e erros ao vivo no editor.
Mais rápido no parse / compile, com drivers ADBC nativos para o warehouse.
Adiciona os verbos de sessão environment, invocation, cancel, reattach.
Flags depreciadas foram removidas, com destaque para --models / -m → use --select.

dbt cheat sheet: a referência dbt interativa, atualizada para a era da AI