var 함수

vars.yml이나 dbt_project.yml에서 정의한 변수를 컴파일 중에 모델에 제공할 수 있어요. 이 변수들은 패키지를 여러 환경에 배포하도록 구성하거나, 패키지 안의 여러 모델에 걸쳐 쓸 값을 정의할 때 유용해요.

출처: 문서

본문

(앱: dbt v1.12 이상)

vars.yml이나 dbt_project.yml에 정의된 변수는 프로젝트 전역 기본값으로 동작해요. --vars 커맨드라인 인자로 런타임에 이를 덮어쓸 수 있어요. 예를 들어 다른 날짜 범위로 테스트하거나, 모델 로직을 바꾸지 않고 환경별 설정으로 모델을 실행할 때요.

모델, 훅, 또는 매크로 안에서 변수를 가져오려면 var() 함수를 사용해요. var() 함수는 우선순위에 따라 프로젝트에 정의된 값이나 --vars로 전달된 값을 반환해요.

var()는 dbt가 컴파일 중에 Jinja를 렌더링하는 어디에서나 쓸 수 있어요. 프로젝트의 대부분 .sql과 .yml 파일을 포함해요. dbt가 컴파일 전에 읽는 구성 파일(profiles.yml이나 packages.yml 같은)에서는 동작하지 않아요.

모델에 변수를 추가하려면 var() 함수를 사용해요:

my_model.sql

select * from events where event_type = '{{ var("event_type") }}'

이 모델을 event_type 변수 없이 실행하려 하면 다음과 같은 컴파일 에러를 받아요:

Encountered an error:
! Compilation error while compiling model package_name.my_model:
! Required var 'event_type' not found in config:
Vars supplied to package_name.my_model = {
}

(앱: dbt v1.12 이상)

프로젝트에 변수를 정의하려면 전용 vars.yml 파일이나 dbt_project.yml 파일에 vars: 설정을 추가해요. vars.yml은 dbt_project.yml 보다 먼저 파싱되므로, dbt_project.yml에서 {{ var('...') }}으로 vars.yml의 변수를 참조할 수 있어요.

vars.yml

vars:
  event_type: activation

dbt_project.yml

dbt_project.yml에서 변수를 정의하거나 vars.yml의 변수를 참조할 수 있어요(예: models 설정에서):

dbt_project.yml

name: my_dbt_project
version: 1.0.0
config-version: 2

# Option 1: Define variables here
vars:
  event_type: activation

# Option 2: Reference a variable from vars.yml
models:
  my_dbt_project:
    +schema: "{{ var('event_type') }}"

변수를 vars.yml과 dbt_project.yml 양쪽에 정의할 수는 없어요. 둘 중 하나만 써야 해요. 두 파일 모두 vars 블록이 정의를 담고 있으면 dbt는 에러를 발생시켜요.

dbt 프로젝트에서 변수를 정의하는 방법에 대한 자세한 내용은 using variables 문서를 참고해요.

변수 기본값

var() 함수는 선택적 두 번째 인자 default를 받아요. 이 인자를 주면, 명시적으로 정의되지 않았을 때 변수의 기본값이 돼요.

my_model.sql

-- Use 'activation' as the event_type if the variable is not defined.
select * from events where event_type = '{{ var("event_type", "activation") }}'

커맨드라인 변수

dbt_project.yml 파일은 거의 변하지 않는 변수를 정의하기에 좋은 곳이에요.

특정 실행에서 변수를 덮어써야 할 때는 --vars 커맨드라인 옵션을 사용해요. 예를 들어 다른 날짜 범위로 테스트하거나, 환경별 설정으로 모델을 실행하거나, 동작을 동적으로 조정하고 싶을 때요.

--vars를 사용해 dbt 명령어에 하나 이상의 변수를 전달해요. 인자를 YAML 사전 문자열로 제공해요.

예를 들면:

$ dbt run --vars '{"event_type": "signup"}'

같은 --vars 구문을 dbt snapshot 같은 다른 dbt 명령어에서도 쓸 수 있어요:

$ dbt snapshot --select my_snapshot --vars '{"cutoff_date": "2026-01-01"}'

모델, 스냅샷, 또는 매크로 안에서 var() 함수로 값에 접근해요:

select '{{ var("event_type") }}' as event_type

--vars로 변수를 전달하면, 프로젝트에서 var() 함수를 쓰는 어디에서든 접근할 수 있어요.

여러 변수를 한 번에 전달할 수 있어요:

$ dbt run --vars '{event_type: signup, region: us}'

변수 하나만 설정하는 경우 대괄호는 선택 사항이에요:

$ dbt run --vars 'event_type: signup'

--vars 인자는 커맨드라인의 문자열로 YAML 사전을 받아요. YAML은 JSON처럼 엄격한 따옴표가 필요 없어서 편리해요.

다음 두 가지는 모두 유효하고 동일해요:

$ dbt run --vars '{"key": "value", "date": 20180101}'
$ dbt run --vars '{key: value, date: 20180101}'

--vars로 정의한 변수는 dbt_project.yml에 정의된 값을 덮어써요. 이 덕분에 커밋된 프로젝트 파일을 바꾸지 않고 일시적으로 설정을 덮어쓸 때 --vars가 유용해요. 완전한 우선순위 순서(패키지 스코프 변수와 var()에 정의된 기본값 포함)는 Variable precedence를 참고해요.

더 알아보기 (Learn more)

var()는 프로젝트 기본값을 정의하고 --vars로 런타임에 덮어쓰는 패턴으로 써요.
관련 개념: variables 문서, env_var.