Microsoft Fabric Data Warehouse 설정

Microsoft Fabric Data Warehouse 설정

dbt-fabric 어댑터(Microsoft Fabric Data Warehouse용)에 특화된 구성 옵션을 다루는 페이지예요. 지원 materialization, incremental 전략(merge, microbatch 포함), 크로스 웨어하우스 참조, 웨어하우스 스냅샷, 프로필 설정 등을 살펴볼 수 있어요.

출처: 문서

본문

Materializations

T-SQL이 중첩 CTE를 지원하지 않기 때문에 ephemeral materialization은 지원되지 않아요. 아주 단순한 ephemeral 모델을 다룰 때는 어떤 경우엔 동작할 수도 있어요.

테이블 (Tables)

테이블은 dbt-fabric의 기본 materialization이에요. 모델을 table로 구성하면, dbt는 매 실행마다 Fabric Data Warehouse에서 테이블을 생성하거나 교체해요.

모델 config

models/example.sql

{{
    config(
        materialized='table'
        )
}}

select *
from ...

프로젝트 config

dbt_project.yml

models:
  your_project_name:
    materialized: view
    staging:
      materialized: table

제한 사항: 모델 materialization에서는 중첩 CTE가 지원되지 않아요. 여러 개의 중첩 CTE를 사용하는 모델은 컴파일 또는 실행 중에 실패할 수 있어요.

테이블 클론 (Table Clone)

table_clone materialization은 Fabric의 클로닝 기능을 사용해 기존 테이블의 물리적 복사본을 만들어요. 버전 관리, 브랜칭, 또는 스냅샷 같은 워크플로에 유용해요.

{{ config(materialized='table_clone', clone_from='staging_table') }}
select * from staging_table

참고:

• 소스 테이블은 타깃 웨어하우스에 존재해야 해요.
• 클로닝은 생성 시점의 스키마와 데이터 상태를 보존해요.
• 테스트나 롤백을 위해 빠른 zero-copy 복제가 필요한 시나리오에 이상적이에요.

Seeds

기본적으로 dbt-fabric은 seed 파일을 400행 단위 배치로 삽입하려 해요. 이 값이 Microsoft Fabric Data Warehouse의 2100 파라미터 한도를 초과하면, 어댑터가 자동으로 가능한 가장 안전한 값으로 제한해요.

다른 기본 seed 값을 설정하려면 프로젝트 구성에서 max_batch_size 변수를 설정할 수 있어요.

dbt_project.yml

vars:
  max_batch_size: 200 # Any integer less than or equal to 2100 will do.

뷰 (Views)

view materialization으로 뷰를 만들 수 있어요:

{{ config(materialized='view') }}
select * from source_data

전역적으로도 설정할 수 있어요:

models:
  my_project:
    +materialized: view

제한 사항: 모델 materialization에서는 중첩 CTE(Common Table Expression)가 지원되지 않아요. 여러 개의 중첩 CTE를 사용하는 모델은 컴파일 또는 실행 중에 실패할 수 있어요.

Snapshots

소스 테이블의 컬럼은 어떤 제약 조건도 가질 수 없어요. 예를 들어 어떤 컬럼에 NOT NULL 제약 조건이 있으면 오류가 발생해요.

인덱스 (Indexes)

Microsoft Fabric Data Warehouse는 인덱스를 지원하지 않아요. configuration으로 제공된 인덱스는 어댑터가 무시해요.

자동 프로비저닝을 포함한 Grants (Grants with auto provisioning)

Microsoft Fabric Data Warehouse는 현재 자동 프로비저닝을 포함한 grants를 지원하지 않아요.

Incremental 모델

Incremental materialization은 여러 전략으로 지원돼요. dbt-fabric에서 **기본 전략은 merge**이며, v1.9.7에서 도입됐어요. 다른 지원 전략으로는 append, delete+insert, microbatch가 있어요.

Merge (기본값)

merge 전략은 구성된 unique_key를 기준으로 기존 레코드를 자동으로 업데이트하고 새 레코드를 삽입해요.

{{
  config(
    materialized='incremental',
    unique_key='id'
  )
}}
select * from source_table
{% if is_incremental() %}
  where updated_at > (select max(updated_at) from {{ this }})
{% endif %}

Append

새 레코드를 기존 데이터셋에 추가해요.

