Skip to content
Tutorials Center
My learning

Topics

Lesson 10 of 41 ยท Projects and Models

Model Configs and Properties

Learn the three places to configure dbt models, how precedence works, and the settings you use daily: materialized, schema, alias, tags, enabled, hooks and meta.

Configs tell dbt how to build a model: as a view or a table, in which schema, under what name, with which tags. Properties describe a model: its columns, descriptions and tests. Both can live in YAML, and configs can also live in the SQL file. This lesson maps the places and the settings you use most often.

Three places to set a config

1. In the model file with config() (most specific):

SQL
{{ config(
    materialized = 'table',
    schema = 'finance',
    tags = ['daily', 'finance']
) }}

select * from {{ ref('stg_shop__orders') }}

2. In a properties YAML file next to the model:

YAML
models:
  - name: fct_orders
    description: "One row per order."
    config:
      materialized: table
      tags: ["daily"]
    columns:
      - name: order_id
        description: "Primary key."

3. In dbt_project.yml, by folder:

YAML
models:
  shop_analytics:
    marts:
      +materialized: table
      finance:
        +schema: finance

Precedence

When the same setting appears in several places, the most specific wins:

  1. config() inside the SQL file
  2. config: in a properties YAML file
  3. folder configs in dbt_project.yml (deeper folders beat shallower ones)
  4. dbt's defaults

Use folder configs for rules that apply to a whole layer, and config() for exceptions. The next stand-in resolves a final configuration from all levels, with the overrides above:

Python Stand-in: precedence of config levels

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Note that real dbt merges some configs across levels rather than replacing them. List configs such as tags are combined, while scalar values like materialized are replaced.

Settings you will use constantly

Config Meaning
materialized view, table, ephemeral, incremental, ...
schema Custom schema suffix (see below)
database Target database or catalog, where the adapter supports it
alias Object name in the warehouse, if different from the file name
tags Labels you can select by (--select tag:daily)
enabled false hides the model from the project
meta Free-form key/value data (owners, SLAs) shown in docs
pre_hook / post_hook SQL to run before or after building the model
grants Permissions to grant on the built object
contract Enforce a column and type contract
persist_docs Push descriptions into warehouse comments
full_refresh Allow or block --full-refresh for this model

Schemas and the surprise of custom schema names

By default, all models build into the schema from your profile (for example dbt_maria in development). If you set +schema: finance, dbt does not use finance alone. The default macro generate_schema_name produces <target schema>_<custom schema>:

Target schema +schema Result
dbt_maria finance dbt_maria_finance
analytics finance analytics_finance

This keeps every developer's objects separated in dev. If you prefer finance exactly in production, override the macro. The following stand-in shows both behaviors (the macro idea comes in the macros lesson):

Python Stand-in: generate_schema_name

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

alias: separate file name from object name

File names must be unique across a project. If two models should produce a table with the same name in different schemas, give them an alias:

SQL
{{ config(alias='orders', schema='finance') }}

The file is still finance_orders.sql, but the table is orders. Referencing it with ref('finance_orders') keeps working.

Tags and meta

Tags are for selection; meta is for people and tools.

YAML
models:
  - name: fct_orders
    config:
      tags: ["daily", "core"]
      meta:
        owner: "[email protected]"
        sla_hours: 6

dbt build --select tag:daily runs everything tagged daily.

Hooks

Hooks run SQL around a model, for example to grant access:

SQL
{{ config(post_hook = "grant select on {{ this }} to role reporter") }}

{{ this }} refers to the object being built. Project-wide hooks (on-run-start, on-run-end) were shown in the project structure lesson.

Disabling a model

SQL
{{ config(enabled = false) }}

A disabled model is treated as if it did not exist, and any ref() to it fails. That is useful for retiring a model gradually or for dev-only objects.

Properties: describing models

Configs change behavior; properties document and constrain. They live in YAML files placed beside your models, one per folder or per model:

YAML
models:
  - name: dim_customers
    description: "One row per customer, with lifetime order stats."
    columns:
      - name: customer_id
        description: "Primary key."
      - name: lifetime_value
        description: "Total of non-cancelled order totals."

Later chapters add tests and documentation to these same files.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which configuration location has the highest precedence?

    An in-file config() is the most specific and overrides everything else.
  2. 2. With target schema 'analytics' and +schema: finance, what schema does the default macro choose?

    The default generate_schema_name joins the target schema and the custom schema with an underscore.
  3. 3. What is alias used for?

    alias changes the object name in the warehouse while the model keeps its file-based name in ref().
  4. 4. What happens to ref() calls that point at a model with enabled=false?

    A disabled model does not exist for dbt, so a ref to it causes an error.

Summary

  • Configs can be set in config(), in properties YAML or by folder in dbt_project.yml; the most specific wins.
  • Common configs: materialized, schema, alias, tags, enabled, meta, hooks and grants.
  • A custom schema is appended to the target schema by default; override generate_schema_name to change it.
  • Properties YAML describes models and columns and is where tests and docs are attached.

Next: Selecting Nodes: --select, Graph Operators and Tags