Skip to main content

Configs, properties, what are they?

Clarify the difference between properties and configs in dbt: properties describe resources, while configs control how dbt builds them in the warehouse

Resources in your project—models, snapshots, seeds, tests, and the rest—can have a number of declared properties. Resources can also define configurations, which are a special kind of property that bring extra abilities. What's the distinction?

  • Properties are declared for resources one-by-one in properties.yml files. Configs can be defined there, nested under a config property. They can also be set one-by-one via a config() macro (right within .sql files), and for many resources at once in dbt_project.yml.
  • Because configs can be set in multiple places, they are also applied hierarchically. An individual resource might inherit or override configs set elsewhere.
  • You can select resources based on their config values using the config: selection method, but not the values of non-config properties.
  • There are slightly different naming conventions for properties and configs depending on the file type. Refer to naming convention for more details.

A rule of thumb: properties declare things about your project resources; configs go the extra step of telling dbt how to build those resources in your warehouse. This is generally true, but not always, so it's always good to check!

For example, you can use resource properties to:

  • Describe models, snapshots, seed files, and their columns
  • Assert "truths" about a model, in the form of data tests, e.g. "this id column is unique"
  • Define pointers to existing tables that contain raw data, in the form of sources, and assert the expected "freshness" of this raw data
  • Define official downstream uses of your data models, in the form of exposures

Whereas you can use configurations to:

  • Change how a model will be materialized (table, view, incremental, etc)
  • Declare where a seed will be created in the database (<database>.<schema>.<alias>)
  • Declare whether a resource should persist its descriptions as comments in the database
  • Apply tags and "meta" properties
0