The following commands are available from the command line to interact with dbt.
dbt init [project_name] performs several actions necessary to create a new dbt project:
- creates a new folder at
- generates directories and sample files necessary to get started with dbt
dbt run executes compiled sql model files against the current
target database. dbt connects to the target database and runs the relevant SQL required to materialize all data models using the specified materialization strategies. Models are run in the order defined by the dependency graph generated during compilation. Intelligent multi-threading is used to minimize execution time without violating dependencies.
Deploying new models frequently involves destroying prior versions of these models. In these cases,
dbt run minimizes the amount of time in which a model is unavailable by first building each model with a temporary name, then dropping the existing model, then renaming the model to its correct name. The drop and rename happen within a single database transaction for database adapters that support transactions.
Specifying models to run
dbt run will execute all of the models in the dependency graph. During development (and deployment), it is useful to specify only a subset of models to run. Use the
--models flag with
dbt run to select a subset of models to run. Note that the following arguments (
--exclude) also apply to
--models flag accepts one or more arguments. Each argument can be one of:
1. a package name
2. a model name
3. a path hierarchy to a models directory
dbt run --models my_dbt_project_name # runs all models in your project dbt run --models my_dbt_model # runs a specific model dbt run --models path.to.my.models # runs all models in a specific directory dbt run --models my_package.some_model # run a specific model in a specific package # multiple arguments can be provided to --models dbt run --models my_project other_project # these arguments can be projects, models, or directory paths dbt run --models my_project path.to.models a_specific_model
Additionally, arguments to
--models can be modified with the
* operators. If placed at the front of the model specifier,
+ will select all parents of the selected model(s). If placed at the end,
+ will select all children of the selected models. The
* operator matches all models within a package or directory.
dbt run --models my_model+ # select my_model and all children dbt run --models +my_model # select my_model and all parents dbt run --models my_package.* # select all models in my_package dbt run --models path.to.models.* # select all models in path/to/models dbt run --models my_package.*+ # select all models in my_package and their children dbt run --models +some_model+ # select some_model and all parents and children
Finally, dbt provides an
--exclude flag with the same semantics as
--models. Models specified with the
--exclude flag will be removed from the set of models selected with
dbt run --models my_package.*+ --exclude my_package.a_big_model+
Run dbt non-destructively
If you provide the
--non-destructive argument to
dbt run, dbt will minimize the amount of destructive changes it runs against your database. Specifically, dbt
- Ignore models materialized as
- Truncate tables and re-insert data instead of dropping and re-creating these tables
This flag is useful for recurring jobs which only need to update table models and incremental models. DBT will not create, drop, or modify views if the
--non-destructive flag is provided.
dbt run --non-destructive
Refresh incremental models
If you provide the
--full-refresh argument to
dbt run, dbt will treat incremental models as table models. This is useful when
- The schema of an incremental model changes and you need to recreate it
- You want to reprocess the entirety of the incremental model because of new logic in the model code
dbt run --full-refresh
dbt test runs tests on data in deployed models. There are two types of tests:
- schema validations, declared in a
- custom data tests, written as SQL
dbt test runs both types of test and reports the results to the console.
The tests to run can be selected using the
--models flag discussed here
dbt test --models one_specific_model # run tests for one_specific_model dbt test --models some_package.* # run tests for all models in package
Model validation is discussed in more detail here.
dbt archive records snapshots of specified tables so that you can analyze how tables change over time. See here for more information.
dbt deps pulls the most recent version of the dependencies listed in your
dbt_project.yml from git. See here for more information on dependencies.
dbt debug is a utility function to show debug information.
dbt clean is a utility function that deletes all compiled files in the
dbt --version is a utility function to check the version of your installed dbt client.