# Project Settings and Defaults

The `dbt_project.yml` file is the configuration backbone of your dex project. It defines the project’s name, version, model paths, default behaviors, variables, and settings that apply across your models unless overridden locally.

This file is always located at the **root** of your project repository and plays a central role in determining how your models run, how they’re organized, and how dex interprets configuration values.

### Why It Matters

`dbt_project.yml` allows you to:

* Define default materializations and schemas per model folder
* Set global variables
* Organize models by [folder structure](/lakehouse-platform/develop-with-dex/layers.md) (e.g. `1.bronze`, `2.silver`, `3.gold`)
* Configure naming conventions, tags, and custom settings
* Control macro packages and project metadata

These defaults keep your project DRY, consistent, and easy to maintain.

### Example Structure

```yaml
name: my_dex_project
version: '1.0'
profile: default

model-paths: ["models"]
seed-paths: ["seeds"]
snapshot-paths: ["snapshots"]
macro-paths: ["macros"]

vars:
  start_date: '2023-01-01'
  environment: 'dev'

models:
  my_dex_project:
    +materialized: view

    1.bronze:
      +materialized: view
      +schema: raw

    2.silver:
      +materialized: table
      +schema: cleaned

    3.gold:
      +materialized: table
      +schema: trusted
      +tags: ['gold', 'analytics']
```

### Key Sections

* **`name`**: The name of your dex project. Used as the namespace for configurations.
* **`version`**: The version number of your project (e.g. `'1.0'`).
* **`profile`**: The connection profile used to connect to your warehouse. Managed by dex automatically.
* **`model-paths`**: Defines where your transformation models are stored (default: `["models"]`).
* **`seed-paths`**: Path to your CSV/Parquet seed files (default: `["seeds"]`).
* **`snapshot-paths`**: Path to your snapshot definitions (default: `["snapshots"]`).
* **`macro-paths`**: Path to your custom macro files (default: `["macros"]`).
* **`vars`**: Project-level variables that can be accessed using `var("...")` inside your models or macros.

```yaml
vars:
  reporting_schema: reporting
```

In your model:

```plsql
select * from {{ var('reporting_schema') }}.users
```

* **`models`**: Default configurations for folders and models in your project (e.g. materialization, schema, tags)

#### Common Model Configurations

<table><thead><tr><th width="184.3759765625">Key</th><th>Description</th></tr></thead><tbody><tr><td><code>+materialized</code></td><td>Sets the model type: <code>view</code>, <code>table</code>, <code>incremental</code>, or <code>ephemeral</code></td></tr><tr><td><code>+schema</code></td><td>Overrides the schema where the model will be created</td></tr><tr><td><code>+alias</code></td><td>Renames the final model (table or view) in the database</td></tr><tr><td><code>+tags</code></td><td>Adds one or more tags to the model (used for filtering, flows, and governance)</td></tr><tr><td><code>+enabled</code></td><td>Enables or disables the model (<code>true</code> or <code>false</code>)</td></tr><tr><td><code>+docs</code></td><td>Adds documentation metadata for models and columns</td></tr><tr><td><code>+persist_docs</code></td><td>Enables descriptions to be pushed to the warehouse (if supported)</td></tr><tr><td><code>+pre-hook</code></td><td>SQL statements to run before the model executes</td></tr><tr><td><code>+post-hook</code></td><td>SQL statements to run after the model finishes</td></tr></tbody></table>

### Folder-Based Defaults

You can define settings that apply to a specific folder of models by nesting configurations under the project name:

```yaml
models:
  my_dex_project:
    1.raw:
      +materialized: view
    2.cleaned:
      +materialized: table
      +schema: cleaned

```

These defaults apply to every model in the folder, unless explicitly overridden in the model file itself via `{{ config(...) }}`.

### Overriding Defaults in a Model

You can override anything from `dbt_project.yml` inside a model:

```sql
{{ config(
    materialized='incremental',
    schema='analytics',
    tags=['experimental']
) }}
```

This will take precedence over project-level defaults.

### Best Practices

* Keep your `dbt_project.yml` clean and well-commented
* Use folder-based settings for layered modeling
* Define variables and tags here for easy overrides by environment
* Treat this file as the control panel for project-wide conventions


---

# 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.dexlabs.io/lakehouse-platform/project-settings-and-defaults.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.