Syntax overview
dbt's node selection syntax makes it possible to run only specific resources in a given invocation of dbt. This selection syntax is used for the following subcommands:
command | argument(s) |
---|---|
run | --select , --exclude , --selector , --defer |
test | --select , --exclude , --selector , --defer |
seed | --select , --exclude , --selector |
snapshot | --select , --exclude --selector |
ls (list) | --select , --exclude , --selector , --resource-type |
compile | --select , --exclude , --selector |
freshness | --select , --exclude , --selector |
build | --select , --exclude , --selector , --resource-type , --defer |
Nodes and resources
We use the terms "nodes" and "resources" interchangeably. These encompass all the models, tests, sources, seeds, snapshots, exposures, and analyses in your project. They are the objects that make up dbt's DAG (directed acyclic graph).
Specifying resourcesβ
By default, dbt run
executes all of the models in the dependency graph; dbt seed
creates all seeds, dbt snapshot
performs every snapshot. The --select
flag is used to specify a subset of nodes to execute.
info
Before dbt v0.21, certain commands (notably run
, test
, and compile
) used a flag called --models
instead of --select
. The two were functionally identical. Those commands still support the --models
flag for backwards compatibility.
How does selection work?β
dbt gathers all the resources that are matched by one or more of the
--select
criteria, in the order of selection methods (e.g.tag:
), then graph operators (e.g.+
), then finally set operators (unions, intersections, exclusions).The selected resources may be models, sources, seeds, snapshots, tests. (Tests can also be selected "indirectly" via their parents; see test selection examples for details.)
dbt now has a list of still-selected resources of varying types. As a final step, it tosses away any resource that does not match the resource type of the current task. (Only seeds are kept for
dbt seed
, only models fordbt run
, only tests fordbt test
, and so on.)
Shorthandβ
Select resources to build (run, test, seed, snapshot) or check freshness: --select
, -s
Examplesβ
By default, 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 --select
flag with dbt run
to select a subset of models to run. Note that the following arguments (--select
, --exclude
, and --selector
) also apply to other dbt tasks, such as test
and build
.
The --select
flag accepts one or more arguments. Each argument can be one of:
- a package name
- a model name
- a fully-qualified path to a directory of models
- a selection method (
path:
,tag:
,config:
,test_type:
,test_name:
)
Examples:
dbt supports a shorthand language for defining subsets of nodes. This language uses the characters +
, @
, *
, and ,
.
As your selection logic gets more complex, and becomes unwieldly to type out as command-line arguments,
consider using a yaml selector. You can use a predefined definition with the --selector
flag.
Note that when you're using --selector
, most other flags (namely --select
and --exclude
) will be ignored.