dbt ETL 파이프라인을 Databricks로 재지정하는 방법

점점 더 많은 팀이 락인(lock-in)이 없고 통합된 파이프라인, 내장된 Unity Catalog 거버넌스, 강력한 가성비를 제공하는 개방형 플랫폼인 Databricks Lakehouse에서 dbt 변환을 실행하고 있습니다.

dbt 프로젝트는 정상적으로 작동합니다. 모델이 컴파일되고, 테스트를 통과하며, 변환 로직은 특정 웨어하우스에 하드코딩되지 않고 버전 관리되는 SQL 및 YAML에 저장됩니다. dbt의 개방형 어댑터 프레임워크는 바로 이러한 디커플링을 위해 설계되었으므로, 하나의 클라우드 데이터 웨어하우스에서 다른 웨어하우스로 마이그레이션하는 것은 DAG나 비즈니스 로직을 다시 작성할 필요 없이 어댑터와 연결 구성을 변경하고 몇 가지 다이얼렉트(dialect)를 수정하는 수준의 작업입니다.

Databricks는 공동 개발된 dbt-databricks 어댑터, 개방형 레이크하우스 스토리지(Delta Lake 및 Apache Iceberg™), Unity Catalog, 그리고 Lakeflow Jobs를 통해 이를 지원합니다. 이를 통해 첫날부터 내장된 거버넌스와 강력한 가성비로 dbt를 실행할 수 있는 개방형 통합 플랫폼을 제공하므로, dbt 워크로드를 실행하기에 매우 적합합니다. 이것이 바로 3,000개 이상의 조직이 이미 Databricks에서 dbt를 실행하고 있는 이유입니다.

마이그레이션을 검토 중이시라면, 프로젝트를 처음부터 다시 빌드할 필요가 없다는 기쁜 소식이 있습니다. 이 글에서는 어댑터와 프로필을 교체하고, 몇 가지 SQL 차이점을 처리하며, 변환 로직을 dbt 내에 그대로 유지하면서 작동 중인 dbt 프로젝트를 Databricks로 다시 가리키도록(repoint) 설정하는 방법을 단계별로 알아봅니다.

dbt를 다시 가리키도록 설정하는 것이 강력한 마이그레이션 출발점인 이유

데이터 웨어하우스 마이그레이션 프로젝트에서 흔히 겪는 어려움은 모든 것을 한 번에 옮기려고 하다가 지연과 병목 현상이 발생하는 것입니다. 더 좋은 방법은 변환 레이어부터 시작하는 것이며, 이는 마이그레이션을 통해 비용 절감 효과를 빠르게 거둘 수 있는 지름길입니다.

dbt 프로젝트는 이미 모듈화되어 있고 테스트가 가능하므로 점진적인 마이그레이션을 진행하기에 이상적입니다. dbt를 Databricks로 다시 가리키도록 설정하면 다음과 같은 이점을 얻을 수 있습니다:

• 즉각적인 검증. 기존 웨어하우스와 새 웨어하우스 간의 출력을 모델별로 비교할 수 있습니다.
• 위험 감소. 변환 로직이 변경되지 않으므로 변수를 컴퓨팅 및 스토리지로 국한하여 격리할 수 있습니다.
• 작동하는 개념 증명(POC). 수집 또는 BI 레이어를 마이그레이션하기 전에 이해관계자가 Databricks에서 실행되는 쿼리를 확인할 수 있습니다.
• 빠른 가치 실현. 전체 기술 스택을 한 번에 마이그레이션하는 대신 변환 레이어를 먼저 이동하세요.

사전 요구 사항

범위: 이 가이드는 dbt 변환 레이어를 다시 가리키도록 설정하는 방법만 다룹니다. 소스 데이터가 이미 Databricks에 있고(Delta 또는 Iceberg 테이블로 로드되어 Unity Catalog에 등록됨) 카탈로그와 스키마가 존재한다고 가정합니다. 데이터 자체를 마이그레이션하고 Unity Catalog를 설정하는 것은 별도의 작업입니다. 이에 대해서는 Databricks 마이그레이션 가이드 및 Lakebridge를 참조하세요.

