매크로 인자 검증

매크로 인자 검증 (Macro argument validation)

validate_macro_args 플래그는 프로젝트 파싱 중 매크로 인자를 검증해요. dbt v1.12부터 이 플래그는 기본값이 true예요.

출처: 문서

본문

validate_macro_args dbt v1 Latest dbt v1
Introduced 2025.03 1.10.0
Matured (default → true) 2026.09 1.12.0
Removed — —

dbt는 validate_macro_args 플래그로 매크로 인자를 검증해요. dbt v1.12부터 이 플래그는 기본값이 true예요.

과거에는 dbt가 YAML의 매크로 인자에서 type 필드에 대한 표준 어휘를 강제하지 않았어요. 그래서 type 필드는 문서화 전용이었고 dbt는 다음을 확인하지 않았어요:

  • 인자 이름이 매크로의 것과 일치하는지
  • 인자 타입이 유효하거나 매크로의 Jinja 정의와 일관적인지

문서화된 매크로의 예시:

macros/filename.yml

macros:
  - name: <macro name>
    arguments:
      - name: <arg name>
        type: <string>

이 플래그가 활성화되면(기본값) dbt는:

  • 프로젝트 파싱 중 매크로 인자를 검증해요.
  • YAML의 모든 인자 이름이 매크로 정의의 것과 일치하는지 확인해요.
  • 이름이나 타입이 일치하지 않으면 경고를 발생시켜요.
  • type 값이 지원되는 형식을 따르는지 검증해요.
  • YAML에 인자가 문서화되지 않았으면 매크로에서 유추해 manifest.json 파일에 포함해요.

검증은 언제 발생하나요?

매크로 인자 검증은 매크로 실행 중이 아니라 프로젝트 파싱 중에 실행돼요. 프로젝트를 파싱하는 모든 dbt 명령이 검증을 트리거해요.

dbt v1에서:

  • 검증은 대부분의 명령(parse, build, run, test, seed, snapshot, compile)에서 파싱의 일부로 실행돼요.
  • 전체 파싱(full parse) 시 dbt는 모든 매크로를 검증해요.
  • 부분 파싱(기본값) 시 dbt는 변경된 파일의 영향을 받는 매크로만 검증해요.
  • --no-partial-parse를 사용해 모든 매크로 검증을 강제할 수 있어요.

영향

그 자체로는 플래그가 경고를 발생시키고 빌드는 계속돼요. 하지만 이 경고는 강제 처리 경로를 사용하고 --warn-error를 존중하므로, --warn-error를 설정한 프로젝트는 파싱 시점에 빌드 실패를 보게 돼요.

이것은 매크로의 YAML 패치에 나열된 arguments:가 더 이상 매크로의 실제 Jinja 시그니처와 일치하지 않는 프로젝트에 영향을 줘요. 그런 프로젝트에서는 YAML 인자를 매크로와 일치하도록 업데이트하거나 arguments: 블록을 완전히 제거할 때까지 모든 명령이 파싱 시점에 실패해요.

권장 조치

파싱 시점에 InvalidMacroAnnotation 경고가 나타나거나(--warn-error 설정 시 파싱 실패 유발) 각 로그 라인을 확인하면 — 매크로 이름과 구체적인 불일치를 알려줘요. 영향을 받는 각 매크로의 macros: YAML 블록에서 arguments: 항목을 .sql 파일의 {% macro name(args) %} 선언과 정렬하거나 arguments: 블록을 완전히 제거해요.

YAML을 고치지 않고 경고를 무음화하려면 warn_error_options를 사용해요:

dbt_project.yml

flags:
  warn_error_options:
    silence:
      - InvalidMacroAnnotation

이 동작을 옵트아웃하려면 플래그를 false로 설정해요:

dbt_project.yml

flags:
  validate_macro_args: false

더 알아보기 (Learn more)