DuckDB 구성

DuckDB 구성 (DuckDB configurations)

이 문서는 dbt-duckdb에 특화된 리소스 구성을 설명해요. 시크릿 관리자, fsspec 기반 클라우드 스토리지, ATTACH 옵션, DuckLake, 그리고 점진적 전략(append, delete+insert, merge, microbatch)을 강사 목소리로 살펴볼게요. 프로필 설정과 연결 옵션은 Connect DuckDB를, 일반적인 dbt 개념은 Materializations와 Incremental models를 참고하세요.

일부 기능은 최소 버전의 dbt-duckdb가 필요합니다. 버전 요구사항은 이 페이지 곳곳에 인라인으로 표시됩니다.

출처: 문서

본문

시크릿 관리자(Secrets manager)

클라우드 스토리지 자격 증명을 관리하려면 DuckDB Secrets Manager를 사용하세요. 프로필에 secrets 필드를 구성합니다.

default:
  outputs:
    dev:
      type: duckdb
      path: /tmp/dbt.duckdb
      extensions:
        - httpfs
        - parquet
      secrets:
        - type: s3
          region: my-aws-region
          key_id: "{{ env_var('S3_ACCESS_KEY_ID') }}"
          secret: "{{ env_var('S3_SECRET_ACCESS_KEY') }}"
  target: dev

컨텍스트에서 자격 증명 가져오기

자격 증명을 직접 지정하는 대신 credential_chain 시크릿 프로바이더를 사용해 지원되는 AWS 메커니즘(예: 웹 아이덴티티 토큰)을 사용할 수 있어요. 자세한 내용은 DuckDB 시크릿 프로바이더 문서를 참고하세요.

secrets:
  - type: s3
    provider: credential_chain

스토리지 접두사별 범위 지정 자격 증명

다른 스토리지 경로가 다른 자격 증명을 사용하도록 시크릿에 범위를 지정할 수 있습니다.

secrets:
  - type: s3
    provider: credential_chain
    scope: [ "s3://bucket-in-eu-region", "s3://bucket-2-in-eu-region" ]
    region: "eu-central-1"
  - type: s3
    region: us-west-2
    scope: "s3://bucket-in-us-region"

경로에 대한 시크릿을 가져올 때 시크릿 범위가 경로와 비교됩니다. 여러 시크릿이 일치하면 가장 긴 접두사가 선택됩니다.

fsspec을 사용한 클라우드 스토리지

dbt-duckdb 1.4.1 이상에서 fsspec을 통해 구현된 DuckDB 파일시스템을 실험적으로 사용할 수 있어요. fsspec 라이브러리는 S3, GCS, Azure Blob Storage를 포함한 다양한 클라우드 데이터 스토리지 시스템을 지원합니다.

fsspec 구현을 사용하려면 관련 Python 모듈을 설치하고 프로필에 filesystems를 구성하세요.

default:
  outputs:
    dev:
      type: duckdb
      path: /tmp/dbt.duckdb
      filesystems:
        - fs: s3
          anon: false
          key: "{{ env_var('S3_ACCESS_KEY_ID') }}"
          secret: "{{ env_var('S3_SECRET_ACCESS_KEY') }}"
          client_kwargs:
            endpoint_url: "http://localhost:4566"
  target: dev

각 항목은 로드할 fsspec 프로토콜(s3, gcs, abfs 등)을 식별하는 fs 속성을 포함해야 하며, 해당 구현을 구성하는 추가 키-값 쌍을 포함할 수 있어요.

임의의 ATTACH 옵션

기본 attach 프로필 구문은 Connecting to DuckDB를 참고하세요. DuckDB의 ATTACH 문에 추가 키-값 쌍을 전달해야 할 때는 options 사전을 사용하세요.

attach:
  - path: /tmp/db1.sqlite
    type: sqlite
    read_only: true
  - path: /tmp/special.duckdb
    options:
      cache_size: 1GB
      threads: 4
      enable_fsst: true

직접 필드(type, secret, read_only)와 options 사전 모두에 같은 옵션을 지정하면 dbt-duckdb는 충돌을 방지하기 위해 오류를 발생시킵니다.

DuckLake

DuckLake는 DuckDB에 ACID 트랜잭션과 time travel을 제공하는 테이블 형식입니다. 로컬 데이터베이스와 MotherDuck 모두에서 DuckLake를 사용할 수 있어요.

MotherDuck에서의 DuckLake

dbt-duckdb 1.9.6 이상에서 DuckLake 데이터베이스를 만들고 is_ducklake: true를 설정해 MotherDuck의 호스팅 DuckLake에 연결할 수 있습니다.

MotherDuck에서 DuckLake를 설정하려면:

MotherDuck에서 DuckLake 데이터베이스를 만듭니다.

CREATE DATABASE my_ducklake
  (TYPE ducklake, DATA_PATH 's3://...')

프로필을 구성합니다.

default:
  outputs:
    dev:
      type: duckdb
      path: "md:my_db?motherduck_token={{ env_var('MOTHERDUCK_TOKEN') }}"
      attach:
        - path: "md:my_ducklake"
          is_ducklake: true
  target: dev

dbt가 안전한 DDL 작업을 적용하도록 DuckLake를 is_ducklake: true로 식별해야 합니다. 로컬 DuckLake의 경우 경로에 ducklake:를 사용하세요.