시작하기 전에 다음 사항을 준비하세요:

• SQL 웨어하우스가 프로비저닝된 Databricks 워크스페이스
• 대상 카탈로그 및 스키마가 생성된 Unity Catalog 설정, 그리고 소스(raw/bronze) 테이블이 이미 Delta 또는 Iceberg로 로드되어 UC에 등록되어 있어야 함
• 버전 관리 중인 기존 dbt 프로젝트 (dbt Core 1.8+ 또는 dbt Platform)
• 로컬에 설치된 Python 3.9+ (dbt Core 사용자의 경우)
• 액세스 자격 증명: Databricks 개인용 액세스 토큰 또는 OAuth 구성
• 선택 사항으로, Lakebridge를 사용하여 SQL 변환의 상당 부분을 자동화할 수 있습니다. 이는 소스 웨어하우스와 dbt 모델의 SQL을 스캔하고, 다이얼렉트 전용 SQL을 Databricks Lakehouse로 변환하며, 결과를 소스와 대조하여 조정합니다. dbt 자체를 마이그레이션하기보다는 dbt 프로젝트의 SQL을 다시 가리키도록 설정하며, 별도의 패턴(Lakehouse Federation + CTAS, COPY INTO 또는 Auto Loader)을 사용하는 데이터는 이동하지 않습니다.

이 예제에서 마이그레이션할 모델은 두 개의 소스 모델인 orders 및 order_items를 기반으로 구축된 표준 분석 팩트 테이블(fact table)입니다. 이 모델은 주문 수준 데이터를 집계하여 총 매출을 계산하고 지난 1년 동안의 개별 트랜잭션에 대해 판매된 제품 목록을 컴파일합니다. 

이 모델은 데이터 웨어하우스마다 다른 경우가 많은 몇 가지 일반적인 SQL 다이얼렉트 패턴(예: regexp_substr, div0 및 object_construct)을 사용하므로 좋은 예시가 됩니다. 여기에서 이러한 패턴을 처리하는 방법을 파악하고 나면 프로젝트의 다른 모든 모델에도 동일한 접근 방식을 적용할 수 있습니다.

1단계: 어댑터 설치 및 Databricks 대상 추가

이 섹션에서는 어댑터 설치, 네임스페이스 매핑, 다이얼렉트 차이점 처리 등 일회성 마이그레이션 작업을 다룹니다.

dbt-databricks 어댑터 설치

 dbt-databricks 어댑터는 dbt 프로젝트와 Databricks Lakehouse 웨어하우스 사이의 가교 역할을 합니다. dbt의 컴파일된 SQL을 Databricks 호환 쿼리로 변환합니다.

(dbt Platform 사용자의 경우: dbt 문서에 설명된 대로 새 환경에서 연결 유형으로 "Databricks"를 선택하면 어댑터가 자동으로 설치됩니다.)

`profiles.yml`에 Databricks 대상을 추가합니다. 기존 대상은 검증 중에 필요하므로 그대로 유지하세요. 그 옆에 두 번째 대상을 추가합니다:

연결 확인:

다음이 표시되어야 합니다:  Connection test: [OK connection ok].

여전히 연결할 수 없는 경우, Databricks + dbt 통합 가이드 및 dbt Databricks 프로필 참조 문서의 연결 문제 해결 단계를 따르세요.

전문가 팁: http_path은(는) 쿼리가 SQL 웨어하우스(dbt에 권장)에서 실행될지 아니면 다목적 클러스터에서 실행될지를 결정합니다. SQL 웨어하우스는 SQL 작업량이 많은 워크로드에 대해 더 나은 가성비를 제공합니다.

2단계: 테이블 소스가 Unity Catalog를 가리키도록 설정하고 테스트 추가

Databricks는 3단계 네임스페이스를 사용합니다: catalog.schema.table. fct_orders이(가) 읽는 sources.yml 항목을 업데이트합니다:

