What you will be able to do
- Preview a model, a failing test or an inline query with
dbt show, and explain what it does and doesn't read - Use
--limit,--inlineand--output jsonappropriately - Tell apart
dbt docs generate,dbt docs serveand the--write-catalogflag
1.dbt show compiles and previews a single node
Sometimes you need to see what a query returns without rebuilding anything. dbt show compiles the dbt-SQL of one model, test or analysis, or an ad-hoc query passed with --inline. It runs the query against the warehouse and prints the result in the terminal. Only one node can be selected: selector methods and graph operators that would pick several nodes are not used. Python models are not supported.
dbt show --select "stg_orders"
21:17:38 Running with dbt=1.5.0-b5
21:17:38 Found 5 models, 20 tests, 0 snapshots, 0 analyses, 425 macros, 0 operations, 3 seed files, 0 sources, 0 exposures, 0 metrics, 0 groups
21:17:38
21:17:38 Concurrency: 24 threads (target='dev')
21:17:38
21:17:38 Previewing node 'stg_orders' :
| order_id | customer_id | order_date | status |
|----------+-------------+------------+-------- |
| 1 | 1 | 2023-01-01 | returned |
| 2 | 3 | 2023-01-02 | completed |
| 3 | 94 | 2023-01-03 | completed |
| 4 | 50 | 2023-01-04 | completed |
| 5 | 64 | 2023-01-05 | completed |Two behaviours surprise people. First, previewing a model always compiles its query from source and runs that. It never selects from the table already built in the warehouse, even right after dbt run. The preview therefore shows what your current code returns, which may differ from the table in the warehouse.
Second, five rows is only the default, and --limit n does more than trim the display. dbt wraps the model's query in a subquery or CTE and adds a SQL limit n, so the warehouse only processes and returns that many rows. That is what keeps previews of large models fast.
Checkpoint 1 of 4· Check yourself
You ran dbt run on fct_orders yesterday and edited its SQL this morning without rerunning it. What does dbt show --select "fct_orders" preview?
dbt show always compiles the model from source and runs that query. It never reads the table that already exists in the warehouse.
“It will not select from the already-materialized database relation, even if you've just run the model.”Source: docs.getdbt.com
Sources1
2.Debugging test failures and ad-hoc queries with dbt show
dbt show is also the quickest way to see why a test failed. After a dbt build reports a failing unique test, select that test by name. The preview shows the offending rows: here, the duplicated value and how many times it appears.
$ dbt show -s "unique_my_model_with_duplicates_id"
13:22:53 Running with dbt=1.5.0
13:22:53 Found 4 models, 2 tests, 0 snapshots, 0 analyses, 309 macros, 0 operations, 0 seed files, 0 sources, 0 exposures, 0 metrics, 0 groups
13:22:53
13:22:53 Concurrency: 5 threads (target='dev')
13:22:53
13:22:53 Previewing node 'unique_my_model_with_duplicates_id':
| unique_field | n_records |
| ------------ | --------- |
| 1 | 2 |--inline runs any SQL you pass it, Jinja such as ref() included. That freedom has a cost: dbt can't guarantee the query won't modify the warehouse. To rule out changes, run it under a profile or role with read-only permissions, which are managed in the warehouse itself, for example --profile my-read-only-profile. Previews of a selected node only appear in dbt's logs and the terminal. They aren't built in the warehouse or stored in any dbt file.
For scripts and automation, --output json returns the preview as JSON instead of the human-readable table. Add --log-format json as well to make the whole terminal output, logs included, machine-readable.
Checkpoint 2 of 4· Check yourself
An analyst wants to run ad-hoc queries through dbt show --inline and must not be able to change any data. What guarantees that?
With --inline, dbt can't make sure the SQL won't modify the warehouse. Only read-only permissions, managed in the warehouse, guarantee it.
“To ensure no changes are made, use a profile or role with read-only permissions”Source: docs.getdbt.com
Checkpoint 3 of 4· Exam question
Within a single `dbt build` invocation, a `not_null` test with default severity fails on `stg_orders`. Which of the following statements correctly describe what happens next in that run? (Select all that apply.)(Select 3)
Correct answers: A, B, C — Every model that references `stg_orders` downstream in the DAG is marked SKIPPED for the remainder of the invocation.; The build process marks the failing test as an error, then continues building DAG branches unrelated to `stg_orders`.; Changing the test's `severity` to `warn` before the next run lets downstream models build even though the same condition still fails.
- A. With default severity, a failing test blocks the DAG: dbt marks every node downstream of `stg_orders` as SKIPPED rather than attempting to build them against data that failed validation. This is the core failure-propagation behavior `dbt build` uses to protect downstream models.
- B. `dbt build` processes the DAG node by node rather than stopping the whole run, so branches that do not depend on `stg_orders` continue to build normally while the failure is recorded against the affected branch. This lets unrelated parts of the project finish even when one path fails.
- C. Severity is a test-level setting that changes whether a failure blocks the run: setting it to `warn` reports the same failing condition without causing downstream nodes to skip, so those models build even though the underlying data issue persists. This is the documented workaround for unblocking a build without fixing the data.
- D. dbt does not automatically retry a failed test within the same invocation; a test either passes or fails once per run, and any retry requires rerunning the command (or using `dbt retry`) afterward. There is no built-in three-attempt retry policy for test failures.
- E. A single node failure does not halt the entire invocation — `dbt build` continues processing the rest of the DAG, only skipping the nodes that actually depend on the failed resource. Stopping everything would defeat the purpose of building independent branches in one pass.
- F. `on_error: continue` is a model-level config that lets downstream models keep running after an upstream model error, not a test-level setting, and it does not touch seed-loading behavior at all. It has no effect on whether a failing test blocks its downstream dependents.
Sources1
3.dbt docs generate builds the site; dbt docs serve previews it
Documentation has its own pair of commands. dbt docs generate compiles the project, writes the index and exports a documentation site in one step. dbt docs serve previews that site locally, and generates it first if it is missing or older than the index. By default the site goes into target/, with index.html and an assets/ folder. --output-dir writes a self-contained copy somewhere else. Because the site is just static files, any static file host can serve it, such as S3, GitHub Pages or Netlify.
Building the browsable site is a different job from producing metadata. The --write-catalog flag, accepted by dbt build, dbt run, dbt parse and dbt compile, writes catalog.json. That file holds metadata about the tables and views your models produce. The flag doesn't build a documentation site.
| Aspect | --write-catalog flag | dbt docs generate command |
|---|---|---|
| What it produces | catalog.json, plus the artifacts the command already generates | index.html, assets/, and the index files |
| What it's for | Metadata for Catalog and the metadata APIs | A static site you can preview with dbt docs serve or host anywhere |
In the dbt platform, the self-hosted site is replaced by Catalog, which job runs keep up to date. If a job includes dbt docs generate as a step, dbt runs dbt compile --write-catalog instead and points you to Catalog. No index.html is produced.
Checkpoint 4 of 4· Match them up
Match each docs command or flag to what it does.
Tap a term, then the definition that fits it.
generate builds the site and serve previews it. --write-catalog only produces metadata, and --output-dir moves the generated site to another directory.
“Both write artifacts, but only dbt docs generate builds a documentation site you can view in a browser.”Source: docs.getdbt.com
Sources2
Exam traps
Each one states something that sounds right. Open it to see what is actually true.
1.
dbt showreads the table thatdbt runlast built, so it is a cheap way to inspect warehouse contents.Why is that wrong?dbt showcompiles the model from source and runs that query every time. It never selects from the existing table.Covered in dbt show compiles and previews a single node
2.
--limitonly changes how many rows dbt prints; the warehouse still processes the full query.Why is that wrong?--limitadds a SQL limit to the query itself, so the warehouse only processes and returns that many rows.Covered in dbt show compiles and previews a single node
Sources
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.https://docs.getdbt.com/reference/commands/showOfficial docs
“Only selecting a single node is supported.”
↩︎ dbt show compiles and previews a single node“dbt show does not support Python (dbt-py) models.”
↩︎ dbt show compiles and previews a single node“By default, dbt show will display the first 5 rows from the query result.”
↩︎ dbt show compiles and previews a single node“The --limit flag modifies the underlying SQL and not just the number of rows displayed.”
↩︎ dbt show compiles and previews a single node“you can quickly preview the test failures right in the terminal, to find values of id that are duplicated”
↩︎ Debugging test failures and ad-hoc queries with dbt show“The --inline flags enables you to run ad-hoc SQL, which means dbt can't ensure the query doesn't modify the data warehouse.”
↩︎ Debugging test failures and ad-hoc queries with dbt show“The --output json flag returns dbt show results in JSON format instead of the default human-readable output”
↩︎ Debugging test failures and ad-hoc queries with dbt show“If previewing a model, dbt will always compile and run the compiled query from source.”
↩︎ Exam trap 1“The --limit flag modifies the underlying SQL and not just the number of rows displayed.”
↩︎ Exam trap 2“It will not select from the already-materialized database relation, even if you've just run the model.”
↩︎ Checkpoint“To ensure no changes are made, use a profile or role with read-only permissions”
↩︎ Checkpoint - 2.https://docs.getdbt.com/reference/commands/cmd-docsOfficial docs
“Run dbt docs generate to build the site, then dbt docs serve to preview it.”
↩︎ dbt docs generate builds the site; dbt docs serve previews it“Use --output-dir to write a self-contained copy of the site to a different directory”
↩︎ dbt docs generate builds the site; dbt docs serve previews it“It focuses solely on metadata hydration and does not build the documentation site”
↩︎ dbt docs generate builds the site; dbt docs serve previews it“If you add dbt docs generate as a job step, dbt automatically runs dbt compile --write-catalog instead and directs you to Catalog.”
↩︎ dbt docs generate builds the site; dbt docs serve previews it“Both write artifacts, but only dbt docs generate builds a documentation site you can view in a browser.”
↩︎ Checkpoint