Skip to content
Tutorials Center
My learning

Topics

Lesson 3 of 41 ยท Getting Started

Your First dbt Run

Write your first two dbt models, run them with dbt run, see how dbt compiles SQL into the target folder, and reproduce the generated CREATE VIEW statements here.

Time to build something. In this lesson you write two small models, run them, and look at what dbt actually sends to the warehouse. The commands are read-only on this site, but the SQL in every model runs here in a sample shop database, so you can check each result.

Our sample warehouse already contains raw tables, the way a loading tool would leave them: customers, orders, order_items, products and categories. Think of them as the raw layer: messy names, no business logic. Your job is to build clean models on top.

Step 1: write a model

Create the file models/stg_customers.sql. The file name (without .sql) becomes the model name, and so the name of the view or table that is created.

SQL
select
    id as customer_id,
    first_name || ' ' || last_name as full_name,
    lower(email) as email,
    city,
    country
from customers

For a real project the raw table would be referenced with a source, which you will learn in Sources. For now we use the plain table name.

Now a second model, models/customer_orders.sql, that depends on the first one:

SQL
select
    c.customer_id,
    c.full_name,
    count(o.id) as order_count
from {{ ref('stg_customers') }} as c
left join orders as o on o.customer_id = c.customer_id
group by c.customer_id, c.full_name

The {{ ref('stg_customers') }} is the dependency. It means "build stg_customers first, then use whatever it is called in this environment".

Step 2: run it

Terminal
dbt run

dbt prints one line per model, with timing:

TEXT
1 of 2 START sql view model analytics.stg_customers ........ [RUN]
1 of 2 OK created sql view model analytics.stg_customers ... [CREATE VIEW in 0.12s]
2 of 2 START sql view model analytics.customer_orders ...... [RUN]
2 of 2 OK created sql view model analytics.customer_orders . [CREATE VIEW in 0.09s]

Done. PASS=2 WARN=0 ERROR=0 SKIP=0 TOTAL=2

Because we set no configuration, both models are built as views (the default materialization). The order of the lines follows the dependency: stg_customers first, customer_orders second.

What dbt really ran

dbt did not run your SELECT as it is. It wrapped it. For the first model the statement sent to the warehouse was essentially this. Run it here to reproduce the build, then query the new view:

SQL Reproducing the first model build ยท database: shop

Press Run (or Ctrl + Enter) to see the result here.

The second model had its ref replaced by the real view name. Running both statements in order is exactly what dbt's two lines did:

SQL Reproducing the second model build ยท database: shop

Press Run (or Ctrl + Enter) to see the result here.

In a real warehouse, the view would be named analytics.customer_orders, where analytics is the schema from your profile. In your own dev schema it might be dbt_maria.customer_orders, so two people can run the project at once without colliding.

The target folder

After a run, look inside the target/ directory that dbt created in your project:

TEXT
target/
โ”œโ”€โ”€ compiled/shop_analytics/models/customer_orders.sql
โ”œโ”€โ”€ run/shop_analytics/models/customer_orders.sql
โ”œโ”€โ”€ manifest.json
โ”œโ”€โ”€ run_results.json
โ””โ”€โ”€ catalog.json        (after dbt docs generate)
  • compiled/ holds your model after Jinja was rendered, so ref is a real table name. It is a plain SELECT, handy for copying into a SQL editor to debug.
  • run/ holds the exact statement executed, including the CREATE VIEW ... AS wrapper.
  • manifest.json describes the whole project: every node, its dependencies, its config.
  • run_results.json records the status and timing of the last command.

You never edit anything in target/. It is rebuilt on every run, and normally listed in .gitignore together with dbt_packages/ and logs/.

Stand-in: compile versus run

The difference between "compiled" and "run" SQL is a small string operation. This Python stand-in (real Jinja, simplified dbt) shows both forms for the second model:

Python Stand-in: compiled vs run SQL

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Useful variations

Terminal
dbt run --select customer_orders      # only one model
dbt run --select +customer_orders     # the model and everything it depends on
dbt run --full-refresh                # rebuild tables that are normally incremental
dbt compile                           # render SQL into target/ without running it

If a model has an error (a typo in a column), dbt marks it as ERROR, shows the database message, and skips every model that depends on it, while models that do not depend on it still finish. Fix the SQL and run again. Node selection is covered fully in Selecting Nodes.

Common mistakes

  • A trailing semicolon in the model. Remove it. dbt wraps your SELECT in other SQL, and a ; inside breaks it.
  • Naming a model like a raw table. If a model is called customers and a raw table has the same name, ref and plain SQL become confusing. Prefix staging models with stg_.
  • Editing target/ files. They are overwritten on every run.
  • Forgetting that models are not tables by default. A view recomputes on every query. We study when to switch in Materializations.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What determines the name of the object dbt creates for a model?

    The model name is the file name without .sql, and it becomes the view or table name.
  2. 2. What is the default materialization when you configure nothing?

    dbt builds views unless you configure something else.
  3. 3. Which folder contains the SQL after Jinja has been rendered but before the CREATE wrapper is added?

    target/compiled has the rendered SELECT, and target/run has the full statement that was actually executed.
  4. 4. A model fails with an error. What happens to models that depend on it?

    dbt skips downstream models of a failed model and reports them as SKIP.

Summary

  • A model is a .sql file with one SELECT; its file name is the object name.
  • dbt run wraps each model in CREATE VIEW (the default) or CREATE TABLE and runs them in dependency order.
  • ref() is replaced with the real name, and target/compiled and target/run show the results.
  • A failed model causes its dependents to be skipped.

Next: The dbt Command Line