full_refresh

full_refresh config는 리소스가 항상 또는 절대 full-refresh를 수행할지 제어할 수 있게 해주는 설정이에요. 이 config는 명령줄 --full-refresh 플래그를 덮어써요.

출처: 문서

본문

모델 (Models)

dbt_project.yml

models:
  <resource-path>:
    +full_refresh: false | true

models/.sql


{{ config(
    full_refresh = false | true
) }}

select ...

Seeds

dbt_project.yml

seeds:
  <resource-path>:
    +full_refresh: false | true

설명 (Description)

full_refresh config는 리소스가 항상 또는 절대 full-refresh를 수행할지 선택적으로 구성할 수 있게 해줘요. 이 config는 dbt 명령 실행 시 사용하는 --full-refresh 명령줄 플래그에 대한 오버라이드예요.

full_refresh config는 dbt_project.yml 파일 또는 리소스 config에서 설정할 수 있어요.

`full_refresh` 값	동작
`true`로 설정	리소스는 dbt 명령에 `--full-refresh` 플래그를 전달했는지와 관계없이 항상 full refresh를 수행해요.
`false`로 설정	리소스는 `--full-refresh` 플래그를 전달했는지와 관계없이 절대 full refresh를 수행하지 않아요.
`none` 또는 생략	리소스는 `--full-refresh` 플래그의 동작을 따르는요. 플래그를 사용하면 full refresh를 수행하고, 그렇지 않으면 수행하지 않아요.

Snapshots는 full refresh를 무시해요.

Snapshots는 full_refresh config와 --full-refresh 플래그 모두를 무시해요. snapshot 노드를 포함한 dbt build --full-refresh 또는 dbt snapshot --full-refresh 같은 명령은 snapshot을 평소처럼 실행해요 — snapshot 테이블을 drop하거나 재생성하지 않으므로 기존 snapshot 기록이 보존돼요.

참고

--full-refresh 플래그는 짧은 이름 -f도 지원해요.
should_full_refresh() 매크로에 로직이 인코딩되어 있어요.

사용법 (Usage)

Incremental 모델

Seeds

seed의 컬럼을 변경했는데, 이제 seed 명령을 실행할 때 오류가 나요. 어떻게 해야 하나요?

seed의 컬럼을 변경했다면 Database Error가 발생할 수 있어요:

Snowflake

$ dbt seed
Running with dbt=1.6.0-rc2
Found 0 models, 0 tests, 0 snapshots, 0 analyses, 130 macros, 0 operations, 1 seed file, 0 sources

12:12:27 | Concurrency: 8 threads (target='dev_snowflake')
12:12:27 |
12:12:27 | 1 of 1 START seed file dbt_claire.country_codes...................... [RUN]
12:12:30 | 1 of 1 ERROR loading seed file dbt_claire.country_codes.............. [ERROR in 2.78s]
12:12:31 |
12:12:31 | Finished running 1 seed in 10.05s.

Completed with 1 error and 0 warnings:

Database Error in seed country_codes (seeds/country_codes.csv)
  000904 (42000): SQL compilation error: error line 1 at position 62
  invalid identifier 'COUNTRY_NAME'

Done. PASS=0 WARN=0 ERROR=1 SKIP=0 TOTAL=1

Redshift

$ dbt seed
Running with dbt=1.6.0-rc2
Found 0 models, 0 tests, 0 snapshots, 0 analyses, 149 macros, 0 operations, 1 seed file, 0 sources

12:14:46 | Concurrency: 1 threads (target='dev_redshift')
12:14:46 |
12:14:46 | 1 of 1 START seed file dbt_claire.country_codes...................... [RUN]
12:14:46 | 1 of 1 ERROR loading seed file dbt_claire.country_codes.............. [ERROR in 0.23s]
12:14:46 |
12:14:46 | Finished running 1 seed in 1.75s.

Completed with 1 error and 0 warnings:

Database Error in seed country_codes (seeds/country_codes.csv)
  column "country_name" of relation "country_codes" does not exist

Done. PASS=0 WARN=0 ERROR=1 SKIP=0 TOTAL=1

이 경우 --full-refresh 플래그로 명령을 다시 실행해야 해요:

dbt seed --full-refresh

왜 이런 일이 일어날까요?

보통 dbt seed를 실행하면 dbt가 기존 테이블을 truncate하고 데이터를 다시 삽입해요. 이 패턴은 BI 사용자가 조회할 수 있는 다운스트림 객체가 drop될 수 있는 drop cascade 명령을 피해요.

하지만 컬럼 이름이 바뀌거나 새 컬럼이 추가되면, 테이블 구조가 바뀌었으므로 이 명령들이 실패해요.

--full-refresh 플래그는 dbt가 테이블을 재빌드하기 전에 기존 테이블을 drop cascade하도록 강제해요.

권장 사항 (Recommendation)

특히 대용량 데이터셋의 모델에는 full_refresh: false를 설정하세요. dbt가 완전히 drop하고 재생성하길 절대 원하지 않을 거예요.
기존 full_refresh config는 덮어쓸 수 없어요. 특정 상황에서 동작을 바꾸려면 config 로직을 제거하거나 변수를 사용해 필요할 때 동작을 오버라이드할 수 있도록 업데이트하세요. 예를 들어 다음과 같은 config를 가진 incremental 모델이 있다면:
```
{{ config(
    materialized = 'incremental',
    full_refresh = var("force_full_refresh", false)
) }}
```
--vars 플래그를 사용해 full_refresh config를 true로 오버라이드하세요: dbt run --vars '{"force_full_refresh": true}'.

더 알아보기 (Learn more)

on_configuration_change