> For the complete documentation index, see [llms.txt](https://docs.paradime.io/app-help/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.paradime.io/app-help/guides-new/dbt-fundamentals/configuring-your-dbt-project/setting-up-your-dbt_project.yml.md).

# Setting up your dbt\_project.yml

The `dbt_project.yml` file is the **core configuration file** for any dbt project. It defines essential settings such as the project name, version, and model configurations, ensuring your project runs correctly and consistently.

***

### Why dbt\_project.yml Matters

The `dbt_project.yml` file serves several important functions:

* Identifies the root of your dbt project
* Configures project-wide settings
* Sets default materializations for your models
* Defines model-specific configurations
* Controls directory paths and behaviors

A well-configured project file ensures consistent behavior across environments and team members.

***

### Core Components of dbt\_project.yml

Here's a breakdown of the key sections and their purposes:

#### Project Metadata

```yaml
name: 'my_dbt_project'  # The unique name of your dbt project
version: '1.0.0'        # Optional versioning for project tracking
config-version: 2       # The version of dbt's config schema
```

This section defines:

* `name`: A unique identifier for your project (used in compiled SQL)
* `version`: Optional versioning for tracking project changes
* `config-version`: The version of dbt's configuration schema (should be 2 for current projects)

#### Profile Configuration

```yaml
profile: 'my_profile'  # Specifies the profile to use from profiles.yml
```

This tells dbt which profile to use from your `profiles.yml` file. Profiles define database connections and credentials.

| Setting   | Purpose                                   | Example                          |
| --------- | ----------------------------------------- | -------------------------------- |
| `profile` | Specifies which connection profile to use | `profile: 'snowflake_analytics'` |

#### Directory Paths

```yaml
# Paths for different dbt components
model-paths: ["models"]
analysis-paths: ["analyses"]
test-paths: ["tests"]
seed-paths: ["seeds"]
macro-paths: ["macros"]
snapshot-paths: ["snapshots"]
```

These settings define where dbt should look for different types of files:

| Path Setting     | Default         | Purpose                               |
| ---------------- | --------------- | ------------------------------------- |
| `model-paths`    | `["models"]`    | Where your SQL models are stored      |
| `seed-paths`     | `["seeds"]`     | Where your CSV files are stored       |
| `test-paths`     | `["tests"]`     | Where singular tests are stored       |
| `analysis-paths` | `["analyses"]`  | Where analytical queries are stored   |
| `macro-paths`    | `["macros"]`    | Where macros are stored               |
| `snapshot-paths` | `["snapshots"]` | Where snapshot definitions are stored |

#### Model Configuration

This section defines how your models should be materialized and configured:

```yaml
models:
  my_dbt_project:  # Must match your project name
    +materialized: view   # Default materialization for all models
    
    # Configure specific directories
    staging:
      +materialized: view  # Staging models as views
    
    marts:
      +materialized: table # Mart models as tables
      
      # Configure specific subdirectories
      marketing:
        +schema: marketing_schema  # Custom schema
```

Key points about model configuration:

* Configuration is hierarchical - lower levels inherit from higher levels
* The top-level project name must match your `name` value
* The `+` prefix indicates a dbt configuration property
* You can override configurations at any level

#### Seed Configuration

For controlling how CSV files are loaded into your database:

```yaml
seeds:
  my_dbt_project:
    +schema: raw_data     # Default schema for seed files
    +quote_columns: false # Whether to quote column names
    
    # Configuration for specific seeds
    country_codes:
      +column_types:
        country_code: varchar(2)
```

#### Variables

Define project-wide variables that can be used in models:

```yaml
vars:
  start_date: '2020-01-01'  # Available as {{ var('start_date') }}
  countries: ['US', 'CA', 'UK']
  # Environment-specific variables
  dev:
    debug_mode: true
  prod:
    debug_mode: false
```

#### On-Run Hooks

Execute SQL before or after your dbt runs:

```yaml
on-run-start:
  - "create schema if not exists {{ target.schema }}_staging"
  
on-run-end:
  - "grant usage on schema {{ target.schema }} to role reporter"
  - "grant select on all tables in schema {{ target.schema }} to role reporter"
```

#### Cleaning Up Artifacts

Define which directories should be cleaned by `dbt clean`:

```yaml
clean-targets:
  - "target"
  - "dbt_packages"
  - "logs"
```

***

### Complete Example

Here's a complete example of a `dbt_project.yml` file:

```yaml
name: 'ecommerce'
version: '1.0.0'
config-version: 2

profile: 'snowflake_analytics'

model-paths: ["models"]
seed-paths: ["seeds"]
test-paths: ["tests"]
analysis-paths: ["analyses"]
macro-paths: ["macros"]
snapshot-paths: ["snapshots"]
docs-paths: ["docs"]

target-path: "target"
clean-targets:
  - "target"
  - "dbt_packages"
  - "logs"

vars:
  start_date: '2020-01-01'
  include_test_accounts: false

models:
  ecommerce:
    +materialized: view
    
    staging:
      +materialized: view
      +schema: staging
      
    intermediate:
      +materialized: view
      +schema: intermediate
    
    marts:
      +materialized: table
      +schema: analytics
      
      finance:
        +schema: analytics_finance
        +tags: ["finance", "daily"]
      
      marketing:
        +schema: analytics_marketing
        +tags: ["marketing"]

seeds:
  ecommerce:
    +schema: reference_data

snapshots:
  ecommerce:
    +target_schema: snapshots

on-run-end:
  - "grant select on all tables in schema {{ target.schema }} to role analyst"
```

***

### Best Practices for dbt\_project.yml

| Category                           | Best Practices                                                                                                                                                                                                 |
| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Use Meaningful Names and Structure | <p>✅ Group models logically by function or business domain<br>✅ Use consistent naming patterns for schemas<br>✅ Document non-obvious configurations with comments</p>                                          |
| Set Sensible Defaults              | <p>✅ Define default materializations for different model types<br>✅ Use views for staging/intermediate models and tables for final models<br>✅ Configure schemas to match your data warehouse organization</p> |
| Optimize for Team Collaboration    | <p>✅ Use environment-specific variables where needed<br>✅ Set appropriate permissions with on-run hooks<br>✅ Document variables and their purposes</p>                                                         |
| Maintain and Evolve                | <p>✅ Review your project configuration regularly<br>✅ Update as your project grows and changes<br>✅ Document changes to configuration in version control</p>                                                   |

***

### Common Issues and Solutions

| Issue                           | Solution                                              |
| ------------------------------- | ----------------------------------------------------- |
| Models building in wrong schema | Check schema configuration and target profile         |
| Incorrect materialization       | Verify hierarchy of materialization settings          |
| Variable not available          | Ensure variable is defined at the correct level       |
| Path not found                  | Verify directory paths match actual project structure |

Your `dbt_project.yml` file is a living document that will evolve with your project. Taking the time to configure it correctly will lead to a more maintainable and consistent dbt implementation.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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/guides-new/dbt-fundamentals/configuring-your-dbt-project/setting-up-your-dbt_project.yml.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.