Back to tutorials

dbt compile Command: Usage & Examples


Welcome to this tutorial on the dbt compile command. dbt is a command-line tool that enables data analysts and engineers to transform data in their warehouses more effectively. The dbt compile command is a crucial part of this tool, and it’s used to generate executable SQL from source model, test, and analysis files.

Understanding the dbt compile Command

The dbt compile command takes your dbt project’s source files and generates executable SQL code. This code is stored in the target/ directory of your dbt project.

For example, if you have a model file orders.sql with the following content:

{{ config(materialized='view') }}

select * 
from raw_data.orders
where order_date >= '2023-01-01'

Running dbt compile will generate a SQL file in the target/ directory that might look something like this:

CREATE OR REPLACE VIEW analytics.orders AS

select * 
from raw_data.orders
where order_date >= '2023-01-01'

Use Cases for dbt compile

Inspecting Compiled Output

The dbt compile command is useful for visually inspecting the compiled output of model files. This is particularly useful for validating complex jinja logic or macro usage.

For example, if you have a model file customers.sql that uses a macro to calculate the lifetime value of a customer:

{{ config(materialized='table') }}

  {{ lifetime_value('order_total') }} as  lifetime_value

from raw_data.orders

Running dbt compile will allow you to see the actual SQL that gets generated and run against your database.

Manually Running Compiled SQL

While debugging a model or schema test, it’s often useful to execute the underlying select statement to find the source of the bug. dbt compile allows you to do this.

Compiling Analysis Files

dbt compile can also be used to compile analysis files. These are SQL files that allow you to perform ad-hoc analyses and explorations.

Common Misconceptions about dbt compile

Not a Prerequisite for dbt run

A common misconception is that dbt compile is a prerequisite for dbt run or other building commands. This is not the case. Those commands will handle compilation themselves.

Use dbt parse for Validation

If you just want dbt to read and validate your project code, without connecting to the data warehouse, use dbt parse instead of dbt compile.

Advanced Usage of dbt compile

The dbt compile command accesses the data platform to cache-related metadata and to run introspective queries.

You can use the --no-populate-cache flag to disable the initial cache population. If metadata is needed, it will be a cache miss, requiring dbt to run the metadata query.

You can also use the --no-introspect flag to disable introspective queries. If a model’s definition requires running an introspective query and this flag is used, dbt will raise an error.


In this tutorial, we’ve covered the basics of the dbt compile command, including what it does, how to use it, and some common misconceptions about it. We’ve also looked at some advanced usage options. With this knowledge, you should be able to use dbt compile effectively in your dbt projects.

database icon
The first SQL editor with built-in dbt Core ™
Simplified dbt development - Create and manage your dbt models and macros all in one place with PopSQL