테스트를 포함하도록 schema.yml을(를) 업데이트합니다.

전문가 팁: database:을(를) 건너뛰면 쿼리가 워크스페이스의 기본 카탈로그에 저장됩니다. 명시적으로 설정하세요.

3단계: 첫 번째 컴파일

이제 모델에 대해 dbt compile을 실행합니다:

저희의 fct_orders 모델에서 아래와 같이 3개의 컴파일 오류가 발생했으며, 모두 다이얼렉트(dialect) 관련 오류입니다. 이는 예상된 결과이며, 이 세 가지가 대부분의 프로젝트에서 겪는 다이얼렉트 문제의 대표적인 예이기는 하지만 전부가 아닙니다. 규모가 더 큰 마이그레이션에서는 증분 모델 전략, 스냅샷, 직접적인 대체 기능이 없는 반정형 함수 등도 마주하게 됩니다. 

저희는 위치 매개변수가 있는 REGEXP_SUBSTR, 안전한 나눗셈을 위한 DIV0, JSON 빌드를 위한 OBJECT_CONSTRUCT과 같이 웨어하우스마다 다른 다이얼렉트 특정 패턴에 의존하는 예시 모델을 의도적으로 사용했습니다. 이렇게 하면 초기 dbt run 오류가 변환 프로세스의 가이드 역할을 하여, 이를 이식 가능한 매크로와 Databricks 친화적인 SQL로 변환하는 방법을 보여줌으로써 프로젝트의 나머지 부분에도 동일한 수정 사항을 적용할 수 있게 됩니다. 이를 보여드리기 위해 각 오류와 근본 원인, 해결 방법을 단계별로 안내해 드리겠습니다. 오류를 살펴보기 전에 이식성에 대해 한 가지 말씀드리자면, 함수에 이식 가능한 대체 기능이 있는 경우 dbt의 교차 데이터베이스 매크로(dbt.* 네임스페이스)를 사용하면 한 번만 작성해도 모든 웨어하우스에서 컴파일할 수 있으므로 표준화 시 도입할 가치가 있습니다. 각 오류와 해결 방법을 살펴본 다음, 대규모 프로젝트에서 이 변환을 자동화하는 방법을 보여드리겠습니다.

오류 1: REGEXP_SUBSTR 다이얼렉트 호환되지 않음

Databricks는 Apache SQL 다이얼렉트를 따르며 REGEXP_SUBSTR에 대해 2개의 매개변수만 지원합니다.

해결 방법: Databricks의 네이티브 regexp_extract() 함수를 사용합니다.

Genie Code가 이 변환을 대신 수행하도록 할 수도 있습니다. 이와 같은 다이얼렉트 격차를 해결하는 것이 바로 Genie Code가 가장 잘하는 일입니다. 여기서는 변경되는 내용을 확인하실 수 있도록 세 가지 모두 수동으로 진행하겠습니다.

오류 2: DIV0 (안전한 나눗셈)

근본 원인: 일부 웨어하우스는 0으로 나눌 때 오류를 발생하는 대신 0을 반환하기 위해 DIV0을 사용합니다.

해결 방법: 패키지에 dbt_utils를 추가하고 내장된 safe_divide 함수를 사용합니다.

오류 3: object_construct (JSON 빌더)

루틴 `object_construct`를 확인할 수 없습니다.

해결 방법: Databricks named_struct 함수를 사용합니다.

컴파일 재실행:

성공적으로 컴파일되었습니다. 이 모델의 총 다이얼렉트 변경 사항: dbt_utils package installed (안전한 나눗셈용), regexp_substr call converted to regexp_extract, div0 호출이 dbt_utils.safe_divide()(으)로 대체됨, object_construct call converted에서 named_struct(으)로 변경.

