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

```bash
# 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.

```bash
# 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.) 

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

```bash
# 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.

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

```bash
# 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.

```bash
# 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

```bash
# 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.

```bash
# 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.

```bash
# 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:

```bash
{{ 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:

```bash
# 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)`

```bash
# 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.

```bash
# 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

{% hint style="info" %}
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](https://docs.paradime.io/app-help/documentation/bolt/creating-schedules):

* Deferred schedule 
* Last run type
  {% endhint %}

**Note:** State-based selection is a powerful and complex feature. Make sure to read about the [known caveats and limitations](https://docs.getdbt.com/reference/node-selection/state-comparison-caveats) 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.

```bash
# 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. 

```bash
# 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.

```bash
# 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

{% hint style="info" %}
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](https://docs.paradime.io/app-help/documentation/bolt/creating-schedules):

* Deferred schedule 
* Last run type
  {% endhint %}

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

```bash
# 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

{% hint style="info" %}
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](https://docs.paradime.io/app-help/documentation/bolt/creating-schedules):

* Deferred schedule 
* Last run type
  {% endhint %}

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:

```bash
# 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. 

```bash
# 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. 

```bash
# 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.

```bash
# 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.

```bash
# 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.

```bash
# 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.

```bash
# 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"  
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.paradime.io/app-help/concepts/dbt-fundamentals/running-dbt/mastering-the-dbt-cli/methods.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.