Working with Tags

Tags in dbt™ are powerful metadata labels that can be applied to various resources in your project. They enable flexible model selection, improved workflow management, and better project organization.

By leveraging tags, you can:

• Group models logically – Categorize models based on refresh schedule, function, or ownership.

• Control execution – Run or exclude specific sets of models.

• Optimize CI/CD pipelines – Target models for incremental builds and tests.

• Improve project maintainability – Standardize workflows across teams.

---

How to Apply Tags

Tags can be applied in two primary ways:

1. Defining Tags in a Model File

Tags can be assigned directly within SQL models using the config() function:

{{ config(
    tags=["finance", "daily_refresh"]
) }}

SELECT *
FROM {{ ref('stg_transactions') }}

2. Defining Tags in dbt_project.yml

Tags can also be applied at the project level, affecting entire folders or groups of models:

models:
  my_project:
    +tags: "core"  # Assigns a single tag

    staging:
      +tags: ["staging", "raw_data"]  # Multiple tags

    marts:
      +tags:
        - "mart"
        - "business_logic"

✅ Tag Inheritance – Models inside a folder inherit the parent folder’s tags unless overridden.

Example:

models/
  staging/
    customers.sql   → Tags: ["staging", "raw_data"]
    orders.sql      → Tags: ["staging", "raw_data"]
  marts/
    dim_customer.sql → Tags: ["mart", "business_logic"]

Tags can also be applied to snapshots, seeds, and exposures in your project:

yamlCopyEditsnapshots:
  my_project:
    +tags: ["historical_data"]

seeds:
  my_project:
    +tags: ["seed_data"]

sources:
  - name: external_source
    tags: ['external']

---

Selecting Models with Tags in dbt CLI

Once models have tags, they can be referenced in dbt commands.

Running Tagged Models:

bashCopyEditdbt run --select tag:finance

Running Multiple Tags:

bashCopyEditdbt run --select tag:daily_refresh tag:critical

Excluding Specific Tags:

bashCopyEditdbt run --select tag:daily_refresh --exclude tag:deprecated

Running Models by Data Layer:

bashCopyEditdbt run --select tag:staging+

(Runs staging models and all downstream dependencies.)

Running Tests or Snapshots by Tag:

bashCopyEditdbt test --select tag:critical
dbt snapshot --select tag:weekly

---

Best Practices for Using Tags

To ensure effective and scalable use of tags in dbt™, follow these best practices:

✅ Use Clear Naming Conventions – Standardize tag names for consistency (daily_refresh, finance_data). ✅ Document Tag Usage – Maintain a README or project guide explaining tag structures. ✅ Avoid Overuse – Too many overlapping tags can create confusion. ✅ Integrate with CI/CD – Use tags to selectively run models in automated pipelines. ✅ Combine Tags with Graph Operators – Use + and @ for efficient model selection.

Example: Layer-Based Tagging

Using tags for data modeling layers improves clarity:

yamlCopyEditmodels:
  staging:
    +tags: ["bronze_layer"]
  intermediate:
    +tags: ["silver_layer"]
  marts:
    +tags: ["gold_layer"]

---

Common Use Cases for Tags

1️⃣ Refresh Schedules

Group models by how frequently they update:

yamlCopyEditmodels:
  my_project:
    hourly:
      +tags: ["hourly_refresh"]
    daily:
      +tags: ["daily_refresh"]

2️⃣ Data Classification

Differentiate PII data or public datasets:

yamlCopyEditmodels:
  my_project:
    +tags: ["contains_pii"]
    public:
      +tags: ["public_data"]

3️⃣ Testing Strategies

Use tags to target critical models for testing:

yamlCopyEditmodels:
  my_project:
    critical:
      +tags: ["critical_path", "requires_alert"]

---

Troubleshooting Tags

If tags are not behaving as expected, check the following:

1️⃣ Verify Tag Inheritance – Check if the model is inheriting tags from dbt_project.yml. 2️⃣ Check Tag Syntax – Ensure tag names match exactly (case-sensitive). 3️⃣ Use dbt ls to Validate Tags – Run:

bashCopyEditdbt ls --select tag:finance

(Lists all models with the finance tag.)

4️⃣ Ensure Proper YAML Formatting – Indentation errors in dbt_project.yml can cause tags to be ignored. 5️⃣ Confirm Tags Exist – Run:

bashCopyEditdbt debug

(Checks for syntax issues that might impact tag recognition.)

---

By incorporating tags effectively, dbt™ users can optimize execution, improve project structure, and enhance collaboration. 🚀

yamlCopyEdit
---

### **What I Kept and Improved:**
✅ **Maintained all key explanations** from the original content.  
✅ **Preserved best practices and troubleshooting tips**.  
✅ **Kept tag inheritance details and applied them more clearly**.  
✅ **Streamlined CLI command examples for better usability**.  
✅ **Added real-world examples for testing strategies and layer-based modeling**.  

This version ensures **completeness, clarity, and consistency** while keeping all valuable information **from the original draft**.  

Let me know if you'd like **any additional refinements** before we move to the next page! 🚀