데이터 테스트 구성

데이터 테스트 구성 (Data test configurations)

데이터 테스트(Data tests)는 몇 가지 방법으로 구성할 수 있어요: .yml 정의의 properties(일반 테스트에만 해당, 전체 구문은 test properties 참고), 테스트 SQL 정의 안의 config() 블록, 그리고 dbt_project.yml. 데이터 테스트 config는 위에서 설명한 구체성(specificity) 순서대로 계층적으로 적용돼요.

출처: 문서

본문

데이터 테스트 config가 적용되는 방식

싱귤러 테스트(singular test)의 경우 SQL 정의 안의 config() 블록이 프로젝트 YAML 파일의 config보다 우선해요. 일반(generic) 테스트의 특정 인스턴스인 경우, 테스트의 .yml properties가 그 일반 SQL 정의의 config()에서 설정된 값보다 우선하고, 그것은 다시 프로젝트 YAML 파일(dbt_project.yml)에 설정된 값보다 우선해요.

사용 가능한 구성 (Available configurations)

각 구성 옵션의 링크를 클릭하면 그 옵션이 무엇을 하는지 더 읽을 수 있어요.

데이터 테스트 전용 구성 (Data test-specific configurations)

리소스별(resource-specific) 구성은 여러 리소스 타입이 아닌, dbt 리소스 타입 하나에만 적용돼요. 프로젝트 파일(dbt_project.yml), property 파일(모델이라면 models/properties.yml, 다른 리소스도 마찬가지), 또는 리소스 파일 안에서 {{ config() }} 매크로로 정의할 수 있어요. 다음 리소스별 구성은 데이터 테스트에만 사용할 수 있어요.

프로젝트 파일 — dbt_project.yml:

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

SQL 파일 config:

{{ config(
    fail_calc = "<string>",
    limit = <integer>,
    severity = "error | warn",
    error_if = "<string>",
    warn_if = "<string>",
    store_failures = true | false,
    where = "<string>"
) }}

Property 파일:

<resource_type>:
  - name: <resource_name>
    data_tests:
      - <test_name>: # # Actual name of the test. For example, dbt_utils.equality
          name: # Human friendly name for the test. For example, equality_fct_test_coverage
          description: "markdown formatting"
          arguments: # Available in v1.10.5 and higher. Older versions can set the <argument_name> as the top-level property.
            <argument_name>: <argument_value>
          config:
            fail_calc: <string>
            limit: <integer>
            severity: error | warn
            error_if: <string>
            warn_if: <string>
            store_failures: true | false
            where: <string>
            # Available in v1.12 and higher. Requires enabling the `require_sql_header_in_test_configs` flag.
            sql_header: <string> 

    columns:
      - name: <column_name>
        data_tests:
          - <test_name>:
              name:
              description: "markdown formatting"
              arguments: # Available in v1.10.5 and higher. Older versions can set the <argument_name> as the top-level property.
                <argument_name>: <argument_value>
              config:
                fail_calc: <string>
                limit: <integer>
                severity: error | warn
                error_if: <string>
                warn_if: <string>
                store_failures: true | false
                where: <string>
                # Available in v1.12 and higher. Requires enabling the `require_sql_header_in_test_configs` flag.
                sql_header: <string>

이 구성 메커니즘은 일반 테스트의 특정 인스턴스에만 지원돼요. 특정 싱귤러 테스트를 구성하려면 SQL 정의에서 config() 매크로를 사용해야 해요. dbt v1.12부터 properties.yml의 모델 또는 컬럼 레벨 일반 데이터 테스트 config에서 sql_header를 설정할 수 있어요. 데이터 테스트에서 config.sql_header를 쓰려면 require_sql_header_in_test_configs 플래그를 활성화하세요.

일반 구성 (General configurations)

일반 구성은 여러 리소스 타입에 걸쳐 적용되는 더 넓은 운영 설정을 제공해요. 리소스별 구성처럼 이들도 프로젝트 파일, property 파일 또는 리소스별 파일에서 설정할 수 있어요.

프로젝트 파일 — dbt_project.yml:

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

SQL 파일 config:

{{ config(
    enabled=true | false,
    tags="<string>" | ["<string>"]
    meta={dictionary},
    database="<string>",
    schema="<string>",
    alias="<string>",
) }}

Property 파일:

<resource_type>:
  - name: <resource_name>
    data_tests:
      - <test_name>: # Actual name of the test. For example, dbt_utils.equality
          name: # Human friendly name for the test. For example, equality_fct_test_coverage
          description: "markdown formatting"
          arguments: # available in v1.10.5 and higher. Older versions can set the <argument_name> as the top-level property.
            <argument_name>: <argument_value>
          config:
            enabled: true | false
            tags: <string> | [<string>]
            meta: {dictionary}
            # relevant for store_failures only
            database: <string>
            schema: <string>
            alias: <string>

    columns:
      - name: <column_name>
        data_tests:
          - <test_name>:
              name: 
              description: "markdown formatting"
              arguments: # available in v1.10.5 and higher. Older versions can set the <argument_name> as the top-level property.
                <argument_name>: <argument_value>
              config:
                enabled: true | false
                tags: <string> | [<string>]
                meta: {dictionary}
                # relevant for store_failures only
                database: <string>
                schema: <string>
                alias: <string>

이 구성 메커니즘은 일반 데이터 테스트의 특정 인스턴스에만 지원돼요. 특정 싱귤러 테스트를 구성하려면 SQL 정의에서 config() 매크로를 사용해야 해요.

예시 (Examples)

하나의 테스트에 tag 추가하기

일반 데이터 테스트의 특정 인스턴스라면 — models/<filename>.yml:

models:
  - name: my_model
    columns:
      - name: id
        data_tests:
          - unique:
              config:
                tags: ['my_tag'] # changed to config in v1.10

싱귤러 데이터 테스트라면 — tests/<filename>.sql:

{{ config(tags = ['my_tag']) }}

select ...

일반 데이터 테스트의 모든 인스턴스에 대해 기본 severity 설정하기 — macros/<filename>.sql:

{% test my_test() %}

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

    select ...

{% endtest %}

한 패키지의 모든 데이터 테스트 비활성화하기 — dbt_project.yml:

data_tests:
  package_name:
    +enabled: false

일반 데이터 테스트에 커스텀 구성 지정하기

dbt v1.9부터 데이터 테스트에 커스텀 config를 지정하기 위해 임의의 커스텀 config 키를 사용할 수 있어요. 예를 들어 다음은 accepted_values 데이터 테스트를 실행할 때 dbt가 사용해야 하는 snowflake_warehouse 커스텀 config를 지정해요:

models:
  - name: my_model
    columns:
      - name: color
        data_tests:
          - accepted_values:
              arguments: # available in v1.10.5 and higher. Older versions can set the <argument_name> as the top-level property.
                values: ['blue', 'red']
              config:
                severity: warn
                snowflake_warehouse: my_warehouse

이 config에 따라 데이터 테스트는 기본 연결에 있는 것과 다른 Snowflake 가상 웨어하우스에서 실행돼요. 다른 웨어하우스 크기나 더 세밀한 비용 배분·가시성으로 더 나은 price-performance를 얻기 위해서예요.

일반 테스트와 싱귤러 테스트에 description 추가하기

dbt v1.9부터(dbt release tracks에서도 제공) 일반 테스트와 싱귤러 테스트 모두에 description을 추가할 수 있어요.

일반 테스트의 경우 기존 YAML에 인라인으로 description을 추가하세요 — models/staging/<filename>.yml:

models:
  - name: my_model
    columns:
      - name: delivery_status
        data_tests:
          - accepted_values:
              arguments: # available in v1.10.5 and higher. Older versions can set the <argument_name> as the top-level property.
                values: ['delivered', 'pending', 'failed']
              description: "This test checks whether there are unexpected delivery statuses. If it fails, check with logistics team"

일반 데이터 테스트의 핵심 로직을 제공하는 Jinja 매크로에도 description을 추가할 수 있어요. 자세한 내용은 일반 데이터 테스트 로직에 description 추가(Add description to generic data test logic)를 참고하세요.

싱귤러 테스트라면 테스트의 디렉터리에 정의하세요 — 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"

자세한 내용은 데이터 테스트에 description 추가(Add a description to a data test)를 참고하세요.

일반 데이터 테스트에 sql_header 설정하기

(적용 범위: dbt v1.12 이상)

require_sql_header_in_test_configs 플래그를 활성화하면 일반 데이터 테스트 config에 sql_header를 설정해서 테스트가 실행되기 전에 지정된 SQL이 실행되게 할 수 있어요(예: 세션 파라미터 설정이나 주석 추가) — models/properties.yml:

models:
  - name: orders
    columns:
      - name: order_id
        data_tests:
          - not_null:
              name: not_null_orders_order_id
              config:
                sql_header: "-- SQL_HEADER_TEST_MARKER"

더 알아보기 (Learn more)

데이터 테스트 전반에 대해선 Data tests 문서를 참고하세요.
테스트 properties의 전체 구문은 test properties 문서를 확인하세요.