static_analysis

static_analysis

static_analysis는 모델·테스트·시드·스냅샷에 대해 dbt v2가 컴파일 타임에 SQL을 어떻게 분석할지 제어하는 설정이에요. strict 분석, 검사와 호환성을 균형 맞추는 baseline, 그리고 필요한 경우 분석을 건너뛰는 off 중에서 고를 수 있어요.

출처: 문서

본문

정보: static_analysis config는 dbt v2에서만 사용할 수 있어요. dbt v1에는 없고 무시돼요. dbt v2로 업그레이드하려면 Get started with dbt v2를 참고하세요.

static_analysis config는 dbt v2가 실행 전에 SQL을 어떻게 검증할지 설정해요. strict 분석, 검사와 호환성을 균형 맞추는 baseline, 또는 필요할 때 분석을 건너뛰는 off 중에 고를 수 있어요. 리소스 타입별 지원되는 설정 위치를 확인하세요.

dbt v2에서 strict 모드로 지원되는 Snowflake 함수를 확인하려면 Snowflake function support를, BigQuery는 BigQuery function support를 참고하세요.

dbt_project.yml

models:
  resource-path:
    +static_analysis: strict | baseline | off

models/filename.yml

models:
  - name: model_name
    config:
      static_analysis: strict | baseline | off

models/model_name.sql

{{ config(static_analysis='strict' | 'baseline' | 'off') }}

dbt_project.yml

data_tests:
  +static_analysis: strict | baseline | off

models/filename.yml

models:
  - name: model_name
    data_tests:
      - not_null:
          arguments:
            column_name: your_column_name
          config:
            static_analysis: strict | baseline | off

dbt_project.yml

seeds:
  resource-path:
    +static_analysis: strict | baseline | off

seeds/filename.yml

seeds:
  - name: seed_name
    config:
      static_analysis: strict | baseline | off

dbt_project.yml

snapshots:
  resource-path:
    +static_analysis: strict | baseline | off

snapshots/filename.yml

snapshots:
  - name: snapshot_name
    config:
      static_analysis: strict | baseline | off

dbt_project.yml

unit_tests:
  resource-path:
    +static_analysis: strict | baseline | off

models/filename.yml

unit_tests:
  - name: unit_test_name
    model: model_name
    config:
      static_analysis: strict | baseline | off

Definition

모델, 데이터 테스트, 단위 테스트, 시드, 스냅샷에 대해 static_analysis를 설정할 수 있어요.

dbt v2가 모델에 대해 정적 SQL 분석을 수행할지, 언제 수행할지 설정할 수 있어요. static_analysis config는 프로젝트 YAML 파일(dbt_project.yml), 모델 properties YAML 파일, 또는 모델 파일의 SQL config 블록에서 설정해요. 정적 분석의 다양한 모드에 대한 자세한 내용은 Principles of static analysis를 참고하세요.

모델을 strict로 설정해도 다운스트림 모델이 자동으로 strict가 되진 않아요. 명시적으로 설정하지 않으면 프로젝트 기본값을 유지해요. 자세한 내용과 예시는 strict mode inheritance를 참고하세요.

static_analysis에 사용할 수 있는 값:

  • baseline (기본값): SQL을 정적으로 분석해요. dbt v1에서 전환하는 사용자에게 권장되는 시작 지점으로, 매끄러운 마이그레이션 경험을 제공하면서도 대부분의 SQL 오류를 잡아줘요. 시간이 지나며 더 엄격한 분석에 점진적으로 opt-in할 수 있어요.
  • strict (이전의 on): 실행 전에 모든 SQL을 정적으로 분석해요. 최대 검증 보장을 위해 써요 — 전체 프로젝트가 유효함이 입증될 때까지 아무것도 실행되지 않아요.
  • off: 이 모델과 그 하위 모델에 대해 SQL 분석을 건너뛰어요.

Deprecated 값: on과 unsafe 값은 2026년 5월에 제거될 예정이에요. 대신 strict를 쓰세요.

strict 모드의 사용자 정의 함수(UDF)

static_analysis: strict가 적용되면 dbt v2는 sql_header와 on-run-start 프로젝트 훅에서 CREATE FUNCTION 문을 파싱해 그 UDF를 컴파일러 레지스트리에 등록하고, strict 정적 컴파일 중 사용할 수 있게 해요. baseline과 off 모드는 정적 분석을 위한 이 UDF 등록을 수행하지 않아요.

모델의 sql_header는 여러 문을 포함할 수 있어요. dbt v2는 CREATE FUNCTION 문에서만 UDF를 등록하고, 이 단계에서는 다른 문은 무시해요.

strict 분석이 여전히 UDF를 해석하지 못하면, 해당 모델에 static_analysis: off를 설정하세요.

static analysis 모드가 캐스케이드되는 방식

