커스텀 마이크로배치 전략

커스텀 마이크로배치 전략 (Custom microbatch strategy)

require_batched_execution_for_custom_microbatch_strategy 플래그는 커스텀 get_incremental_microbatch_sql 매크로가 있을 때만 관련돼요. 마이크로배치 전략을 쓰는 모델을 dbt가 배치로 실행할지 제어해요. 이 플래그는 v2에서 제거됐고 새 동작이 항상 활성화돼요.

출처: 문서

본문

이 플래그는 v2에서 제거됐어요. 새 동작이 항상 활성화돼요. 업그레이드한다면 dbt_project.yml에서 이 플래그를 제거해요.

require_batched_execution_for_custom_microbatch_strategy 플래그는 프로젝트에 커스텀 get_incremental_microbatch_sql 매크로가 이미 있을 때만 관련돼요. 커스텀 마이크로배치 매크로가 없다면 이 플래그를 설정할 필요가 없어요 — dbt가 마이크로배치 전략을 쓰는 모든 모델에 대해 자동으로 마이크로배칭을 처리해요.

dbt v1.12부터 이 플래그는 기본값이 true로, dbt가 커스텀 마이크로배치 전략을 배치로 실행해요. 커스텀 마이크로배치 매크로가 있고 플래그를 false로 설정하면 dbt가 deprecation 경고를 발생시켜요.

이전에는 기존 커스텀 인크리멘탈 전략과 의도치 않은 상호작용을 막으려면 DBT_EXPERIMENTAL_MICROBATCH 환경 변수를 true로 설정해야 했어요. 이제 DBT_EXPERIMENTAL_MICROBATCH를 설정해도 런타임 기능에 아무 영향이 없어요.

영향

이 플래그는 프로젝트에 커스텀 get_incremental_microbatch_sql 매크로가 있을 때만 관련돼요. 커스텀 마이크로배치 매크로가 없는 프로젝트는 영향을 받지 않아요 — 내장 매크로는 이미 배치로 실행돼요.

get_incremental_microbatch_sql을 오버라이드했다면 — 주로 어댑터 제한을 우회하거나 커스텀 파티션 전략을 구현하기 위해 — 매크로가 작성된 적 없는 배치 계약(batched contract) 아래에서 호출돼요. 가능한 결과:

• 매크로가 더 작은 event_time_start / event_time_end 윈도우를 무시하고 매 배치마다 전체 범위를 다시 처리해, 낭비되는 컴퓨팅, 중복 행, 또는 MERGE/INSERT 충돌을 유발.
• 매크로가 실행당 단일 호출을 기대해 오류 발생.
• 대상 테이블의 행 수가 플래그 값에 따라 달라짐.

권장 조치

마이크로배치 모델이 실행 중간에 오류가 나거나, 중복 행 또는 MERGE/INSERT 충돌이 생기거나, 매 배치마다 전체 날짜 범위를 다시 처리한다면, get_incremental_microbatch_sql 매크로가 event_time_start / event_time_end 윈도우로 필터링하는지 확인해요. 하드코딩된 날짜 필터(예: where event_ts >= current_date - interval '1 day')를 사용하거나 _dbt_max_partition만 읽는다면, 매크로가 배치별 윈도우를 무시하고 매 반복마다 전체 범위를 다시 처리하는 거예요.

수정하려면 매크로가 배치별 윈도우를 쓰도록 다시 작성해요:

{% macro get_incremental_microbatch_sql(arg_dict) %}
  {%- set target = arg_dict["target_relation"] -%}
  {%- set source = arg_dict["temp_relation"] -%}
  {%- set event_time = arg_dict["incremental_predicates"] -%}
  -- Use the per-batch window dbt passes via event_time_start/event_time_end
  -- (exposed through arg_dict["incremental_predicates"] or model.config.event_time_*),
  -- NOT a hard-coded date filter.
  insert into {{ target }}
  select * from {{ source }}
{% endmacro %}

검증하려면 단일 배치에 대해 dbt run --event-time-start <date> --event-time-end <date> -s <model>을 실행하고 행 수가 그 단일 날짜와 일치하는지 확인해요.

이 동작을 옵트아웃하려면 플래그를 false로 설정해요:

dbt_project.yml

flags:
  require_batched_execution_for_custom_microbatch_strategy: false

더 알아보기 (Learn more)

• 인크리멘탈 마이크로배치 — 마이크로배치 전략
• 동작 변경(Behavior changes)