Methods

Selector methods allow you to filter resources based on specific properties using the method:value syntax. While it's advisable to explicitly denote the method, you can omit it, and the default will be one of path, file, or fqn.

Most selector methods below support unix-style wildcards:

Wildcard	Description	Example
*	matches any number of characters (including none)	dbt list --select "*.folder_name.*"
?	matches any single character	dbt list --select "model_?.sql"
[abc]	matches one character listed in the bracket	dbt list --select "model_[abc].sql"
[a-z]	matches one character from the specified range in the bracket	dbt list --select "model_[a-z].sql"

Below are examples of several popular selector methods:

"tag" Method

Use the tag: method select models with a specified tag.

# Run all models with the 'hourly' tag
dbt run --select "tag:hourly"    

"source" Method

Use the source: method to select models that reference a specified source.

# Runs all models that reference the fivetran source
dbt run --select "source:fivetran+"

"resource_type" method

Use the resource_type method to select nodes of a specific type (ex. model, test, exposure, etc.)

# Runs all models and tasks related to exposures
dbt run --select "resource_type:exposure"  

# Lists all tests in your project
dbt list --select "resource_type:test"  

"path" method

Use path method to select models/sources defined at or under a specific path.

# Runs all models in the "models/marts" path
dbt run --select "path:models/marts"

# Runs a specific model, "customers.sql", in the "models/marts" path. 
dbt run --select "path:models/marts/customers.sql"

"file" method

Use file method to select a model by filename.

# Runs the model defined in 'model_name.sql'
dbt run --select "file:model_name.sql"

# Note: Adding the file extension (e.g., ".sql") is optional.
dbt run --select "file:model_name"

"fqn" method

Use 'fqn' to select nodes based off their "fully qualified name" (FQN). The default FQM format includes the dbt project name, subdirectories, and the file name

# Runs the model named 'example_model'
dbt run --select "fqn:example_model"

# Runs the model 'model_one' in 'example_model'
dbt run --select "fqn:project_name.example_model"

# Runs 'example_model' in 'package_name'
dbt run --select "fqn:package_name.example_model"

# Runs 'example_model' in 'example_path'
dbt run --select "fqn:example_path.example_model"

# Runs 'example_model' in 'example_path' within 'project_name'
dbt run --select "fqn:project_name.example_path.example_model"

"package" method

Use package method to select models defined within the root project or an installed dbt package.

# Runs all models in the 'fivetran' package
dbt run --select "package:fivetran"

# Note: Adding "package" prefix is optional. The following commands are equivalent:
dbt run --select "fivetran"
dbt run --select "fivetran.*"

"config" method

Use config to select models that match a specified node config.

# Runs all models that are materialized as tables
dbt run --select "config.materialized:table"

# Runs all models that are created in the 'stagins' schema
dbt run --select "config.schema:staging"

# Runs all models clustered by 'zip_code'
dbt run --select "config.cluster_by:zip_code"

Note: config method work for non-string values, such as: booleans, dictionary keys, values in arrays, etc.

Suppose you have a model with the following configurations:

{{ config(
  materialized = 'view',
  unique_key = ['customer_id', 'order_id'],
  grants = {'insert': ['sales_team', 'marketing_team']},
  transient = false
) }}

select ...

You can use config method to select the following:

# Lists all models materialized as views
dbt ls -s config.materialized:view

# Lists all models with 'customer_id' as a unique key
dbt ls -s config.unique_key:customer_id

# Lists all models with insert grants for the sales team
dbt ls -s config.grants.insert:sales_team

# Lists all models that are not transient
dbt ls -s config.transient:false

"test_type" method

Use test_type to select tests based on type (singular or generic)

# Runs all generic tests
dbt test --select "test_type:generic"

# Runs all singular tests
dbt test --select "test_type:singular"

"test_name" method

Use test_name method to select tests based on the name of the test defined.

# Runs all instances of the 'not null' test
dbt test --select "test_name:not null"

# Runs all instances of the 'dbt_utils.not_accepted_values' test
dbt test --select "test_name:not_accepted_values"

"state" method

When using the "state" method in a Bolt schedule of type Deferred or Turbo-CI, you don't need to pass the --state path/to/project/artifacts to your dbt command.

Paradime will point to the artifacts based on the Bolt schedule configurations:

• Deferred schedule

• Last run type

Note: State-based selection is a powerful and complex feature. Make sure to read about the known caveats and limitations of state comparison.

The state method selects nodes by comparing them against a previous version of the same project, represented by a manifest. The file path of the comparison manifest must be specified using the --state flag or the DBT_STATE environment variable.

• state:new: Indicates there is no node with the same unique_id in the comparison manifest.

