Skip to main content

Model configurations

Available configurations​

Model-specific configurations​

Resource-specific configurations are applicable to only one dbt resource type rather than multiple resource types. You can define these settings in the project file (dbt_project.yml), a property file (models/properties.yml for models, similarly for other resources), or within the resource’s file using the {{ config() }} macro.

The following resource-specific configurations are only available to Models:

dbt_project.yml
models:
  <resource-path>:
    +materialized: <materialization_name>
    +sql_header: <string>
    +on_configuration_change: apply | continue | fail #only for materialized views on supported adapters
    +unique_key: <column_name_or_expression>
    +build_after: <dict>

General configurations​

General configurations provide broader operational settings applicable across multiple resource types. Like resource-specific configurations, these can also be set in the project file, property files, or within resource-specific files.

dbt_project.yml
models:
  <resource-path>:
    +enabled: true | false
    +tags: <string> | [<string>]
    +pre-hook: <sql-statement> | [<sql-statement>]
    +post-hook: <sql-statement> | [<sql-statement>]
    +database: <string>
    +schema: <string>
    +alias: <string>
    +persist_docs: <dict>
    +full_refresh: <boolean>
    +meta: {<dictionary>}
    +grants: {<dictionary>}
    +contract: {<dictionary>}
    +event_time: my_time_field

Warehouse-specific configurations​

Configuring models​

Model configurations are applied hierarchically. You can configure models from within an installed package and also from within your dbt project in the following ways, listed in order of precedence:

  1. Using a config() Jinja macro within a model.
  2. Using a config resource property in a .yml file.
  3. From the dbt_project.yml project file, under the models: key. In this case, the model that's nested the deepest will have the highest priority.

The most specific configuration always takes precedence. In the project file, for example, configurations applied to a marketing subdirectory will take precedence over configurations applied to the entire jaffle_shop project. To apply a configuration to a model or directory of models, define the resource path as nested dictionary keys.

Model configurations in your root dbt project have higher precedence than configurations in installed packages. This enables you to override the configurations of installed packages, providing more control over your dbt runs.

Example​

Configuring directories of models in dbt_project.yml​

To configure models in your dbt_project.yml file, use the models: configuration option. Be sure to namespace your configurations to your project (shown below):

dbt_project.yml


name: dbt_labs

models:
  # Be sure to namespace your model configs to your project name
  dbt_labs:

    # This configures models found in models/events/
    events:
      +enabled: true
      +materialized: view

      # This configures models found in models/events/base
      # These models will be ephemeral, as the config above is overridden
      base:
        +materialized: ephemeral

      ...


Apply configurations to one model only​

Some types of configurations are specific to a particular model. In these cases, placing configurations in the dbt_project.yml file can be unwieldy. Instead, you can specify these configurations at the top of a model .sql file, or in its individual YAML properties.

models/events/base/base_events.sql
{{
  config(
    materialized = "table",
    sort = 'event_time',
    dist = 'event_id'
  )
}}


select * from ...
models/events/base/properties.yml
version: 2

models:
  - name: base_events
    config:
      materialized: table
      sort: event_time
      dist: event_id

Configuring source freshness​

The model freshness config rebuilds models only when new source or upstream data is available. This is useful for models that depend on other models but only need to be updated periodically. For more information, see freshness.

Note that for every freshness config, you're required to either set values for both count and period, or set freshness: null. This requirement applies to all freshness types: freshness.warn_after, freshness.error_after, and freshness.build_after.

See the following example of a my_model.yml file using the freshness config:

models/my_model.yml
models:
  - name: stg_orders
    config:
      freshness:
        build_after:  # build this model no more often than every X amount of time, as long as as it has new data
          count: positive_integer
          period: minute | hour | day
          updates_on: any | all # optional config
0
Edit this page