attach:
  - path: "ducklake:my_ducklake.ddb"

DuckLake 테이블 파티셔닝

DuckLake 지원 테이블(MotherDuck 관리 DuckLake 포함)의 경우 partitioned_by를 사용해 table 또는 incremental 모델의 물리적 파티셔닝을 구성할 수 있어요.

{{ config(materialized='table', partitioned_by=['year', 'month']) }}

select
  *,
  year(event_time) as year,
  month(event_time) as month
from {{ ref('upstream_model') }}

partition_by는 partitioned_by의 별칭으로 허용됩니다. 이 설정은 DuckLake 관계에만 적용되며, DuckLake가 아닌 대상에서는 경고와 함께 무시됩니다.

DuckLake는 ALTER TABLE ... SET PARTITIONED BY (...)를 사용해 파티셔닝을 적용하며, 파티셔닝은 새 데이터에만 영향을 줍니다. 첫 빌드나 전체 새로고침의 경우 dbt-duckdb는 빈 테이블을 만들고 파티셔닝을 설정한 뒤 데이터를 삽입해 초기 로드가 파티셔닝되도록 합니다. 자세한 내용은 DuckLake 파티셔닝 문서를 참고하세요.

점진적 전략(Incremental strategies)

dbt-duckdb는 점진적 테이블 모델에 대해 다음 전략을 지원합니다.

append
delete+insert
merge
microbatch

Append 전략

구성	유형	기본값	설명
incremental_predicates		null	추가되는 레코드를 필터링할 SQL 조건

Delete+insert 전략

구성	유형	기본값	설명
unique_key	/	—	필수. 삭제할 레코드를 식별하는 데 사용하는 컬럼.
incremental_predicates		null	delete와 insert 작업을 필터링할 SQL 조건

Merge 전략

merge 전략은 DuckDB 1.4.0 이상을 요구하며 DuckDB의 네이티브 MERGE 문에 접근할 수 있게 해줍니다.

기본 구성: unique_key만 지정하면 dbt-duckdb가 DuckDB의 UPDATE BY NAME과 INSERT BY NAME 작업을 사용해 컬럼을 이름으로 자동 매칭합니다.

models:
  - name: my_incremental_model
    config:
      materialized: incremental
      incremental_strategy: merge
      unique_key: id

향상된 구성: 더 세밀한 제어를 위한 추가 옵션입니다.

구성	유형	기본값	설명
unique_key	<string/list>	—	필수. MERGE 조인 조건에 사용하는 컬럼.
incremental_predicates		null	MERGE 작업을 필터링할 추가 SQL 조건
merge_update_condition		null	일치하는 레코드를 업데이트할 시점을 제어하는 SQL 조건
merge_insert_condition		null	일치하지 않는 레코드를 삽입할 시점을 제어하는 SQL 조건
merge_update_columns		null	업데이트할 특정 컬럼
merge_exclude_columns		null	업데이트에서 제외할 컬럼
merge_update_set_expressions		null	컬럼 업데이트용 커스텀 표현식

최대 유연성을 위해 merge_clauses를 사용해 커스텀 when_matched와 when_not_matched 동작을 정의할 수 있어요. DuckLake를 사용할 때는 DuckLake의 현재 MERGE 구현 제약 때문에 MERGE 문의 when_matched 절에서 단일 UPDATE 또는 DELETE 작업만 허용됩니다.

조건과 표현식에서는 들어오는 데이터 참조에 DBT_INTERNAL_SOURCE를, 기존 대상 테이블 참조에 DBT_INTERNAL_DEST를 사용하세요.

Microbatch 전략

microbatch 전략은 dbt 1.9 이상을 요구하며 구성된 event_time 컬럼을 사용해 시간 기반 배치로 점진적 빌드를 실행합니다.

구성	기본값	설명
event_time	—	필수. microbatch 윈도잉에 사용하는 타임스탬프 컬럼 이름.
begin	—	필수. 배칭 시작 시간(예: 2025-01-01).
batch_size	—	필수. 배치 grain(예: day, hour).
incremental_predicates	null	각 배치 내에 적용되는 선택적 추가 조건

팁: 성능 관점에서 microbatching이 항상 최선의 옵션은 아닐 수 있어요. DuckDB는 물리적 파티션이 아닌 행 그룹(row groups)으로 작동합니다(DuckLake에서 데이터를 명시적으로 파티셔닝하지 않는 한). 사용 사례에 맞게 스레드 수를 다르게 테스트하세요.

더 많은 정보

연결 모드와 프로필 설정은 Connect DuckDB를 참고하세요.
어댑터 소스 코드와 플러그인은 dbt-duckdb 저장소를, 어댑터 릴리스 노트는 dbt-duckdb releases 페이지를 참고하세요.
이 페이지에서 사용된 dbt 개념은 Materializations, Incremental models, Python models를 참고하세요.

더 알아보기 (Learn more)

dbt-duckdb는 로컬 분석과 임베디드 분석에 특히 유용한 어댑터예요. DuckDB의 시크릿 관리자와 병렬 처리(threads) 같은 성능 설정, 그리고 점진적 전략의 일반 개념을 함께 학습하면 DuckDB 기반 파이프라인을 효과적으로 설계할 수 있습니다.