lineage에서 static_analysis 모드가 어떻게 적용되는지 두 규칙이 정해요.

  • 자격(eligibility) 규칙: 모델은 "부모"(lineage에서 현재 모델의 업스트림에 있는 모델)가 모두 자격이 있을 때만 정적 분석 자격이 있어요.
  • 엄격성(strictness) 규칙: "자식" 모델은 부모보다 더 엄격할 수 없어요 (자식은 lineage에서 현재 모델의 다운스트림 모델).

정적 분석 설정은 가장 엄격한 것에서 가장 덜 엄격한 것으로 캐스케이드돼요. 엄격성 계층은 다음과 같아요.

strict → baseline → off

부모 모드별 허용되는 다운스트림

lineage에서 다운스트림으로 갈 때 같은 모드를 유지하거나 완화할 수 있어요. 하지만 자식을 부모보다 더 엄격하게 만들 수는 없어요. 부모 모드별 허용되는 다운스트림 모드는 다음 표와 같아요.

예를 들어 Model A → Model B → Model C 계보에서:

  • Model A가 baseline이면 Model B를 strict로 설정할 수 없어요.
  • Model A가 strict면 Model B를 baseline으로 설정할 수 있어요.

이렇게 하면 부모 모델이 요구 사항을 충족하지 못했을 때 더 엄격한 검증 요구가 다운스트림에 적용되지 않아요. baseline은 strict가 업스트림 모델에서 필요로 하는 전체 분석 스키마를 생성하지 않으므로, baseline 모델의 다운스트림 모델은 strict 레벨 타입체크를 실행할 수 없어요.

더 깊은 논의와 시각 자료는 v2 개념 페이지를 참고하세요: New concepts. JSON 스키마에 대한 자세한 내용은 dbt-jsonschema 파일을 참고하세요.

커스텀 materialization

dbt v2는 커스텀 materialization으로 빌드된 모델에 대해 자동으로 static_analysis: off를 설정해요. 새 이름을 주거나 내장 table/incremental을 재사용한 경우 모두 적용돼요.

커스텀 materialization은 빌드하는 테이블에 컬럼을 추가·이름 변경·타입 변경할 수 있는데, dbt v2는 모델이 실행되기 전에 그 변경을 예측할 수 없어요. 내부 조회(introspective) 쿼리를 건너뛰는 것과 같은 이유로 분석도 건너뛰어요.

즉:

  • 커스텀 materialization을 쓰는 모델에 strict나 baseline을 설정해도 효과가 없어요 — off로의 자동 다운그레이드가 우선해요. 모델은 정적 분석 때문에 오류를 내지 않아요.
  • off가 캐스케이드되므로 그 모델의 모든 다운스트림 모델도 정적 분석 자격이 없고, 컬럼 레벨 lineage·타입체크 같은 SQL 이해에 의존하는 기능도 쓸 수 없어요.

DAG 대부분에서 정적 분석 커버리지를 유지하려면, 실용적인 곳에서는 내장 materialization을 쓰고 커스텀 materialization은 lineage의 잎(끝) 근처에 두세요. 예를 들어 아무도 의존하지 않는 모델에 커스텀 materialization을 써서 다운스트림 모델이 정적 분석 커버리지를 잃는 일을 줄이세요.

CLI override

--static-analysis 플래그로 실행의 모델 레벨 설정을 재정의할 수 있어요. 예를 들어 실행의 정적 분석을 비활성화하려면:

dbt run --static-analysis off # disable static analysis for all models
dbt run --static-analysis baseline # use baseline analysis for all models

Examples

다음 예시들은 여러 시나리오에서 static_analysis를 비활성화하거나 설정하는 방법을 보여줘요.

  • 모든 모델에 strict 분석 활성화
  • 패키지의 모든 모델 정적 분석 비활성화
  • YAML에서 단일 모델 정적 분석 비활성화
  • 커스텀 UDF 사용 모델의 SQL에서 정적 분석 비활성화
  • 데이터 테스트 정적 분석 설정
  • 단위 테스트 정적 분석 설정
  • 시드 정적 분석 설정
  • 스냅샷 정적 분석 설정

모든 모델에 strict 분석 활성화

프로젝트 전체에 최대 SQL 검증을 적용하는 권장 방법은 dbt_project.yml의 최상위 models 설정에 strict를 설정하는 거예요. 이 설정은 프로젝트의 모든 모델에 strict 분석을 적용하므로 각 모델을 개별 설정할 필요가 없어요.

dbt_project.yml

name: jaffle_shop

models:
  jaffle_shop:
    +static_analysis: strict
    staging:
      +materialized: view
    marts:
      +materialized: table

필요한 곳(예: 지원되지 않는 UDF를 쓰는 모델)에서는 개별 하위 디렉터리나 모델을 baseline 또는 off로 설정할 수 있어요. 개별 모델은 프로젝트 레벨 설정보다 덜 엄격하게만 설정할 수 있고, 더 엄격하게는 할 수 없어요. 프로젝트 기본값은 baseline이에요.

