Reading dbt_project.yml: Key Settings and Naming in the Shortest Path

dbt_project.yml is the blueprint for your entire project. It heavily shapes runtime behavior: default model materialization, schema naming, path layout, macro dispatch strategy, and more.

This article focuses on stable concepts that directly map to Analytics Engineer exam prep. We avoid version-specific behavior and follow the general assumptions found in the official documentation.

Overview and Minimum Setup: First, Grasp What This File Decides

dbt_project.yml declares project metadata and default settings. At minimum, define the project name, version, the profile name to use, and the config file format version (commonly 2).

Path keys (models, seeds, snapshots, tests, macros, etc.) have defaults and can be omitted, but it is safer to set them explicitly for team readability and CI stability.

• name must be unique and feeds into each node's unique_id (resource_type.package.name)
• profile binds to connection info in profiles.yml and is the key to environment switching
• config-version is commonly set to 2
• require-dbt-version pins the required dbt version range

From dbt_project.yml to a final relation name

Minimal to basic dbt_project.yml example

name: my_dbt_proj
version: 1.0.0
config-version: 2
profile: warehouse_default

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

require-dbt-version: ">=1.3.0"
quoting:
  database: false
  schema: false
  identifier: false

models:
  my_dbt_proj:
    +materialized: view

Naming and Path Design: How to Carve Up models / seeds / snapshots / tests

Naming conventions directly impact query readability and operational cost. Keep model names (file names), aliases, and schemas consistent, and apply per-directory defaults (materialized, schema, etc.) to keep things manageable.

Centralizing defaults for seeds and snapshots in dbt_project.yml blocks prevents policy drift.

• Under models, you can target settings by hierarchy (e.g., models/staging, models/marts)
• Setting delimiter, quote_columns, and column_types as project defaults for seeds reduces incidents
• target_schema / target_database for snapshots are easy to centralize at the project level

Recommended directory layout (example)

project_root/
  models/
    staging/
    intermediate/
    marts/
  seeds/
  snapshots/
  tests/
  macros/
  target/   (生成物)
  dbt_packages/ (依存パッケージ)

Example paths and naming conventions (project defaults)

models:
  my_dbt_proj:
    +materialized: view
    staging:
      +schema: stg
      +tags: [staging]
    marts:
      +materialized: table
      +schema: marts
      +tags: [prod]

seeds:
  my_dbt_proj:
    +schema: seed
    quote_columns: true
    delimiter: ","

snapshots:
  my_dbt_proj:
    target_schema: snap

Config Precedence and Model Naming Resolution Rules

dbt settings have different precedence depending on where they are written. Precedence and the alias/schema resolution order are favorite exam targets.

The basic principle: more local definitions win, and explicit CLI flags take the highest priority.

• Precedence (high → low): CLI flag > config() inside the resource file > dbt_project.yml > settings from dependent packages > default values
• alias replaces the database identifier, but ref('name') still references the model (node) name
• schema is determined by the generate_schema_name macro. When +schema is provided, the default implementation concatenates it onto target.schema

Visualizing config precedence as terraced layers

A sample showing precedence differences

# models/marts/orders.sql
{{ config(materialized='table', alias='fct_orders') }}
select * from {{ ref('int_orders') }}

# dbt_project.yml（抜粋）
models:
  my_dbt_proj:
    marts:
      +materialized: view   # ← リソース内 config がこれを上書き
      +schema: marts

Schema Naming: How to Use +schema and generate_schema_name Correctly

Schemas are decided by target (the target setting in profiles.yml), the project-side +schema, and the generate_schema_name macro that ties them together. With the default implementation, providing +schema typically appends it onto target.schema.

Decide explicitly as a team between suffix-append vs. full-replace, and override the macro if needed to prevent incidents.

• Default: with +schema, you often get target.schema_custom
• For full replacement, override generate_schema_name in your project
• It is simplest to absorb dev/prod suffixes on the target side

Examples of combining environment and custom schema

target.schema = analytics
+schema = stg

既定: analytics_stg
完全置換: stg
環境サフィックス例: analytics_dev_stg

Overriding generate_schema_name (full replacement example)

{% macro generate_schema_name(custom_schema_name, node) %}
  {# 完全置換：custom_schema_name があればそれを使い、なければ target.schema #}
  {% if custom_schema_name is not none %}
    {{ custom_schema_name }}
  {% else %}
    {{ target.schema }}
  {% endif %}
{% endmacro %}

# dbt_project.yml（例）
models:
  my_dbt_proj:
    staging:
      +schema: stg

Extension Basics: vars, dispatch, and Compatibility Settings

vars is a place to store parameters referenced from macros and models. dispatch controls the search order for macro resolution, helping you coexist with adapters and your own packages.

For compatibility and safety, pin the runtime version with require-dbt-version and make quoting, on-run-*, and clean-targets explicit.

• Use dispatch to define the order for replacing dbt's standard macros with your own
• Combine vars with env_var to absorb environment differences
• quoting normalizes identifier policy differences across adapters

Macro resolution dispatch order

Examples of extension-related settings

dispatch:
  - macro_namespace: dbt
    search_order: [my_pkg, dbt]

vars:
  country: "JP"
  run_ts: "{{ var('override_ts', env_var('RUN_TS', '1970-01-01')) }}"

require-dbt-version: ">=1.3.0,<2.0.0"

quoting:
  database: false
  schema: false
  identifier: false

on-run-start:
  - "{{ log('Run started at ' ~ run_started_at, info=True) }}"
clean-targets: ["target", "dbt_packages"]
packages-install-path: "dbt_packages"

Exam Prep and Pitfall Checklist

Frequent Analytics Engineer exam topics include config precedence, schema/identifier naming, and the default-vs-override relationship for seeds and snapshots. Use the checks below to close knowledge gaps.

The relationship between alias and ref, the default behavior of +schema with generate_schema_name, and the default for seeds' quote_columns are especially easy to confuse.

• ref resolves by node name. Even if you change alias, ref('node_name') stays the same
• The default materialized for models is view. Override inside the resource or in dbt_project.yml
• quote_columns for seeds is commonly true by default. Set it explicitly when needed
• target_schema for snapshots can also be set at the project level. Per-snapshot settings take precedence
• quoting can be controlled per database/schema/identifier. Mind adapter differences

A rough picture of the execution flow

Practical settings examples for seeds and tests

seeds:
  my_dbt_proj:
    +schema: seed
    quote_columns: true
    delimiter: ","
    column_types:
      id: integer
      amount: numeric

tests:
  +severity: warn
  +store_failures: true
  +schema: test_audit

Check with a Sample Question

Frequently Asked Questions