Databricks 어댑터 동작 변경

Databricks 어댑터 동작 변경 (Databricks adapter behavior changes)

dbt-databricks 어댑터 전용의 동작 변경 플래그들을 다뤄요. use_user_folder_for_python, use_materialization_v2, use_managed_iceberg, use_replace_on_for_insert_overwrite, use_describe_as_json_for_relation_metadata 같은 플래그가 있어요.

출처: 문서

본문

다음은 dbt-databricks 전용인 현재 동작 변경 플래그들이에요:

Flag	`dbt-databricks`: Intro	`dbt-databricks`: Maturity	Status
`use_info_schema_for_columns`	1.9.0	N/A	Removed in 1.11.0
`use_user_folder_for_python`	1.9.0	1.11.0	Default changed to `true`
`use_materialization_v2`	1.10.0	TBD	Active
`use_managed_iceberg`	1.11.0	1.12.0	Active
`use_replace_on_for_insert_overwrite`	1.11.0	1.12.0	Active, defaults to `true`
`use_describe_as_json_for_relation_metadata`	1.12.0	TBD	Active, defaults to `false`

컬럼용 정보 스키마 사용 (Use information schema for columns)

use_info_schema_for_columns 플래그는 dbt-databricks v1.11.0부터 제거됐어요. 어댑터는 이제 DBR 16.2+에서 사용 가능한 DESCRIBE EXTENDED ... AS JSON을 사용해 복잡한 타입 정보를 효율적으로 가져와 이 플래그의 필요성을 없앴어요. 프로젝트 구성에서 여전히 이 플래그를 쓰고 있다면 안전하게 제거할 수 있어요. 새 접근 방식은 더 나은 성능을 제공하고 information_schema에서 필요했던 REPAIR TABLE 연산이 필요 없어요.

레거시 문서

이 내용은 dbt-databricks v1.11 이하 버전에 적용돼요

use_info_schema_for_columns 플래그는 1.9와 1.10 버전에서 기본값이 false였어요.

이 플래그를 true로 설정하면 Unity Catalog 테이블의 컬럼 메타데이터를 가져올 때 describe extended 대신 information_schema를 사용했어요. 이 설정은 타입이 복잡한 struct일 때 describe extended가 정보를 잘라내는 문제를 피하는 데 도움이 됐어요.

from_json으로 JSON을 처리해 복잡한 타입을 만든다면 대안이 있어요: parse_json을 사용해 컬럼을 variant 타입으로 만들기. variant 타입은 타입 잘림 문제를 피하면서 성능 면에서 합리적인 대안이 될 수 있어요.

