dbt compile 명령어

dbt compile 명령어

dbt compile 명령어는 소스 파일에서 실행 가능한 SQL을 생성해요. 모델·데이터 테스트·분석·함수·스냅샷의 컴파일된 SQL을 target/ 디렉터리에서 확인할 수 있어요. 실제 데이터베이스에는 아무것도 구체화하지 않아서 검증 목적으로 자주 사용해요.

출처: 문서

본문

dbt compile은 다음을 위해 소스 파일에서 실행 가능한 SQL을 생성해요:

(dbt v1.12 이상 적용)

  • 모델(Models)
  • 데이터 테스트(Data tests)
  • 분석(Analyses)
  • 함수(Functions)
  • 스냅샷(Snapshots) (dbt v1.12에서 사용 가능)

이 컴파일된 SQL 파일들은 dbt 프로젝트의 target/ 디렉터리에서 찾을 수 있어요.

compile 명령어는 다음에 유용해요:

  • 리소스 파일의 컴파일된 출력을 시각적으로 검사하는 것. 복잡한 Jinja 로직이나 매크로 사용을 검증할 때 유용해요.
  • 컴파일된 SQL을 수동으로 실행하는 것. 모델이나 데이터 테스트를 디버깅할 때 버그의 원인을 찾기 위해 내부 select 문을 실행해 보는 게 자주 도움이 돼요.
  • analysis 파일을 컴파일하는 것. 분석 파일에 대한 자세한 내용은 여기를 읽어보세요.

몇 가지 흔한 오해:

  • dbt compile은 dbt run이나 다른 빌드 명령어의 선행 조건이 아니에요. 그 명령어들은 스스로 컴파일을 처리해요.
  • 단지 프로젝트 코드를 데이터 웨어하우스에 연결하지 않고 읽고 검증하고 싶다면 dbt parse를 사용하세요.

인터랙티브 컴파일

dbt v1.5부터 compile은 CLI에서 "인터랙티브"하게 동작할 수 있어요. 노드나 임의의 dbt-SQL 쿼리의 컴파일된 코드를 표시해요:

  • --select 이름으로 특정 노드 선택
  • --inline 임의의 dbt-SQL 쿼리

이는 target/ 디렉터리에 쓰는 것에 더해 컴파일된 SQL을 터미널에도 기록해요.

예를 들어:

dbt compile --select "stg_orders"                           
dbt compile --inline "select * from {{ ref('raw_orders') }}"

다음이 반환돼요:

dbt compile --select "stg_orders"                           

21:17:09  Running with dbt=1.7.5
21:17:09  Registered adapter: postgres=1.7.5
21:17:09  Found 5 models, 3 seeds, 20 tests, 0 sources, 0 exposures, 0 metrics, 401 macros, 0 groups, 0 semantic models
21:17:09  
21:17:09 Concurrency: 24 threads (target='dev')
21:17:09  
21:17:09  Compiled node 'stg_orders' is:
with source as (
    select * from "jaffle_shop"."main"."raw_orders"

),

renamed as (

    select
        id as order_id,
        user_id as customer_id,
        order_date,
        status

    from source

)

select * from renamed

dbt compile --inline "select * from {{ ref('raw_orders') }}"

18:15:49  Running with dbt=1.7.5
18:15:50  Registered adapter: postgres=1.7.5
18:15:50  Found 5 models, 3 seeds, 20 tests, 0 sources, 0 exposures, 0 metrics, 401 macros, 0 groups, 0 semantic models
18:15:50  
18:15:50  Concurrency: 5 threads (target='postgres')
18:15:50  
18:15:50  Compiled inline node is:
select * from "jaffle_shop"."main"."raw_orders"

이 명령어는 캐시 관련 메타데이터를 얻고 내부 조회(introspective queries)를 실행하기 위해 데이터 플랫폼에 접근해요. 다음 플래그를 사용해요:

  • --no-populate-cache: 초기 캐시 채우기를 비활성화해요. 메타데이터가 필요하면 캐시 미스가 발생해 dbt가 메타데이터 쿼리를 실행하게 돼요. 이는 dbt 플래그라서 접두사에 dbt를 붙여야 해요. 예: dbt --no-populate-cache.
  • --no-introspect: 내부 조회를 비활성화해요. 리소스 정의가 이를 실행해야 한다면 dbt가 오류를 발생시켜요. 이는 dbt compile 플래그라서 접두사에 dbt compile을 붙여야 해요. 예: dbt compile --no-introspect.

내부 조회를 사용하는 리소스 내부 조회를 사용하는 리소스의 컴파일된 SQL은 웨어하우스의 메타데이터에 의존할 수 있어요. 컴파일은 그 메타데이터의 상태에 따라 불완전하거나 달라질 수 있어요.

--select로 테스트 컴파일하기

선택자(selector)가 프로젝트의 테스트 노드와 일치한다면 dbt compile로 테스트를 컴파일할 수 있어요. 선택자 메서드로 테스트 그룹을 지정할 수도 있어요:

