Skip to main content

About config variable

The config variable exists to handle end-user configuration for custom materializations. Configs like unique_key can be implemented using the config variable in your own materializations.

For example, code in the incremental materialization like this:

{% materialization incremental, default -%}
  {%- set unique_key = config.get('unique_key') -%}
  ...

is responsible for handling model code that looks like this:

{{
  config(
    materialized='incremental',
    unique_key='id'
  )
}}

Review Model configurations for examples and more information on valid arguments.

config.get​

Args:

  • name: The name of the configuration variable (required)
  • default: The default value to use if this configuration is not provided (optional)

The config.get function is used to get configurations for a model from the end-user. Configs defined in this way are optional, and a default value can be provided.

There are 3 cases:

  1. The configuration variable exists, it is not None
  2. The configuration variable exists, it is None
  3. The configuration variable does not exist
Deprecation warning for meta fallback

Starting in dbt Core v1.11, config.get() throws a deprecation warning when it finds a value in config.meta. This fallback was temporarily introduced when dbt reserved the top-level configs for official framework configuration. This fallback behavior will be removed in a future version.

To access custom configurations stored under meta, use config.meta_get() instead. For more information, check out deprecations.

Example usage:

{% materialization incremental, default -%}
  -- Example w/ no default. unique_key will be None if the user does not provide this configuration
  {%- set unique_key = config.get('unique_key') -%}

  -- Example w/ alternate value. Use alternative of 'id' if 'unique_key' config is provided, but it is None
  {%- set unique_key = config.get('unique_key') or 'id' -%}

  -- Example w/ default value. Default to 'id' if the 'unique_key' config does not exist
  {%- set unique_key = config.get('unique_key', default='id') -%}

  -- Example of a custom config nested under `meta` as required in v1.10 and higher.
  {% set my_custom_config = config.get('meta').custom_config_key %}
  ...

config.require​

Args:

  • name: The name of the configuration variable (required)

The config.require function is used to get configurations for a model from the end-user. Configs defined using this function are required, and failure to provide them will result in a compilation error.

Deprecation warning for meta fallback

Starting in dbt Core v1.11, config.require() throws a deprecation warning when it finds a value in config.meta. This fallback was temporarily introduced when dbt reserved the top-level configs for official framework configuration. This fallback behavior will be removed in a future version.

To access custom configurations stored under meta, use config.meta_require() instead. For more information, check out deprecations.

Example usage:

{% materialization incremental, default -%}
  {%- set unique_key = config.require('unique_key') -%}
  ...

config.meta_get​

Args:

  • name: The name of the configuration variable to retrieve from meta (required)
  • default: The default value to use if this configuration is not provided (optional)

The config.meta_get function retrieves custom configurations stored under the meta dictionary. Unlike config.get(), this function exclusively checks config.meta and won't result in a deprecation warning.

Use this function when accessing custom configurations that you've defined under meta in your model or resource configuration - it's equivalent to writing config.get('meta').get().

Example usage:

{% materialization custom_materialization, default -%}
  -- Retrieve a custom config from meta, returns None if not found
  {%- set custom_setting = config.meta_get('custom_setting') -%}

  -- Retrieve with a default value
  {%- set custom_setting = config.meta_get('custom_setting', default='default_value') -%}
  ...

Example model configuration:

models:
  - name: my_model
    config:
      meta:
        custom_setting: "my_value"

config.meta_require​

Args:

  • name: The name of the configuration variable to retrieve from meta (required)

The config.meta_require function retrieves custom configurations stored under the meta dictionary. Unlike config.require(), this function exclusively checks config.meta and won't result in deprecation warnings. If the configuration is not found, dbt raises a compilation error.

Use this function when you need to ensure a custom configuration exists under meta.

Example usage:

{% materialization custom_materialization, default -%}
  -- Require a custom config from meta, throws error if not found
  {%- set required_setting = config.meta_require('required_setting') -%}
  ...

Example model configuration:

models:
  - name: my_model
    config:
      meta:
        required_setting: "my_value"

Was this page helpful?

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.

0
Edit this page