Python 모델 노트북용 사용자 폴더 사용 (Use user's folder for Python model notebooks)

dbt-databricks v1.11.0부터 use_user_folder_for_python 플래그는 기본값이 **true**예요.

use_user_folder_for_python 플래그는 업로드된 Python 모델 노트북이 Databricks 어디에 저장될지 제어해요:

true (v1.11+ 기본값): 노트북이 /Users/{{current user}}/{{catalog}}/{{schema}}/에 기록돼요.
false (v1.9-v1.10 기본값): 노트북이 /Shared/dbt_python_models/{{schema}}/에 기록돼요.

Databricks는 거버넌스 모범 사례에 맞지 않는다며 Shared 폴더에 쓰기를 deprecate했어요. 사용자별 폴더를 쓰면 더 나은 격리, 접근 제어를 제공하고 Unity Catalog 보안 모델에 부합해요.

백워드 호환성을 위해 레거시 동작을 유지하려면 dbt_project.yml에서 이 플래그를 명시적으로 false로 설정할 수 있어요:

flags:
  use_user_folder_for_python: false

재구조화된 materialization 사용 (Use restructured materializations)

use_materialization_v2 플래그는 기본값이 false이며 실험 단계인 동안 dbt-databricks의 핵심 materialization의 상당한 재작성을 보호해요.

true로 설정하면 dbt-databricks가 모든 모델 타입(뷰, 테이블, 인크리멘탈, 시드)에 업데이트된 로직을 사용해요. 또한 보다 세밀한 제어를 위한 추가적 선택적 구성 옵션을 활성화해요:

view_update_via_alter — 활성화하면 이 구성이 create나 replace로 교체하는 대신 alter view로 뷰를 제자리에서 업데이트하려고 해요.
use_safer_relation_operation — 활성화하면(그리고 view_update_via_alter가 설정되지 않았다면) 이 구성이 relation을 스테이징하고 rename 연산을 사용해 장애가 테이블이나 뷰의 라이브 버전을 방해하지 않도록 dbt 모델 업데이트를 더 안전하게 해요.

이 구성들은 이 플래그의 핵심 이점(더 나은 성능, 컬럼/제약 기능처럼)을 받는 데 필수는 아니지만, materialization이 동작하는 방식을 더 크게 바꾸기 때문에 플래그 뒤에 게이트돼 있어요.

v1.11.0에서 이 플래그는 기본값 false로 유지돼요. 새 materialization의 원자성(전부 아니면 전무 업데이트) 부족에 대한 피드백을 바탕으로 자동 활성화하지 않을 거예요. 원자성을 잃지 않고 같은 이점을 얻을 다른 방법을 모색할 거예요.

새 materialization 접근 방식의 원자성 부족에 대한 피드백을 고려해, 이 플래그를 true로 뒤집지 않을 거예요. 대신 원자성을 유지하면서 같은 이점을 제공할 새로운 방법을 조사할 거예요.

Seed materialization의 변경

시드 materialization은 트랜잭션 연산 같은 Databricks가 지원하지 않는 메서드 호출을 제거하는 것이 주된 차이이므로, 이전과 새 materialization 간 차이가 가장 작아야 해요.

View materialization의 변경

use_materialization_v2 플래그가 true로 설정되면 대상 위치에서 기존 relation을 감지할 때 뷰 materialization을 처리하는 방법을 사용자화할 수 있는 두 가지 모델 구성 옵션이 있어요.

view_update_via_alter — create나 replace로 교체하는 대신 alter view로 뷰를 제자리에서 업데이트해요. 이렇게 하면 뷰의 히스토리가 연속되고 메타데이터를 유지하며 Unity Catalog 호환성에 도움이 돼요. 구성 예시:

schema.yml

models:
  - name: market_summary
    config:
      materialized: view
      view_update_via_alter: true
    
    columns:
      - name: country
        data_tests:
          - unique
          - not_null
...

그러므로 뷰의 설명을 바꿀 때마다 뷰를 교체해야 해요.

use_safer_relation_operations — 활성화하면(그리고 view_update_via_alter가 설정되지 않았다면) 이 구성이 스테이징 위치에 새 relation을 만들고, 기존 relation과 교체하고, 이후에 이전 relation을 삭제해 dbt 모델 업데이트를 더 안전하게 해요. 구성 예시:

schema.yml

models:
  - name: market_summary
    config:
      materialized: view
      use_safer_relation_operations: true
    
    columns:
      - name: country
        data_tests:
          - unique
          - not_null
...

이 접근 방식은 기본 dbt 뷰 materialization과 동등하지만, 대안에 비해 추가 UC 객체를 만들 거예요. 이 구성은 어떤 materialization에도 원자적 'create or replace...'를 사용하지 않으므로, Unity Catalog에서 객체의 히스토리가 예상대로 동작하지 않을 수 있어요. 이 모델 구성을 널리 사용하기 전에 신중히 고려해요.

Table materialization의 변경

뷰처럼 이러한 materialization 변경은 비용을 증가시킬 수 있어요. 다른 dbt 어댑터의 materialization과 일관되게 더 많은 임시 객체가 사용돼요. 이 변경의 가격 영향을 정량화할 데이터가 충분하지 않기 때문에 이러한 변경을 부분적으로 실험적이라고 간주해요. 하지만 이점은 성능, 안전성 개선과 기존 materialization으로는 제공할 수 없는 기능의 잠금 해제예요.

use_materialization_v2가 true로 설정되면 모든 materialization 경로가 업데이트돼요. 핵심 변경은 테이블 생성이 테이블에 행을 삽입하는 것과 분리된다는 점이에요. 이 분리는 테이블 주석 설정 성능을 크게 개선해요 — 생성 시점에 주석을 추가하는 것이 별도의 alter table 문보다 빠르기 때문이에요. 또한 Databricks에서 생성과 삽입을 한 단계로 하면 주석 설정이 불가능한 호환성 문제를 해결해요.

추가로 이 변경 덕분에 생성 중 데이터 삽입과 호환되지 않는 다른 컬럼 기능(컬럼 레벨 마스크처럼)을 지원할 수 있게 됐어요. 이러한 기능은 버전 1.10.0에 포함되지는 않지만 향후 릴리즈에서 추가될 수 있어요.

제약 (Constraints)

여러 기능 릴리즈 동안 dbt-databricks는 dbt의 제약 구현과 자체 대안인 이전 버전 persist_constraints를 모두 지원했어요. use_materialization_v2 플래그로 persist_constraints를 deprecate하기 시작하고 dbt의 네이티브 제약 지원으로 완전히 전환하고 있어요.

새로운 개선 중 하나는 기본 키와 외래 키에서 expression 필드를 지원하는 것으로, RELY를 사용해 Databricks 최적화 프로그램이 제약을 활용해 쿼리를 재작성할 수 있게 말하는 것 같은 추가 Databricks 옵션을 전달할 수 있게 해요.

create와 insert를 분리하는 것은 제약이 동작하는 방식도 바꿔요. 이전에는 데이터와 함께 테이블을 만든 다음 제약을 적용했어요. 새 데이터가 제약을 위반하면 실행이 실패했지만 — 그 시점에는 이미 이전 실행의 유효한 테이블을 교체해 버렸어요.

뷰처럼 use_safer_relation_operations 플래그로 성능과 안전성 사이를 선택할 수 있지만, 설정과 관계없이 새 materialization 접근 방식은 제약 위반이 대상 테이블에 들어가지 않도록 보장해요.

`use_safer_relation_operations`

테이블에서 이 모델 구성을 사용하면 먼저 스테이징 테이블을 만들어요. 테이블에 데이터를 성공적으로 삽입한 뒤, 대상 materialization을 교체하도록 이름을 바꿔요. Databricks는 롤백을 지원하지 않으므로 이는 더 안전한 접근 방식이에요 — 이름 바꾸기 전에 무언가 실패하면 원래 테이블은 그대로 유지돼요. 그렇게 되면 그 테이블에 의존하는 노출이나 작업 흐름이 그동안 깨질 걱정 없이 문제를 해결할 시간을 갖게 돼요.

이 구성이 false(기본값)로 설정되면 대상 테이블은 여전히 제약 위반 데이터를 절대 포함하지 않지만, 삽입이 제약 때문에 실패하면 비어 있을 수 있어요. 핵심 차이는 대상을 직접 교체하느냐 스테이징 후 이름 바꾸기 방식을 쓰느냐예요.

뷰처럼 추가 임시 객체를 사용하면 자체 히스토리가 있는 UC 객체를 더 많이 만드는 비용이 들어요. 이 동작이 필요한지 신중히 고려해요.

Incremental materialization의 변경

Table materialization 섹션에서 이뤄진 모든 변경은 Incremental materialization에도 적용돼요.

또한 새 구성 incremental_apply_config_changes를 추가했어요.

이 구성은 인크리멘탈 실행 중 tags, tblproperties, 주석 같은 것에 변경을 적용할지 제어하게 해줘요. 많은 사용자가 dbt가 덮어쓰지 않고 Databricks에서 AI 생성 주석 같은 테이블 메타데이터를 구성할 수 있는 기능을 원했어요. 이전에는 dbt-databricks가 인크리멘탈 실행 중 감지된 변경을 항상 적용했어요.

V2 materialization에서는 이제 incremental_apply_config_changes를 false로 설정해 그 동작을 멈출 수 있어요. (기본값은 이전 동작과 일치하도록 true예요.)

구성 예시:

schema.yml

models:
  - name: incremental_market_updates
    config:
      materialized: incremental
      incremental_apply_config_changes: false
...

관리형 Iceberg 사용 (Use managed Iceberg)

table_format을 iceberg로 설정하면 use_managed_iceberg 플래그가 테이블이 생성되는 방식을 제어해요. 기본적으로 이 플래그는 false로 설정되고 dbt는 UniForm 테이블을 만들어요. true로 설정하면 dbt는 관리형 Iceberg 테이블을 만들어요.

`insert_overwrite` 전략에 `replace on` 사용

use_replace_on_for_insert_overwrite 플래그는 insert_overwrite 전략을 사용하는 인크리멘탈 모델에 대해 dbt가 생성하는 SQL 구문을 제어해요. 이 플래그는 기본값이 true이며 insert into ... replace on 구문으로 동적 파티션/클러스터 덮어쓰기를 수행해요 — 클러스터 컴퓨트에서와 같은 동작이에요. 플래그가 false로 설정되면 SQL 웨어하우스에서 사용할 때 insert_overwrite가 전체 테이블을 truncate해요. 이 플래그는 클러스터 컴퓨트에서는 관련 없어요 — 클러스터 컴퓨트에서 insert_overwrite의 동작은 항상 동적 파티션/클러스터 덮어쓰기였기 때문이에요.

Flag value	SQL generated	Description
`true` (default)	`INSERT INTO ... REPLACE ON`	최신 권장 Databricks 구문으로 일치하는 파티션을 교체해요.
`false`	`INSERT OVERWRITE`	더 오래된 Spark 구문으로 파티션을 덮어써요. Spark 세션 설정에 따라 달라요.

이전에 기존 메타데이터를 버리지 않고 전체 테이블 교체를 얻기 위해 이 동작에 의존했다면, 파티션이나 liquid clustering 클러스터를 사용하지 않는 한 플래그를 true로 설정해도 그 동작은 계속 존재해요.

이러한 데이터 레이아웃 최적화는 대략 1 TB 이상인 테이블에서만 유의미한 효과를 내는 경향이 있고, 그 시점에는 모든 데이터의 정기적 교체가 최선의 접근 방식이 아닐 가능성이 커요.

relation 메타데이터에 `DESCRIBE AS JSON` 사용

use_describe_as_json_for_relation_metadata 플래그는 Databricks 테이블과 뷰에 대해 dbt가 제약(기본 키, 외래 키, non-null), 컬럼 마스크, 행 필터, 뷰 설명 같은 relation 레벨 메타데이터를 가져오는 방식을 제어해요. 두 값을 허용해요:

false (기본값): dbt가 relation당 메타데이터를 가져오기 위해 여러 information_schema 쿼리를 발행해요.
true: dbt가 relation당 단일 DESCRIBE TABLE EXTENDED ... AS JSON 호출로 이 모든 메타데이터를 가져와요.

이 플래그를 활성화하면 제약, 컬럼 마스크, 행 필터가 있는 모델이 많은 프로젝트에서 유용해요. dbt가 발행해야 하는 메타데이터 쿼리 수가 줄어들기 때문이에요.

요구 사항

dbt는 다음이 모두 참일 때만 특정 relation에 DESCRIBE AS JSON 경로를 사용해요:

relation이 Unity Catalog에 있음 (Hive metastore 아님).
relation이 외부 테이블이 아님.
컴퓨트가 SQL 웨어하우스이거나 DBR 17.3 이상에서 실행됨.

조건 중 하나라도 충족되지 않으면 dbt는 해당 relation에 대해 information_schema 쿼리로 폴백해요. 폴백은 relation별로 발생하므로 혼합 컴퓨트 타입의 프로젝트에서도 안전하게 플래그를 활성화할 수 있어요.

더 알아보기 (Learn more)

동작 변경(Behavior changes) — 동작 변경 플래그 개요
관리형 Iceberg — Databricks 관리형 Iceberg
UniForm — 범용 포맷

Databricks 어댑터 동작 변경