패키지 ref 검색 순서

패키지 ref 검색 순서 (Package ref search order)

require_ref_searches_node_package_before_root 플래그는 패키지 내에서 정의된 ref() 호출을 dbt가 해결할 때의 검색 순서를 제어해요. 패키지 정의 모델을 루트 프로젝트보다 먼저 검색할지 결정해요.

출처: 문서

본문

require_ref_searches_node_package_before_root dbt v1 Latest dbt v1
Introduced 2025.12 1.11.0
Matured (default → true) — —
Removed — —

require_ref_searches_node_package_before_root 플래그는 패키지 내에 정의된 ref() 호출을 dbt가 해결할 때의 검색 순서를 제어해요.

이 플래그는 v1 Latest와 dbt v1.11에서 기본값이 false예요. 패키지 모델에서 ref()를 해결할 때 dbt는 참조된 모델을 루트 프로젝트에서 먼저 검색하고, 그다음 모델이 정의된 패키지에서 검색해요.

예를 들어, 다음 모델이 패키지 my_package에 있고 프로젝트 my_project가 임포트한다고 해요:

my_package/model_downstream.sql

select * from {{ ref('model_upstream') }}

기본적으로 dbt는 model_upstream을 이 순서로 검색해요:

  • my_project(루트 프로젝트)에서 먼저
  • 그다음 my_package(모델이 정의된 곳)

require_ref_searches_node_package_before_root 플래그를 true로 설정하면 dbt는 모델이 정의된 패키지를 루트 프로젝트보다 먼저 검색해요.

같은 예시에서 dbt는 model_upstream을 이 순서로 검색해요:

  • my_package(모델이 정의된 곳)에서 먼저
  • 그다음 my_project(루트 프로젝트)

현재 기본 동작은 예기치 않은 의존성 순환(dependency cycles)을 초래할 수 있기 때문에 dbt의 버그로 간주돼요. 하지만 오랫동안 유지된 동작이므로, 기본값을 바꾸려면 기존 프로젝트를 깨지 않도록 require_ref_searches_node_package_before_root를 true로 설정해야 해요.

더 알아보기 (Learn more)