세 개의 함수를 수동으로 수정하는 것은 쉽습니다. 하지만 실제 dbt 프로젝트에는 수백 또는 수천 개의 모델이 있으며, 이러한 다이얼렉트 격차는 AI 도구가 자동으로 해결해 줍니다. Genie Code는 다이얼렉트 특정 SQL을 변환하고 에디터에서 바로 이러한 수정을 처리하므로, 개발자는 각 수정 사항을 직접 작성하는 대신 변환된 내용을 검토하는 데 시간을 집중할 수 있습니다.

4단계: 첫 번째 실행

컴파일이 성공적으로 완료되면(초록색 표시), 모델과 기존 테스트를 실행합니다:

모델 빌드와 테스트가 모두 통과했습니다. 전문가 팁:

• 실행 시간(Runtime). 이를 기록해 두세요. 다음 단계에서 이전 웨어하우스와 비교하게 됩니다.
• 숫자 열의 테스트 실패. equality 또는 accepted_values 테스트가 실패하는 경우, 이는 로직 버그가 아니라 거의 항상 부동 소수점 정밀도 때문입니다.

5단계: 기존 웨어하우스와 행 단위로 검증하기

녹색 dbt run은 SQL이 실행됨을 증명합니다. 이제 기존 웨어하우스와 Databricks 간의 출력을 일치시켜야 합니다. 행 단위로 비교하려면 dbt-audit-helper을 사용하세요.

설치:

양쪽 웨어하우스에서 fct_orders을 비교합니다. analyses/compare_fct_orders.sql에서:

Databricks에서 실행합니다(비교를 위해 기존 출력을 Databricks에 복제했거나 교차 웨어하우스 비교를 실행한다고 가정):

예상 결과:

참고: 이 예시들은 가장 일반적인 패턴을 다루고 있지만 모든 경우를 포함하지는 않습니다. 추가적인 불일치(예: 문자열 트리밍, 콜레이션 또는 사용자 정의 UDF 동작)가 발생하는 경우, summarize=false를 설정하여 샘플 행을 구체화하고, in_a과 in_b가 다른 몇 개의 기본 키를 검사한 후, 모델 또는 매크로를 수정하고 100% 일치할 때까지 다시 실행하세요.

실행 결과: fct_orders가 정확히 일치했습니다.

6단계: Databricks에 배포하기

dbt를 위한 별도의 오케스트레이션 레이어를 유지 관리하는 대신, Lakeflow Jobs를 사용하여 단일 파이프라인에서 업스트림 수집 및 다운스트림 작업과 함께 dbt를 실행할 수 있습니다. dbt는 Jobs 내에서 기본 지원되는 태스크 유형이므로 외부 오케스트레이터나 맞춤형 Docker 이미지가 필요하지 않습니다.

Job 생성:

1. Workspace → Jobs & Pipelines → Create Job
2. 태스크 유형: dbt
3. Git 소스: 사용자의 dbt 리포지토리
4. 명령:

5. SQL 웨어하우스: 프로덕션 웨어하우스
6. 웨어하우스 카탈로그: 테이블이 기록될 카탈로그: dev
7. 웨어하우스 스키마: 테이블이 기록될 스키마: analytics
8. 일정: 원하는 주기

Jobs가 기본적으로 제공하는 혜택:

• 완전 관리형 — 구매, 보안 설정 또는 유지 관리할 추가 인프라가 없음
• 업스트림 수집 파이프라인 및 Power BI 새로 고침과 같은 다운스트림 작업과 함께 dbt 태스크를 실행할 수 있는 단일 파이프라인 생성 기능

7단계: 전환 및 서비스 중단

dbt 프로젝트를 검증하고 Databricks에 배포했다면, 다음 단계는 프로덕션 트래픽을 통제된 방식으로 Databricks로 이동하고, 신속한 롤백 경로를 유지하며, 필요 이상으로 두 개의 웨어하우스에 비용을 지불하지 않도록 하는 것입니다.

다음 체크리스트를 참고하세요:

