unique_key

unique_key

unique_key는 incremental 모델이나 스냅샷의 레코드를 식별해서 변경 사항이 올바르게 캡처·갱신되도록 해주는 설정이에요. incremental 모델에서는 이 키로 변경을 병합(merge)/업서트하고, 스냅샷에서는 시간이 지나며 같은 unique_key에 대해 여러 행을 저장해 이력을 유지해요.

출처: 문서

본문

unique_key는 incremental 모델의 SQL 파일 config 블록, models/properties.yml 파일, 또는 dbt_project.yml 파일에서 설정해요.

models/my_incremental_model.sql

{{
    config(
        materialized='incremental',
        unique_key='id'
    )
}}

models/properties.yml

models:
  - name: my_incremental_model
    description: "An incremental model example with a unique key."
    config:
      materialized: incremental
      unique_key: id

dbt_project.yml

name: jaffle_shop

models:
  jaffle_shop:
    staging:
      +unique_key: id

(dbt v1.9 이상 적용) 스냅샷의 경우 unique_key는 snapshot/filename.yml 파일이나 dbt_project.yml 파일에서 설정해요.

snapshots/.yml

snapshots:
  - name: orders_snapshot
    relation: source('my_source', 'my_table')
    config:
      unique_key: order_id

dbt_project.yml

snapshots:
  <resource-path>:
    +unique_key: column_name_or_expression

Description

스냅샷이나 incremental 모델 입력의 각 레코드를 고유하게 식별하는 컬럼 이름 또는 표현식이에요. dbt는 이 키로 들어오는 레코드를 대상 테이블(스냅샷 또는 incremental 모델)의 기존 레코드와 매칭해 변경 사항을 올바르게 캡처·갱신해요.

  • incremental 모델에서 dbt는 이전 행을 교체해요 (merge 키 또는 upsert처럼).
  • 스냅샷에서 dbt는 이력을 유지해, 시간이 지나며 같은 unique_key에 대해 여러 행을 저장해요.

dbt v1 Latest 릴리스 트랙과 dbt v1.9부터 스냅샷은 snapshots/ 디렉터리 내 YAML 파일에서 정의·설정돼요. 스냅샷 YAML 파일의 config 키에 unique_key 값을 하나 이상 지정할 수 있어요.

주의: 고유하지 않은 키를 제공하면 예기치 않은 스냅샷 결과가 나와요. dbt는 이 키의 고유성을 테스트하지 않으므로, 이 키가 실제로 고유한지 소스 데이터를 테스트하는 것을 고려하세요.

Default

이 파라미터는 선택 사항이에요. unique_key를 제공하지 않으면 어댑터가 기본적으로 incremental_strategy: append를 사용해요.

unique_key 파라미터를 생략하고 merge, insert_overwrite, delete+insert, microbatch 같은 전략을 쓰면, 어댑터가 incremental_strategy: append로 폴백해요.

BigQuery는 다르게 동작해요.

  • incremental_strategy = merge의 경우 unique_key를 반드시 제공해야 해요. 생략하면 모호하거나 실패하는 동작이 나와요.
  • insert_overwrite 또는 microbatch의 경우 unique_key는 필요 없어요. 행 레벨 업서트가 아니라 파티션 교체로 동작하기 때문이에요.

Examples

id 컬럼을 unique key로 사용하기

incremental 모델에서 id 컬럼을 unique key로 쓰는 예시예요.

models/my_incremental_model.sql

{{
    config(
        materialized='incremental',
        unique_key='id'
    )
}}

select * from ..

이 예시에서는 스냅샷의 unique key로 id 컬럼을 사용해요.

(dbt v1.9 이상 적용) snapshots/orders_snapshot.yml

snapshots:
  - name: orders_snapshot
    relation: source('jaffle_shop', 'orders')
    config:
      schema: snapshots
      unique_key: id
      strategy: timestamp
      updated_at: updated_at

여러 스냅샷이 같은 unique_key를 공유한다면 dbt_project.yml 파일에서 설정을 지정할 수도 있어요.

dbt_project.yml

snapshots:
  <resource-path>:
    +unique_key: id

(dbt v1.9 이상 적용)

여러 unique key 사용하기

incremental 모델의 여러 unique key는 단일 컬럼을 나타내는 문자열 또는 함께 사용할 수 있는 작은따옴표 컬럼 이름의 목록으로 설정해요. 예: ['col1', 'col2', …].

컬럼에는 null 값이 있으면 안 돼요. 그렇지 않으면 incremental 모델이 행을 매칭하지 못하고 중복 행을 만들 수 있어요. 자세한 내용은 Defining a unique key를 참고하세요.

models/my_incremental_model.sql

{{ config(
    materialized='incremental',
    unique_key=['order_id', 'location_id']
) }}

with...

스냅샷은 primary_key 컬럼에 여러 unique key를 쓰도록 설정할 수 있어요.

snapshots/transaction_items_snapshot.yml

snapshots:
  - name: orders_snapshot
    relation: source('jaffle_shop', 'orders')
    config:
      schema: snapshots
      unique_key:
        - order_id
        - product_id
      strategy: timestamp
      updated_at: updated_at

더 알아보기 (Learn more)