Skip to main content

Data test configurations

Data tests can be configured in a few different ways:

  1. Properties within .yml definition (generic tests only, see test properties for full syntax)
  2. A config() block within the test's SQL definition
  3. In dbt_project.yml

Data test configs are applied hierarchically, in the order of specificity outlined above. In the case of a singular test, the config() block within the SQL definition takes precedence over configs in the project file. In the case of a specific instance of a generic test, the test's .yml properties would take precedence over any values set in its generic SQL definition's config(), which in turn would take precedence over values set in dbt_project.yml.

Available configurations​

Click the link on each configuration option to read more about what it can do.

Data test-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 Data tests:

dbt_project.yml
tests:
  <resource-path>:
    +fail_calc: <string>
    +limit: <integer>
    +severity: error | warn
    +error_if: <string>
    +warn_if: <string>
    +store_failures: true | false
    +where: <string>

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
tests:
  <resource-path>:
    +enabled: true | false
    +tags: <string> | [<string>]
    +meta: {dictionary}
    # relevant for store_failures only
    +database: <string>
    +schema: <string>
    +alias: <string>

Examples​

Add a tag to one test​

If a specific instance of a generic data test:

models/<filename>.yml
models:
  - name: my_model
    columns:
      - name: id
        tests:
          - unique:
              tags: ['my_tag']

If a singular data test:

tests/<filename>.sql
{{ config(tags = ['my_tag']) }}

select ...

Set the default severity for all instances of a generic data test​

macros/<filename>.sql
{% test my_test() %}

    {{ config(severity = 'warn') }}

    select ...

{% endtest %}

Disable all data tests from a package​

dbt_project.yml
tests:
  package_name:
    +enabled: false

Specify custom configurations for generic data tests​

Beginning in dbt v1.9, you can use any custom config key to specify custom configurations for data tests. For example, the following specifies the snowflake_warehouse custom config that dbt should use when executing the accepted_values data test:


models:
  - name: my_model
    columns:
      - name: color
        tests:
          - accepted_values:
              values: ['blue', 'red']
              config:
                severity: warn
                snowflake_warehouse: my_warehouse

Given the config, the data test runs on a different Snowflake virtual warehouse than the one in your default connection to enable better price-performance with a different warehouse size or more granular cost allocation and visibility.

Add a description to generic and singular tests​

Starting from dbt v1.9 (also available to dbt Cloud release tracks), you can add descriptions to both generic and singular tests.

For a generic test, add the description in line with the existing YAML:

models/staging/<filename>.yml

models:
  - name: my_model
    columns:
      - name: delivery_status
        tests:
          - accepted_values:
              values: ['delivered', 'pending', 'failed']
              description: "This test checks whether there are unexpected delivery statuses. If it fails, check with logistics team"

For a singular test, define it in the test's directory:

tests/my_custom_test.yml

data_tests: 
  - name: my_custom_test
    description: "This test checks whether the rolling average of returns is inside of expected bounds. If it isn't, flag to customer success team"

For more information refer to Add a description to a data test.

0
Edit this page