• state:modified: Includes all new nodes and any changes to existing nodes.

# run all tests on new models + and new tests on old models
dbt test --select "state:new" --state path/to/artifacts

# run all models that have been modified
dbt run --select "state:modified" --state path/to/artifacts

# list all modified nodes (not just models)
dbt ls --select "state:modified" --state path/to/artifacts

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, excluding database/schema/alias

• state:modified.relation: Changes to database/schema/alias (the database representation of this node), irrespective of target values or generate_x_name macros

• state:modified.persisted_descriptions: Changes to relation- or column-level description, if and only if persist_docs is enabled at each level

• state: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 the name and data_type of columns. 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.

There are two additional state selectors that complement state:new and state:modified by representing the inverse of those functions:

• state:old — A node with the same unique_id exists in the comparison manifest

• state:unmodified — All existing nodes with no changes

These selectors can help you shorten run times by excluding unchanged nodes. Currently, no subselectors are available at this time, but that might change as use cases evolve.

"exposure" method

Use exposure method to select the parent resources of an exposure.

# tests all models that feed into the monthly_reports exposure
dbt test --select "exposure:monthly_reports" 

# Runs all upstream resources of all exposures
dbt run --select "+exposure:*"

# Lists all upstream models of all exposures
dbt ls --select "+exposure:*" --resource-type model  

"metric" method

Use metric method to select parent resources of a metric.

# Runs all upstream resources of the monthly_qualified_leads metric
dbt run --select "+metric:monthly_qualified_leads"

# Builds all upstream models of all metrics
dbt build --select "+metric:*" --resource-type model

"results" method

When using the "results" method in a Bolt schedule of type Deferred or Turbo-CI, you don't need to pass the --state path/to/project/artifacts to your dbt command.

Paradime will point to the artifacts based on the Bolt schedule configurations:

• Deferred schedule

• Last run type

Use result method to select resources based on their results status from a previous execution.

# Runs all models that successfully ran on the previous execution of dbt run
dbt run --select "result:success" --state path/to/project/artifacts

# Runs all tests that issued warnings on the previous execution of dbt test
dbt test --select "result:warn" --state /path/to/project/artifacts

# Runs all seeds that failed on the previous execution of dbt seed
dbt seed --select "result:fail" --state /path/to/project/artifacts

Note: This method only works if a dbt command (ex. seed, test, run, build.) was performed prior.

"source_status" method

When using the "source_status" method in a Bolt schedule of type Deferred or Turbo-CI, you don't need to pass the --state path/to/project/artifacts to your dbt command.

Paradime will point to the artifacts based on the Bolt schedule configurations:

• Deferred schedule

• Last run type

Another element of job state is the source_status from a prior dbt invocation. For instance, after running dbt source freshness, dbt generates the sources.json artifact, which includes execution times and max_loaded_at dates for dbt sources.

The following dbt commands produce sources.json artifacts whose results can be referenced in subsequent dbt invocations:

• dbt source freshness

After running one of the above commands, you can reference the source freshness results by adding a selector to a subsequent command as follows:

# You can also set the DBT_STATE environment variable instead of the --state flag.
# must be run again to compare current to previous state
dbt source freshness 
dbt build --select "source_status:fresher+" --state path/to/prod/artifacts

"group" method

Use group method to select models defined within a specified group.

# Runs all models that belong to the marketing group
dbt run --select "group:marketing"

"access" Method

Use access method to select models based on their access property.

# List all public models
dbt list --select "access:public"

"version" Method

Use version to select versioned models based on the following:

• Version Identifier: A specific version label or number (old, prerelease, latest)

• Latest Version: The most recent version of a model.

# lists versios older than the 'latest' version
dbt list --select "version:old"  

# Lists versions new than the 'latest' version. 
dbt list --select "version:prerelease"  

# lists the 'latest'version
dbt list --select "version:latest"  

"semantic_model" Method

Use semantic_model method to selects semantic models.

# Runs the semantic model named "sales" and all its dependencies
dbt run --select "semantic_model:sales"

# Builds the semantic model "customer_orders", as well as all upstream resources
dbt build --select "+semantic_model:customer_orders"  

# Lists all resources semantic models
dbt ls --select "semantic_model:*"  

"saved_query" method

Use saved_query method to selects saved queries.

# Lists all saved queries
dbt list --select "saved_query:*"                    

# Lists your saved query named "customers_queries" and all upstream resources
dbt list --select "+saved_query:customers_queries"  

"unit_test" method

Use unit_test method to selects dbt™️ unit tests.

# list all unit tests 
dbt list --select "unit_test:*"                        

# list your unit test named "orders_with_zero_items" and all upstream resources
dbt list --select "+unit_test:orders_with_zero_items"