Skip to main content

tags

dbt_project.yml

Definition​

Apply a tag (or list of tags) to a resource.

These tags can be used as part of the resource selection syntax, when running the following commands:

  • dbt run --select tag:my_tag — Run all models tagged with a specific tag.
  • dbt build --select tag:my_tag — Build all resources tagged with a specific tag.
  • dbt seed --select tag:my_tag — Seed all resources tagged with a specific tag.
  • dbt snapshot --select tag:my_tag — Snapshot all resources tagged with a specific tag.
  • dbt test --select tag:my_tag — Indirectly runs all tests associated with the models that are tagged.

Using tags with the + operator​

You can use the + operator to include upstream or downstream dependencies in your tag selection:

  • dbt run --select tag:my_tag+ — Run models tagged with my_tag and all their downstream dependencies.
  • dbt run --select +tag:my_tag — Run models tagged with my_tag and all their upstream dependencies.
  • dbt run --select +model_name+ — Run a model, its upstream dependencies, and its downstream dependencies.
  • dbt run --select tag:my_tag+ --exclude tag:exclude_tag — Run model tagged with my_tag and their downstream dependencies, and exclude models tagged with exclude_tag, regardless of their dependencies.
Usage notes about tags

When using tags, consider the following:

  • Tags are additive across project hierarchy.
  • Some resource types (like sources, exposures) require tags at the top level.

Refer to usage notes for more information.

Examples​

The following examples show how to apply tags to resources in your project. You can configure tags in the dbt_project.yml, schema.yml, or SQL files.

Use tags to run parts of your project​

Apply tags in your dbt_project.yml as a single value or a string. In the following example, one of the models, the jaffle_shop model, is tagged with contains_pii.

dbt_project.yml
models:
  jaffle_shop:
    +tags: "contains_pii"

    staging:
      +tags:
        - "hourly"

    marts:
      +tags:
        - "hourly"
        - "published"

    metrics:
      +tags:
        - "daily"
        - "published"

Apply tags to models​

This section demonstrates applying tags to models in the dbt_project.yml, schema.yml, and SQL files.

To apply tags to a model in your dbt_project.yml file, you would add the following:

dbt_project.yml
models:
  jaffle_shop:
    +tags: finance # jaffle_shop model is tagged with 'finance'.

To apply tags to a model in your models/ directory YAML file, you would add the following using the config property:

models/stg_customers.yml
models:
  - name: stg_customers
    description: Customer data with basic cleaning and transformation applied, one row per customer.
    config:
      tags: ['santi'] # stg_customers.yml model is tagged with 'santi'.
    columns:
      - name: customer_id
        description: The unique key for each customer.
        data_tests:
          - not_null
          - unique

To apply tags to a model in your SQL file, you would add the following:

models/staging/stg_payments.sql
{{ config(
    tags=["finance"] # stg_payments.sql model is tagged with 'finance'.
) }}

select ...

Run resources with specific tags (or exclude resources with specific tags) using the following commands:

# Run all models tagged "daily"
  dbt run --select tag:daily

# Run all models tagged "daily", except those that are tagged hourly
  dbt run --select tag:daily --exclude tag:hourly

Apply tags to seeds​

dbt_project.yml
seeds:
  jaffle_shop:
    utm_mappings:
      +tags: marketing
dbt_project.yml
seeds:
  jaffle_shop:
    utm_mappings:
      +tags:
        - marketing
        - hourly

Apply tags to saved queries​

This following example shows how to apply a tag to a saved query in the dbt_project.yml file. The saved query is then tagged with order_metrics.

dbt_project.yml
saved-queries:
  jaffle_shop:
    customer_order_metrics:
      +tags: order_metrics

Then run resources with a specific tag using the following commands:

# Run all resources tagged "order_metrics"
  dbt run --select tag:order_metrics

The second example shows how to apply multiple tags to a saved query in the semantic_model.yml file. The saved query is then tagged with order_metrics and hourly.

semantic_model.yml
saved_queries:
  - name: test_saved_query
    description: "{{ doc('saved_query_description') }}"
    label: Test saved query
    config:
      tags: 
        - order_metrics
        - hourly

Run resources with multiple tags using the following commands:

# Run all resources tagged "order_metrics" and "hourly"
  dbt build --select tag:order_metrics tag:hourly

Usage notes​

Tags are additive​

Tags accumulate hierarchically. The earlier example would result in:

ModelTags
models/staging/stg_customers.sqlcontains_pii, hourly
models/staging/stg_payments.sqlcontains_pii, hourly, finance
models/marts/dim_customers.sqlcontains_pii, hourly, published
models/metrics/daily_metrics.sqlcontains_pii, daily, published

Other resource types​

Tags can also be applied to sources, exposures, and even specific columns in a resource. These resources do not yet support the config property, so you'll need to specify the tags as a top-level key instead.

models/schema.yml
version: 2

exposures:
  - name: my_exposure
    tags: ['exposure_tag']
    ...

sources:
  - name: source_name
    tags: ['top_level']

    tables:
      - name: table_name
        tags: ['table_level']

        columns:
          - name: column_name
            tags: ['column_level']
            tests:
              - unique:
                  tags: ['test_level']

In the example above, the unique test would be selected by any of these four tags:

dbt test --select tag:top_level
dbt test --select tag:table_level
dbt test --select tag:column_level
dbt test --select tag:test_level
0
Edit this page