{{
  config(
    materialized='incremental',
    incremental_strategy='append'
  )
}}
select * from new_data

Delete+Insert

unique_key를 기준으로 삭제하고 다시 삽입해요.

{{
  config(
    materialized='incremental',
    incremental_strategy='delete+insert',
    unique_key='id'
  )
}}
select * from updated_data

Microbatch

microbatch 전략은 이벤트 타임스탬프 컬럼을 사용해 데이터를 제한된 시간 간격으로 처리해요.

{{
  config(
    materialized='incremental',
    incremental_strategy='microbatch',
    event_time='event_timestamp',
    batch_size='1 day'
  )
}}

select * from raw_events

참고

• event_time은 유효한 타임스탬프 컬럼이어야 해요.
• dbt는 각 배치를 독립적으로 처리해, 대용량 시계열 데이터셋을 효율적으로 incremental 새로고침할 수 있어요.
• unique_key를 지정하지 않으면 dbt-fabric은 append로 기본 설정돼요.

자세한 내용은 Incremental models을 참고하세요.

권한 (Permissions)

현재 데이터베이스 레벨에서 작업하려면 Microsoft Entra ID(사용자 또는 서비스 주체)가 Fabric Workspace admin이어야 해요. 세분화된 액세스 제어는 향후 도입될 예정이에요.

크로스 웨어하우스 참조 (Cross-warehouse references)

dbt-fabric 어댑터는 source() 또는 ref() 매크로를 사용한 크로스 웨어하우스 쿼리를 지원해요.

select * from {{ source('sales_dw', 'transactions') }}
union all
select * from {{ ref('customer_dim') }}

해당 모델이나 source 정의가 다른 Fabric Warehouse를 참조하도록 올바른 database: 파라미터를 지정해야 해요.

sources.yml 예시:

sources:
  - name: sales_dw
    database: saleswarehouse
    schema: sales
    tables:
      - name: transactions

크로스 웨어하우스 참조나 웨어하우스 스냅샷을 사용하려면, 여기에 구성된 ID가 참조하는 모든 Fabric Warehouse에 접근 권한이 있어야 해요.

웨어하우스 스냅샷 (Warehouse snapshots)

Microsoft Fabric 웨어하우스 스냅샷은 특정 시점의 웨어하우스 읽기 전용 복사본이며 최대 30일 동안 보관돼요. ELT 프로세스가 웨어하우스를 업데이트하는 동안에도 분석가들이 안정적인 데이터셋을 조회할 수 있게 해줘요. 스냅샷의 타임스탬프를 앞으로 옮기면 변경 사항이 한 번에(원자적으로) 적용돼요.

dbt-fabric은 웨어하우스 스냅샷을 지원해서, dbt 실행 사이에 Fabric Data Warehouse 객체의 변경 사항을 추적하는 데 도움이 돼요. Fabric은 dbt run, dbt build, dbt snapshot 명령을 실행하기 전과 후에 스냅샷을 자동으로 만들어요.

이를 사용하려면 profiles.yml에 workspace_id와 웨어하우스 스냅샷 이름이 포함되어야 해요. 그래야 dbt가 스냅샷을 웨어하우스의 하위 항목으로 만들 수 있어요.

자세한 내용은 여기를 참고하세요.

fabric_dw:
  target: dev
  outputs:
    dev:
      type: fabric
      server: "<your-fabric-server-name>"
      database: "<your-warehouse-name>"
      schema: "<default-schema>"
      authentication: CLI
      workspace_id: e4487eff-d67d-4b58-917c-ffbb61a5c05f
      warehouse_snapshot_name: dbt-dwtests-snpshot

동작 (Behavior)

• dbt 연산(run, build, snapshot) 전에 어댑터가 영향받는 테이블의 사전 상태를 캡처해요.
• 실행 후 스냅샷 타임스탬프와 함께 웨어하우스 스냅샷이 만들어져요.

추가 세부 사항:

• dbt snapshot 문서
• Fabric 어댑터 snapshots 참조

dbt-utils

현재는 지원되지 않아요. 다만 dbt-fabric은 일부 dbt-utils 매크로를 제공해요. tsql-utils 패키지를 확인해 보세요.

더 알아보기 (Learn more)

• Fabric 웨어하우스 스냅샷 관련 Microsoft 문서.
• incremental 모델 전략에 대한 자세한 내용은 Incremental models을 참고하세요.