Skip to main content

tags

dbt_project.yml
models/properties.yml
models:
  - name: model_name
    config:
      tags: <string> | [<string>]
    columns:
      - name: column_name
        config:
          tags: <string> | [<string>] # changed to config in v1.10 and backported to 1.9
        data_tests:
          - test_name:
              config:
                tags: <string> | [<string>]
models/<modelname>.sql
{{ config(
    tags="<string>" | ["<string>"]
) }}

select ...

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 +tag:my_tag+ — Run models tagged with my_tag, their upstream dependencies, and their downstream dependencies.
  • dbt run --select tag:my_tag+ --exclude tag:exclude_tag — Run models 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:

  • Each individual tag must be a string.
  • 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, property files, 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 property 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 must be strings​

Each individual tag must be a string value (for example, marketing or daily).

In the following example, my_tag: "my_value" is invalid because it is a key-value pair.

sources:
  - name: ecom
    schema: raw
    description: E-commerce data for the Jaffle Shop
    config:
      tags:
        my_tag: "my_value". # invalid
    tables:
      - name: raw_customers
        config:
          tags:
            my_tag: "my_value". # invalid

A warning is raised when the tags value is not a string. For example:

Field config.tags: {'my_tag': 'my_value'} is not valid for source (ecom)

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
Loading table...

Applying tags to specific columns and tests​

You can also apply tags to specific columns in a resource, and to tests.

models/properties.yml
models:
  - name: my_model
    columns:
      - name: column_name
        config:
          tags: ['column_level'] # changed to config in v1.10 and backported to 1.9
        data_tests:
          - unique:
              config:
                tags: ['test_level'] # changed to config in v1.10

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

dbt test --select tag:column_level
dbt test --select tag:test_level

Backwards compatibility for sources and exposures​

For backwards compatibility, tags is supported as a top-level key for sources and exposures (prior to dbt v1.10), but without the capabilities of config inheritance.

models/properties.yml
exposures:
  - name: my_exposure
    tags: ['exposure_tag'] # top-level key (legacy)
    # OR use config (v1.10+)
    config:
      tags: ['exposure_tag']

sources:
  - name: source_name
    tags: ['top_level'] # top-level key (legacy)
    # OR use config (v1.10+)
    config:
      tags: ['top_level']
    tables:
      - name: table_name
        tags: ['table_level'] # top-level key (legacy)
        # OR use config (v1.10+)
        config:
          tags: ['table_level']
        columns:
          - name: column_name
            config:
              tags: ['column_level'] # changed to config in v1.10 and backported to 1.9

Was this page helpful?

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.

0
Loading