플래그(글로벌 구성) 소개

플래그(글로벌 구성) 소개 (About flags)

dbt에서 "플래그"(글로벌 구성이라고도 하며, 흔히 환경 변수로 설정)는 dbt가 프로젝트를 어떻게 실행하는지를 세밀하게 조정하는 설정이에요. dbt가 무엇을 실행할지 알려주는 리소스 전용 구성과는 달라요.

출처: 문서

본문

dbt에서 "플래그"(글로벌 구성이라고도 하며, 흔히 환경 변수로 설정)는 dbt가 프로젝트를 어떻게 실행하는지를 세밀하게 조정하는 설정이에요. dbt가 무엇을 실행할지 알려주는 리소스 전용 구성과는 달라요.

플래그는 로그의 시각적 출력, 특정 경고 메시지를 오류로 처리할지, 첫 오류를 만난 뒤 "빠르게 실패(fail fast)"할지 같은 것을 제어해요. 플래그는 모든 dbt 명령에서 쓸 수 있고 여러 곳에서 설정할 수 있기 때문에 "글로벌" 구성이에요.

로컬 개발 중 CLI로, 또는 dbt platform에서 dbt v2나 dbt v1 엔진과 함께 플래그를 사용할 수 있어요.

dbt의 플래그와 커맨드라인 옵션은 상당히 겹치지만 차이점이 있어요:

  • 특정 플래그는 dbt_project.yml에서만 설정할 수 있고, CLI 옵션으로 특정 호출에 대해 덮어쓸 수 없어요.
  • CLI 옵션을 특정 명령에서만 지원하고 모든 명령("글로벌")에서 지원하지 않는다면, 일반적으로 "플래그"로 간주하지 않아요.

플래그는 dbt_project.yml, 환경 변수, CLI 옵션에서 구성할 수 있어요. 자세한 내용은 환경 변수 구성을 참고하세요.

플래그를 설정하는 방법은 여러 가지이며, 사용 사례에 따라 달라요:

  • CLI 옵션: 이번 호출에 특화된 동작을 정의해요. 모든 dbt 명령에서 지원돼요.
  • 환경 변수: 런타임 환경마다 다른 동작(개발 vs. 프로덕션 vs. 지속적 통합)을 정의하고, 개발 환경에서 사용자별(개인 선호에 따라) 다른 동작을 정의해요.
  • dbt_project.yml의 프로젝트 레벨 flags: 이 프로젝트를 실행하는 모든 사람을 위한 버전 관리된 기본값을 정의해요. 또한 레거시 기능에서 마이그레이션을 관리하기 위해 동작 변경에 옵트인/아웃해요.
  • 사용자 설정 (~/.dbt/user_settings.yml): 이 머신의 모든 프로젝트에 걸쳐 적용되는 개인 선호를 정의해요. dbt login이 자동으로 기록해요.

가장 구체적인 설정이 "이겨요". CLI 옵션이 최우선이고, 그다음 환경 변수, 그다음 dbt_project.yml, 마지막으로 user_settings.yml이에요. 어느 곳에도 설정하지 않으면 dbt 내부에 정의된 기본값을 사용해요.

대부분의 플래그는 세 곳 모두에서 설정할 수 있어요:

# dbt_project.yml
flags:
  # set default for running this project -- anywhere, anytime, by anyone
  fail_fast: true

(dbt v1.11 이상에 적용)

# set this environment variable to 'True' (bash syntax)
export DBT_ENGINE_FAIL_FAST=1
dbt run

dbt run --fail-fast # set to True for this specific invocation
dbt run --no-fail-fast # set to False

두 가지 예외 범주가 있어요:

  1. 파일 경로를 설정하는 플래그: 런타임 실행과 관련된 파일 경로 플래그(예: --log-path 또는 --state)는 dbt_project.yml에서 설정할 수 없어요. 기본값을 덮어쓰려면 CLI 옵션을 전달하거나 환경 변수((dbt v1.11 이상) DBT_ENGINE_LOG_PATH와 DBT_ENGINE_STATE)를 설정해요. 프로젝트 리소스를 어디서 찾을지 알려주는 플래그(예: model-paths)는 dbt_project.yml에서 설정하지만 flags 사전 밖의 최상위 키로 설정해요; 이런 구성은 완전히 정적이고 명령이나 실행 환경에 따라 변하지 않을 것으로 기대돼요.
  2. 옵트인 플래그: 동작 변경에 옵트인/아웃하는 플래그는 dbt_project.yml에서 만 정의할 수 있어요. 버전 관리에 넣고 pull/merge 요청으로 마이그레이션하도록 의도됐어요. 그 값은 호출, 환경, 사용자에 걸쳐 무한정 분기하면 안 돼요.

