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, --inline
freshness	--select, --exclude, --selector
build	--select, --exclude, --selector, --resource-type, --defer
docs generate	--select, --exclude, --selector

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).

The --select and --selector arguments are similar in that they both allow you to select resources. To understand the difference, see Differences between --select and --selector.

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.

To follow POSIX standards and make things easier to understand, we recommend CLI users use quotes when passing arguments to the --select or --exclude option (including single or multiple space-delimited, or comma-delimited arguments). Not using quotes might not work reliably on all operating systems, terminals, and user interfaces. For example, dbt run --select "my_dbt_project_name" runs all models in your project.

How does selection work?

1. 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).

2. 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.)

3. 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 for dbt run, only tests for dbt 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.

Examples of select flag

The --select flag accepts one or more arguments. Each argument can be one of:

1. a package name
2. a model name
3. a fully-qualified path to a directory of models
4. a selection method (path:, tag:, config:, test_type:, test_name:)

Examples:

dbt run --select "my_dbt_project_name"   # runs all models in your project
dbt run --select "my_dbt_model"          # runs a specific model
dbt run --select "path/to/my/models"     # runs all models in a specific directory
dbt run --select "my_package.some_model" # run a specific model in a specific package
dbt run --select "tag:nightly"           # run models with the "nightly" tag
dbt run --select "path/to/models"        # run models contained in path/to/models
dbt run --select "path/to/my_model.sql"  # run a specific model by its path

Examples of subsets of nodes

dbt supports a shorthand language for defining subsets of nodes. This language uses the following characters:

• plus operator (+)
• at operator (@)
• asterisk operator (*)
• comma operator (,)

Examples:

# multiple arguments can be provided to --select
dbt run --select "my_first_model my_second_model"

# select my_model and all of its children
dbt run --select "my_model+"     

# select my_model, its children, and the parents of its children
dbt run --models @my_model          

# these arguments can be projects, models, directory paths, tags, or sources
dbt run --select "tag:nightly my_model finance.base.*"

# use methods and intersections for more complex selectors
dbt run --select "path:marts/finance,tag:nightly,config.materialized:table"

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.

The --select and --selector arguments are similar in that they both allow you to select resources. To understand the difference between --select and --selector arguments, see this section for more details.

Troubleshoot with the ls command

Constructing and debugging your selection syntax can be challenging. To get a "preview" of what will be selected, we recommend using the list command. This command, when combined with your selection syntax, will output a list of the nodes that meet that selection criteria. The dbt ls command supports all types of selection syntax arguments, for example:

dbt ls --select "path/to/my/models" # Lists all models in a specific directory.
dbt ls --select "source_status:fresher+" # Shows sources updated since the last dbt source freshness run.
dbt ls --select state:modified+ # Displays nodes modified in comparison to a previous state.
dbt ls --select "result:<status>+" state:modified+ --state ./<dbt-artifact-path> # Lists nodes that match certain result statuses and are modified.

Questions from the Community

Ask the Community