1. profiles.yml에서 프로덕션 대상을 전환하여 prod이 Databricks를 가리키도록 합니다. 이제 모든 새로운 프로덕션 실행은 Databricks에 기록됩니다.
2. CI/CD 자격 증명을 업데이트하여 PR 검사가 기존 웨어하우스가 아닌 Databricks 스테이징 카탈로그를 대상으로 실행되도록 합니다.
3. system.billing.usage을 통해 비용을 모니터링하여 Databricks 지출 프로필을 확인합니다.
4. 롤백 기간이 종료되고 Databricks가 프로덕션 환경에서 안정적이라고 확신하면 기존 대상을 서비스 중단합니다.

프로젝트의 나머지 부분으로 확장하기

방금 수행한 작업의 대부분은 어댑터 설치, profiles.yml 대상 설정, 소스 네임스페이스 변경 등 일회성 작업입니다. 이러한 작업이 완료되면 다음 모델의 대상을 재지정하는 데는 점진적인 다이얼렉트(dialect) 수정 비용만 발생합니다.

일부 패턴은 다이얼렉트 전환 이상의 작업이 필요하며, 규모를 확장하면서 이러한 패턴을 접하게 됩니다.

• 증분 모델(Incremental models) — 증분 전략은 플랫폼마다 다릅니다. 소스에서 사용하는 전략이 Databricks 증분 전략과 1:1로 매핑되지 않을 수 있으므로, 전략을 다시 선택하고 증분 로직을 재검증해야 합니다.
• 스냅샷(Snapshots) — 스냅샷 로직의 대상을 재지정하고, 이와 별개로 기존의 기록 스냅샷 데이터를 가져와서 이력을 잃지 않도록 해야 합니다.
• 반정형 및 특수 함수 — 일부 소스 함수는 직접적으로 대응되는 Databricks 함수가 없으므로 한 줄의 코드 변경이 아닌 재작성이나 매크로가 필요합니다.

이와 같은 까다로운 작업의 경우, 전체 마이그레이션 가이드를 참고하세요.

그런 다음 소규모 배치로 마이그레이션하고 DAG 순서(소스, 스테이징, 중간, 마트 순)로 작업하여 각 배치가 이미 이동한 모델에 대해 정상적으로 검증되도록 합니다. 두 대상을 병렬로 실행하고 audit-helper를 사용하여 모든 모델이 일치할 때까지 비교합니다. 마지막 모델이 성공(녹색)하면 전체 프로젝트를 전환합니다. 이 가이드는 대상 재지정에 대한 간소화된 안내서이며, 마이그레이션의 전체 범위는 당사의 공개 마이그레이션 가이드에서 다룹니다. 

결론

dbt의 대상을 Databricks로 재지정하는 것은 웨어하우스 마이그레이션을 시작하는 실용적이고 위험성이 낮은 방법입니다. 모델과 테스트는 그대로 유지되며 실행 위치만 변경됩니다. 또한 Delta Lake 및 Apache Iceberg™와 같은 오픈 소스 형식 및 표준의 이점을 누릴 수 있으며, 다운스트림 AI 작업도 지원할 수 있는 플랫폼 상에서 Unity Catalog가 거버넌스 및 계보(lineage)를 제공합니다. 하나의 모델로 시작하여 출력을 비교한 다음, Databricks를 dbt 프로젝트의 기본 홈으로 안심하고 설정할 수 있을 때까지 확장해 보세요.

시작할 준비가 되셨나요? 

1. Databricks 무료 체험판 설정
2. dbt-databricks 어댑터 설치
3. Databricks 레이크하우스 웨어하우스를 대상으로 첫 dbt 컴파일을 실행합니다. 그 후, Databricks 문서를 참조하여 프로덕션 환경에서 dbt 모델을 실행하기 위한 Databricks Job을 배포합니다.

Databricks와 함께 dbt를 사용하는 방법에 대한 자세한 내용은 GitHub에서 dbt-databricks 어댑터를 살펴보세요.

(이 글은 AI의 도움을 받아 번역되었습니다. 원문이 궁금하시다면 여기를 클릭해 주세요)