Jinja로 작성한 사용자 정의 로직은 flags 컨텍스트 변수를 사용해 플래그 값을 확인할 수 있어요.

# dbt_project.yml

on-run-start:
  - '{{ log("I will stop at the first sign of trouble", info = true) if flags.FAIL_FAST }}'

flags의 값은 호출마다 다를 수 있으므로, dbt가 파싱 중에 해결하는 구성이나 의존성(ref + source)의 입력으로 flags를 사용하는 것을 강력히 권장하지 않아요.

이 표로 모든 사용 가능한 플래그와 인터페이스별 구성 방법을 비교할 수 있어요:

  • dbt CLI: dbt platform 지원 CLI에서 플래그가 지원되는지 여부.
  • Type / default: 허용되는 값 타입과 기본값.
  • In project: dbt_project.yml에서 플래그를 설정할 수 있는지 여부.
  • Env var: 해당 환경 변수 이름(사용 가능할 때). 일반적으로 v1.10 이하는 DBT_ 접두어, v1.11+는 DBT_ENGINE_ 접두어를 사용해요.
  • CLI flags: 특정 호출에 대해 플래그를 설정하는 커맨드라인 옵션 목록.

(dbt v1.11 이상에 적용)

Flag dbt CLI? Type / default In project? Env var CLI flags
cache_selected_only ✅ boolean default: False ✅ DBT_ENGINE_CACHE_SELECTED_ONLY --cache-selected-only --no-cache-selected-only
clean_project_files_only ❌ boolean default: True ❌ DBT_ENGINE_CLEAN_PROJECT_FILES_ONLY --clean-project-files-only --no-clean-project-files-only
debug ✅ boolean default: False ✅ DBT_ENGINE_DEBUG --debug --no-debug
defer ✅ (default) boolean default: False ❌ DBT_ENGINE_DEFER --defer --no-defer
defer_state ❌ path default: None ❌ DBT_ENGINE_DEFER_STATE --defer-state
favor_state ✅ boolean default: False ❌ DBT_ENGINE_FAVOR_STATE --favor-state --no-favor-state
empty ✅ boolean default: False ❌ DBT_ENGINE_EMPTY --empty --no-empty
event_time_start ✅ datetime default: None ❌ DBT_ENGINE_EVENT_TIME_START --event-time-start
event_time_end ✅ datetime default: None ❌ DBT_ENGINE_EVENT_TIME_END --event-time-end
fail_fast ✅ boolean default: False ✅ DBT_ENGINE_FAIL_FAST --fail-fast -x --no-fail-fast
full_refresh ✅ boolean default: False ✅ (as resource config) DBT_ENGINE_FULL_REFRESH --full-refresh --no-full-refresh
hints_enabled (v1.12+) ✅ boolean default: True ✅ DBT_ENGINE_HINTS_ENABLED --hints-enabled --no-hints-enabled
indirect_selection ❌ enum default: eager ✅ DBT_ENGINE_INDIRECT_SELECTION --indirect-selection
introspect ❌ boolean default: True ❌ DBT_ENGINE_INTROSPECT --introspect --no-introspect
log_cache_events ❌ boolean default: False ❌ DBT_ENGINE_LOG_CACHE_EVENTS --log-cache-events --no-log-cache-events
log_format_file ❌ enum default: default (text) ✅ DBT_ENGINE_LOG_FORMAT_FILE --log-format-file
log_format ❌ enum default: default (text) ✅ DBT_ENGINE_LOG_FORMAT --log-format
log_level_file ❌ enum default: debug ✅ DBT_ENGINE_LOG_LEVEL_FILE --log-level-file
log_level ❌ enum default: info ✅ DBT_ENGINE_LOG_LEVEL --log-level
log_path ❌ path default: None (uses logs/) ❌ DBT_ENGINE_LOG_PATH --log-path
manage_state (v2.0+) ✅ boolean default: False ✅ DBT_ENGINE_MANAGE_STATE --manage-state --no-manage-state
partial_parse ✅ boolean default: True ✅ DBT_ENGINE_PARTIAL_PARSE --partial-parse --no-partial-parse
populate_cache ✅ boolean default: True ✅ DBT_ENGINE_POPULATE_CACHE --populate-cache --no-populate-cache
print ❌ boolean default: True ❌ DBT_ENGINE_PRINT --print --no-print
printer_width ❌ int default: 80 ✅ DBT_ENGINE_PRINTER_WIDTH --printer-width
profile ❌ string default: None ✅ (as top-level key) DBT_ENGINE_PROFILE --profile
profiles_dir ❌ path default: None (current dir, then HOME dir) ❌ DBT_ENGINE_PROFILES_DIR --profiles-dir
project_dir ❌ path default: (empty) ❌ DBT_ENGINE_PROJECT_DIR --project-dir
quiet ✅ boolean default: False ❌ DBT_ENGINE_QUIET --quiet
resource-type (v1.8+) ✅ string default: None ❌ DBT_ENGINE_RESOURCE_TYPES DBT_ENGINE_EXCLUDE_RESOURCE_TYPES --resource-type --exclude-resource-type
sample ✅ string default: None ❌ DBT_ENGINE_SAMPLE --sample
send_anonymous_usage_stats ❌ boolean default: True ✅ DBT_ENGINE_SEND_ANONYMOUS_USAGE_STATS --send-anonymous-usage-stats --no-send-anonymous-usage-stats
source_freshness_run_project_hooks ❌ boolean default: True ✅ ❌ ❌
sqlparse ❌ YAML map default: MAX_GROUPING_DEPTH and MAX_GROUPING_TOKENS set to null ❌ DBT_ENGINE_SQLPARSE --sqlparse
state ❌ path default: none ❌ DBT_ENGINE_STATE, DBT_ENGINE_DEFER_STATE --state --defer-state
static_parser ❌ boolean default: True ✅ DBT_ENGINE_STATIC_PARSER --static-parser --no-static-parser
store_failures ✅ boolean default: False ✅ (as resource config) DBT_ENGINE_STORE_FAILURES --store-failures --no-store-failures
target_path ❌ path default: None (uses target/) ❌ DBT_ENGINE_TARGET_PATH --target-path
target ❌ string default: None ❌ DBT_ENGINE_TARGET --target
use_colors_file ❌ boolean default: True ✅ DBT_ENGINE_USE_COLORS_FILE --use-colors-file --no-use-colors-file
use_colors ❌ boolean default: True ✅ DBT_ENGINE_USE_COLORS --use-colors --no-use-colors
use_experimental_parser ❌ boolean default: False ✅ DBT_ENGINE_USE_EXPERIMENTAL_PARSER --use-experimental-parser --no-use-experimental-parser
use_fast_test_edges ✅ boolean default: False ❌ DBT_ENGINE_USE_FAST_TEST_EDGES --use-fast-test-edges --no-use-fast-test-edges
use_v2_parser ✅ boolean default: False ✅ DBT_ENGINE_USE_V2_PARSER --use-v2-parser
version_check ❌ boolean default: varies ✅ DBT_ENGINE_VERSION_CHECK --version-check --no-version-check
warn_error_options ✅ dict default: ✅ DBT_ENGINE_WARN_ERROR_OPTIONS --warn-error-options
warn_error ✅ boolean default: False ✅ DBT_ENGINE_WARN_ERROR --warn-error
write_json ✅ boolean default: True ✅ DBT_ENGINE_WRITE_JSON --write-json --no-write-json

--target 플래그로 dbt 명령을 실행할 때 사용할 target(환경)을 지정해요. 예를 들어:

dbt run --target dev
dbt run --target prod
dbt build --target staging

--target 플래그를 쓰면 구성 파일을 수정하지 않고도 같은 dbt 프로젝트를 여러 환경에서 실행할 수 있어요. target은 profiles.yml 파일에 정의해요. 연결 프로파일과 target에 대해 자세히 알아보세요.

더 알아보기 (Learn more)