이 예시에서 strict 정적 분석은 Jaffle Shop 모델에만 적용돼요. 설치된 패키지는 명시적으로 설정하지 않으면 기본 baseline을 유지해요.

패키지의 모든 모델 정적 분석 비활성화

이 예시는 패키지의 모든 모델 정적 분석을 비활성화하는 방법을 보여줘요. + 접두사는 패키지의 모든 모델에 config를 적용해요.

dbt_project.yml

name: jaffle_shop

models:
  jaffle_shop:
    marts:
      +materialized: table

  a_package_with_introspective_queries:
    +static_analysis: off

YAML에서 단일 모델 정적 분석 비활성화

이 예시는 YAML에서 단일 모델의 정적 분석을 비활성화하는 방법을 보여줘요.

models/my_udf_using_model.yml

models:
  - name: model_with_static_analysis_off
    config:
      static_analysis: off

커스텀 UDF 사용 모델의 SQL에서 정적 분석 비활성화

이 예시는 SQL 파일에서 커스텀 사용자 정의 함수(UDF)를 쓰는 모델의 정적 분석을 비활성화하는 방법을 보여줘요.

models/my_udf_using_model.sql

{{ config(static_analysis='off') }}

select
  user_id,
  my_cool_udf(ip_address) as cleaned_ip
from {{ ref('my_model') }}

데이터 테스트 정적 분석 설정

이 예시는 dbt_project.yml로 프로젝트의 모든 테스트에 정적 분석을 설정하는 방법이에요.

dbt_project.yml

# dbt_project.yml
data_tests:
  +static_analysis: baseline

모델의 특정 데이터 테스트에 정적 분석을 설정하려면:

models/filename.yml

# models/filename.yml
models:
  - name: my_model
    data_tests:
      - not_null:
          arguments:
            column_name: order_id
          config:
            static_analysis: off

(dbt v2.0 이상 적용)

단위 테스트 정적 분석 설정

단위 테스트는 모델을 빌드하기 전에 SQL 로직을 정적 픽스처에 대해 검증해요. dbt_project.yml로 프로젝트의 모든 단위 테스트에 정적 분석을 설정하는 예시예요.

dbt_project.yml

# dbt_project.yml
unit_tests:
  my_project:
    +static_analysis: baseline

properties 파일에서 단일 단위 테스트를 설정하려면:

models/filename.yml

# models/filename.yml
unit_tests:
  - name: test_is_valid_email_address
    model: dim_customers
    config:
      static_analysis: off

단위 테스트에 compute: local을 설정하면(데이터 플랫폼 대신 DuckDB로 테스트 실행) 그 static_analysis가 strict로 승격돼요. 로컬 실행은 SQL을 DuckDB로 변환하기 위해 strict 분석이 필요하기 때문이에요. 테스트에 직접 baseline을 설정해도 마찬가지예요.

로컬 실행으로 설정된 단위 테스트에 static_analysis: off를 설정하면 테스트가 실행될 수 없고 ExecutorFailed (dbt1401)로 실패해요. 그 테스트에는 compute: remote를 쓰세요.

compute: local은 실험적이며 DBT_ENGINE_EXPERIMENTAL_LOCAL_UNIT_TESTS 환경 변수를 true로 설정해야 하므로, 이 상호작용은 opt-in한 경우에만 적용돼요.

시드 정적 분석 설정

이 예시는 프로젝트의 모든 시드에 정적 분석을 설정하는 방법이에요.

dbt_project.yml

# dbt_project.yml
seeds:
  your_project:
    +static_analysis: baseline

properties 파일에서 단일 시드를 설정하려면:

seeds/filename.yml

# seeds/filename.yml
seeds:
  - name: my_seed
    config:
      static_analysis: off

스냅샷 정적 분석 설정

이 예시는 프로젝트의 모든 스냅샷에 정적 분석을 설정하는 방법이에요.

dbt_project.yml

# dbt_project.yml
snapshots:
  your_project:
    +static_analysis: baseline

properties 파일에서 단일 스냅샷을 설정하려면:

snapshots/filename.yml

# snapshots/filename.yml
snapshots:
  - name: my_snapshot
    config:
      static_analysis: off

Considerations

  • 모델의 경우 정적 분석을 비활성화하면 SQL 이해에 의존하는 VS Code 확장 기능을 사용할 수 없어요.
  • 모델의 경우 정적 분석이 실패할 수 있어서(예: 동적 SQL 구성, 인식되지 않는 UDF), static_analysis: off를 설정해야 할 때도 있어요. 더 많은 예시는 When should I turn static analysis off?를 참고하세요.
  • 커스텀 materialization을 쓰는 모델은 자동으로 off로 설정되므로, 설정한 모드가 항상 적용되는 모드는 아니에요. 모델의 적용 모드를 확인하려면 dbt VS Code 확장이나 Studio IDE의 CodeLens를 사용하세요. 어떤 모델이 정적 분석을 비활성화했는지, 왜 그런지 보여줘요.

더 알아보기 (Learn more)