Methods
Selector methods return all resources that share a common property, using the
syntax method:value
. While it is recommended to explicitly denote the method,
you can omit it (the default value will be one of path
, file
or fqn
).
The "tag" method
The tag:
method is used to select models that match a specified tag.
$ dbt run --select tag:nightly # run all models with the `nightly` tag
The "source" method
The source
method is used to select models that select from a specified source. Use in conjunction with the +
operator.
$ dbt run --select source:snowplow+ # run all models that select from Snowplow sources
The "resource_type" method
Use the resource_type
method to select nodes of a particular type (model
, test
, exposure
, and so on). This is similar to the --resource-type
flag used by the dbt ls
command.
$ dbt build --select resource_type:exposure # build all resources upstream of exposures
$ dbt list --select resource_type:test # list all tests in your project
Note: This method doesn't work for sources, so use the --resource-type
option of the list command instead:
$ dbt list --resource-type source
The "path" method
The path
method is used to select models/sources defined at or under a specific path.
Model definitions are in SQL/Python files (not YAML), and source definitions are in YAML files.
While the path
prefix is not explicitly required, it may be used to make
selectors unambiguous.
# These two selectors are equivalent
dbt run --select path:models/staging/github
dbt run --select models/staging/github
# These two selectors are equivalent
dbt run --select path:models/staging/github/stg_issues.sql
dbt run --select models/staging/github/stg_issues.sql
The "fqn" method
The fqn
method is used to select nodes based off their "fully qualified names" (FQN) within the dbt graph. The default output of dbt list
is a listing of FQN.
dbt run --select fqn:some_model
dbt run --select fqn:your_project.some_model
dbt run --select fqn:some_package.some_other_model
The "package" method
The package
method is used to select models defined within the root project
or an installed dbt package. While the package:
prefix is not explicitly required, it may be used to make
selectors unambiguous.
# These three selectors are equivalent
dbt run --select package:snowplow
dbt run --select snowplow
dbt run --select snowplow.*
The "config" method
The config
method is used to select models that match a specified node config.
$ dbt run --select config.materialized:incremental # run all models that are materialized incrementally
$ dbt run --select config.schema:audit # run all models that are created in the `audit` schema
$ dbt run --select config.cluster_by:geo_country # run all models clustered by `geo_country`
The "test_type" method
The test_type
method is used to select tests based on their type, singular
or generic
:
$ dbt test --select test_type:generic # run all generic tests
$ dbt test --select test_type:singular # run all singular tests
The "test_name" method
The test_name
method is used to select tests based on the name of the generic test
that defines it. For more information about how generic tests are defined, read about
tests.
$ dbt test --select test_name:unique # run all instances of the `unique` test
$ dbt test --select test_name:equality # run all instances of the `dbt_utils.equality` test
$ dbt test --select test_name:range_min_max # run all instances of a custom schema test defined in the local project, `range_min_max`
The "state" method
N.B. State-based selection is a powerful, complex feature. Read about known caveats and limitations to state comparison.
state:new
: There is no node with the same unique_id
in the comparison manifest
state:modified
: All new nodes, plus any changes to existing nodes.
$ dbt test --select state:new # run all tests on new models + and new tests on old models
$ dbt run --select state:modified # run all models that have been modified
$ dbt ls --select state:modified # list all modified nodes (not just models)
Because state comparison is complex, and everyone's project is different, dbt supports subselectors that include a subset of the full modified
criteria:
state:modified.body
: Changes to node body (e.g. model SQL, seed values)state:modified.configs
: Changes to any node configs, excludingdatabase
/schema
/alias
state:modified.relation
: Changes todatabase
/schema
/alias
(the database representation of this node), irrespective oftarget
values orgenerate_x_name
macrosstate:modified.persisted_descriptions
: Changes to relation- or column-leveldescription
, if and only ifpersist_docs
is enabled at each levelstate:modified.macros
: Changes to upstream macros (whether called directly or indirectly by another macro)state:modified.contract
: Changes to a model's contract, which currently include thename
anddata_type
ofcolumns
. Removing or changing the type of an existing column is considered a breaking change, and will raise an error.
Remember that state:modified
includes all of the criteria above, as well as some extra resource-specific criteria, such as modifying a source's freshness
or quoting
rules or an exposure's maturity
property. (View the source code for the full set of checks used when comparing sources, exposures, and executable nodes.)
The "exposure" method
The exposure
method is used to select parent resources of a specified exposure. Use in conjunction with the +
operator.
$ dbt run --select +exposure:weekly_kpis # run all models that feed into the weekly_kpis exposure
$ dbt test --select +exposure:* # test all resources upstream of all exposures
$ dbt ls --select +exposure:* --resource-type source # list all sources upstream of all exposures
The "metric" method
The metric
method is used to select parent resources of a specified metric. Use in conjunction with the +
operator.
$ dbt build --select +metric:weekly_active_users # build all resources upstream of weekly_active_users metric
$ dbt ls --select +metric:* --resource-type source # list all source tables upstream of all metrics
The "result" method
The result
method is related to the state
method described above and can be used to select resources based on their result status from a prior run. Note that one of the dbt commands [run
, test
, build
, seed
] must have been performed in order to create the result on which a result selector operates. You can use result
selectors in conjunction with the +
operator.
$ dbt run --select result:error --state path/to/artifacts # run all models that generated errors on the prior invocation of dbt run
$ dbt test --select result:fail --state path/to/artifacts # run all tests that failed on the prior invocation of dbt test
$ dbt build --select 1+result:fail --state path/to/artifacts # run all the models associated with failed tests from the prior invocation of dbt build
$ dbt seed --select result:error --state path/to/artifacts # run all seeds that generated errors on the prior invocation of dbt seed.
The "source_status" method
Supported in v1.1 or higher.
Another element of job state is the source_status
of a prior dbt invocation. After executing dbt source freshness
, for example, dbt creates the sources.json
artifact which contains execution times and max_loaded_at
dates for dbt sources. You can read more about sources.json
on the 'sources' page.
The following dbt commands produce sources.json
artifacts whose results can be referenced in subsequent dbt invocations:
dbt source freshness
After issuing one of the above commands, you can reference the source freshness results by adding a selector to a subsequent command as follows: