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 modelos (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 modelo 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 modelos incrementais 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 modelos 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 modelos 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 modelo 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.

Quando as colunas de um modelo 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.

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

Snapshots

Histórico SCD tipo 2 para sources que você não controla. Cada execução versiona as linhas que mudaram, então você consegue consultar como elas estavam em qualquer data passada.

Estratégias

Duas formas de detectar que uma linha da source mudou.

timestamp: Compara uma coluna updated_at com a última execução do snapshot. Barato e rápido, mas perde mudanças silenciosamente quando a source esquece de atualizar essa coluna.
check: Faz hash de uma lista de check_cols e compara. Pega as mudanças independente do updated_at. Use quando a source não tem um timestamp confiável.

Um snapshot adiciona dbt_valid_from e dbt_valid_to em toda linha. Quando o dbt detecta uma mudança, ele fecha a versão anterior (define dbt_valid_to) e insere uma nova. O status da row 2 acabou de mudar de trial para active; alterne se o updated_at também avançou para ver o que cada estratégia pega.

Dados de snapshot vivem para sempre. Trate snapshots como histórico imutável: fazer backfill ou restate depois é doloroso.

Padrões comuns

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

Retomar depois de uma falha (pega o que falhou / foi pulado) dbt retry
Visualizar o que um selector selecionaria (sem rodar) dbt list -s "tag:nightly,config.materialized:table"
Testar só o que você acabou de mexer dbt test -s state:modified+ --state path/to/prod
Rebuildar os modelos incrementais do zero dbt run --full-refresh -s config.materialized:incremental
Atualizar só o que tem dados de source mais recentes dbt source freshness && dbt build -s source_status:fresher+ --state path/
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

Slim CI, visualizado

--select state:modified+ seleciona os nós modificados e os descendentes deles; o --defer diz ao dbt para resolver todo ref() não selecionado contra o manifest de prod. Escolha um modelo que você imagina ter mudado no seu PR.

Modificado neste PR:

dbt build -s state:modified+ --defer --state path/to/prod

O slim CI economiza tempo e gasto de warehouse pulando os modelos que o PR não tocou. Pré-requisito: um manifest.json de uma execução recente de prod, passado via --state.

Builds por source freshness

O dbt source freshness registra quais sources receberam dados novos; o --select source_status:fresher+ então roda todo model downstream delas, e somente esses. Alterne quais sources chegaram frescas.

orders tem dados novos events tem dados novos users tem dados novos

dbt source freshness && dbt build -s source_status:fresher+ --state path/to/prod

Combine com um job noturno para rodar só os marts cujo upstream realmente mudou. Compara contra o sources.json da execução anterior via --state.

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 modelo
Um caminho totalmente qualificado para um diretório de modelos
Um método de seleção (path:, tag:, config:, test_type:, test_name: etc)

Exemplos:

$ dbt run --select my_dbt_project_nametodos os modelos do seu projeto
$ dbt run --select my_dbt_modelum modelo específico
$ dbt run --select path.to.my.modelstodos os modelos de um diretório específico
$ dbt run --select my_package.some_modelum modelo específico de um package específico
$ dbt run --select tag:nightlymodelos com a tag “nightly”
$ dbt run --select path/to/modelsmodelos contidos em path/to/models
$ dbt run --select path/to/my_model.sqlum modelo 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 modelos que estão no subdiretório marts/finance e têm a tag nightly

Excluindo modelos

O dbt oferece uma flag --exclude com a mesma semântica do --select. Os modelos 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 modelo 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.

dbt agent skills

Instruções e scripts curados que o seu coding agent carrega sob demanda. Disponíveis prontos em Claude Code, Cursor e VS Code através do plugin dbt-labs/dbt-agent-skills.

Analytics engineering: Cria e modifica modelos, escreve testes, debuga erros e explora sources.
Semantic Layer: Cria modelos semânticos, métricas e dimensões com o MetricFlow.
Unit tests: Adiciona unit tests contra inputs mockados e outputs esperados; pratica TDD.
NL questions: Responde perguntas de negócio via Semantic Layer ou SQL ad-hoc.
dbt Mesh: Implementa contracts, access, groups e versions; refs cross-project.
MCP setup: Configura o dbt MCP server para Claude Code, Cursor ou VS Code.

Agents e Copilot

Estes recursos fazem parte do dbt Platform.

Developer Agent: Escreve e refatora modelos, 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, modelos, testes e documentação com um clique, dentro da Studio IDE.

Fusion engine

O runtime do dbt, reescrito em Rust e agora aberto dentro do dbt Core: o que muda quando o seu projeto roda nele.

O que o Fusion traz

Uma reescrita do zero do runtime do dbt em Rust. A partir do v2.0 ele é open source (Apache 2.0) e a base do dbt Core; o Fusion é a distribuição que adiciona recursos premium por cima.

Compreensão de SQL: o Fusion faz análise estática do seu projeto. No modo baseline (o padrão) ele pega erros de sintaxe antes de uma execução; no modo strict ele também valida tipos de coluna, então um typo como select non_existent_col falha no compile.
Suporte no editor: a extensão do dbt para VS Code te dá autocomplete, go-to-definition, erros inline e preview ao vivo de CTEs, tudo movido pelo language server do Fusion.
Mais rápido: um binário em Rust mais drivers ADBC nativos para o warehouse, com a dbt Labs citando parse até 10x mais rápido nos maiores projetos.
Unit tests rodam primeiro: o dbt build roda todos os unit tests antes de buildar o DAG, em vez de intercalá-los pela lineage.
Flags depreciadas removidas: com destaque para --models / -m; use --select.
Open source, a partir do v2.0: o runtime em Rust agora é Apache 2.0 e a base do dbt Core (pip install dbt-core, em alpha). Três distribuições coexistem: dbt Core v1 (Python), dbt Core v2 (Rust, OSS) e o Fusion (Rust, o superset proprietário que adiciona column-level lineage e um SQL linter nativo).

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