모든 테스트 노드 컴파일:

dbt compile --select "resource_type:test"

일반(generic) 테스트만 컴파일:

dbt compile --select "test_type:generic"

단일(singular) 테스트만 컴파일:

dbt compile --select "test_type:singular"

dbt가 selection does not match any nodes를 반환하면 선택자가 발견된 노드와 일치하지 않은 거예요. 이렇게 문제를 해결해요:

  • 모델 선택자의 테스트 목록을 나열하세요:
dbt ls --resource-type test --select "MODEL_NAME"
  • 반환된 테스트 노드 이름 중 하나를 dbt compile --select에 복사하세요:
dbt compile --select "TEST_NODE_NAME"

예를 들어, 반환된 테스트 노드 이름은 이렇게 생겼을 수 있어요:

FULL_TEST_NODE_NAME
  • 테스트가 반환되지 않으면 compile을 다시 실행하기 전에 테스트 정의와 프로젝트 경로를 확인하세요.

더 많은 선택자 패턴은 Test selection examples를 참고하세요.

(dbt v2.0 이상 적용)

dbt Information Schema

--generate-info-schema를 사용해 dbt Information Schema를 버전이 있는 하위 디렉터리(현재 v1/)의 target/info_schema/에 기록해요. Information Schema는 프로젝트의 메타데이터를 쿼리 가능한 SQL 테이블(데이터베이스의 INFORMATION_SCHEMA와 유사)로 노출해서, manifest.json을 파싱하지 않고도 모델·소스 등을 조회할 수 있어요.

dbt compile --generate-info-schema --static-analysis strict

FAQ: dbt compile이 데이터 플랫폼 연결이 필요한 이유

dbt compile은 프로젝트의 모든 모델에 대한 SQL을 준비하기 위해 필요한 정보(내부 조회 포함)를 모으려면 데이터 플랫폼 연결이 필요해요.

dbt compile은 source, model, test, analysis 파일에서 실행 가능한 SQL을 생성해요. dbt compile은 컴파일된 모델 SQL을 기존 테이블로 구체화하지 않는다는 점만 빼면 dbt run과 비슷해요. 따라서 구체화 전까지 dbt compile과 dbt run은 비슷한데, 둘 다 데이터 플랫폼 연결이 필요하고, 쿼리를 실행하며, execute 변수가 True로 설정되기 때문이에요. 하지만 고려할 몇 가지가 있어요:

dbt run 전에 dbt compile을 실행할 필요 없음

dbt에서 compile은 parse를 의미하지 않아요. parse는 작성한 YAML, 구성된 태그 등을 검증하기 때문이에요.

내부 조회(Introspective queries)

많은 모델의 컴파일된 SQL을 생성하려면 dbt는 데이터 플랫폼에 대해 내부 조회(즉, 데이터를 가져와서 무언가 하기 위해 dbt가 SQL을 실행해야 하는 것)를 실행해야 해요. 이 내부 조회에는 다음이 포함돼요:

  • 관계(relation) 캐시 채우기. 자세한 내용은 Create new materializations 가이드를 참고하세요. 캐싱은 인크리멘탈 모델이 데이터 플랫폼에 이미 존재하는지 같은 메타데이터 검사를 빠르게 해줘요.
  • SQL을 템플릿화하는 데 쓰는 run_query나 dbt_utils.get_column_values 같은 매크로를 해석(resolve)하는 것. dbt가 모델 SQL 컴파일 중에 그 쿼리들을 실행해야 하기 때문이에요.

dbt docs generate는 기본적으로 프로젝트를 컴파일하므로(--no-compile을 전달하지 않으면), run_query 같은 내부 매크로가 다른 컴파일 워크플로우처럼 문서 빌드 중에도 웨어하우스에 대해 실행돼요. DML이나 부수 효과(side-effecting)가 있는 SQL을 특정 dbt 명령어로 제한하고 싶다면 run_query와 flags.WHICH 사용법을 참고하세요.

데이터 플랫폼 연결이 없으면 dbt는 이런 내부 조회를 수행할 수 없고, dbt 워크플로우의 다음 단계에 필요한 컴파일된 SQL을 생성할 수 없어요.

인터넷이나 데이터 플랫폼 연결 없이도 프로젝트를 parse하고 프로젝트의 list 리소스를 사용할 수는 있어요. 프로젝트를 파싱하면 manifest를 생성하기에 충분하지만, 기록된 manifest에는 컴파일된 SQL이 포함되지 않는다는 점을 기억하세요. 프로젝트를 설정하려면 연결 프로필(profiles.yml)이 필요해요. 조건부 config에 {{target}}을 쓰거나, 올바른 SQL 방언을 선택하려면 어떤 플랫폼에 대해 실행하는지 알아야 하기 때문에 이 파일이 필요해요.

더 알아보기 (Learn more)