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 (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

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.

vars:
  reporting_schema: reporting

In your model:

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

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

Common Model Configurations

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

Folder-Based Defaults

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

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:

{{ 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