모델 운영: deprecation, migration, documentation, consumer communication

분석 모델은 쿼리가 아니라 약속이다

분석 데이터 모델은 한 번 만들어 두면 끝나는 산출물이 아니다. 대시보드, 노트북, reverse ETL, ML feature, 재무 정산 쿼리가 그 모델을 source of truth처럼 사용하기 시작하는 순간, 모델은 내부 SQL 파일이 아니라 소비자와의 약속이 된다.

문제는 이 약속이 조용히 늘어난다는 점이다. 처음에는 한 팀의 대시보드용 mart_orders였지만, 몇 달 뒤에는 매출 리포트, 캠페인 성과 분석, CS 운영 지표, 임원 주간 보고서가 모두 같은 컬럼을 읽고 있을 수 있다. 이때 컬럼명을 바꾸거나 grain을 바꾸거나 필터 로직을 수정하면 “빌드는 성공했는데 숫자가 달라진” 사고가 난다.

그래서 모델 운영의 핵심은 네 가지다.

• deprecation: 더 이상 권장하지 않는 모델·컬럼·버전을 언제까지 유지할지 알린다.
• migration: 소비자가 새 모델로 옮겨 갈 수 있는 경로와 검증 방법을 제공한다.
• documentation: grain, owner, freshness, 컬럼 의미, 제한 사항을 검색 가능한 형태로 남긴다.
• consumer communication: 영향 받는 사람에게 변경 이유, 일정, 필요한 행동을 반복해서 전달한다.

이 장에서는 분석 모델을 “서비스 인터페이스”처럼 운영하는 방법을 다룬다. 도구는 dbt, DataHub, Google Knowledge Catalog, Microsoft Fabric 같은 사례를 참고하지만, 목표는 특정 제품 사용법이 아니라 변경을 안전하게 흘려보내는 운영 감각이다.

1. 모델 생명주기를 명시한다

모델 상태를 단순히 “있음/없음”으로 두면 운영이 어렵다. 최소한 다음 상태를 구분해야 한다.

Microsoft Fabric과 Power BI의 endorsement 기능은 Promoted, Certified, Master data 같은 배지를 통해 사용자가 신뢰할 수 있는 콘텐츠를 찾도록 돕는다. 이 개념을 특정 BI 도구에만 맡기지 말고, warehouse 모델과 dbt 문서, catalog metadata에도 같은 신호로 남기는 것이 좋다.

2. Deprecation은 삭제 공지가 아니라 이관 프로세스다

Deprecation을 “이 모델은 곧 삭제됩니다”라고 한 번 알리는 것으로 끝내면 실패한다. 실제 운영에서는 소비자가 다음 질문에 답할 수 있어야 한다.

• 왜 deprecated 되었는가?
• 대체 모델은 무엇인가?
• 어떤 컬럼·metric·grain이 달라졌는가?
• 기존 쿼리를 어떻게 바꾸면 되는가?
• 언제까지 옮겨야 하는가?
• 옮긴 뒤 숫자가 맞는지 어떻게 검증하는가?

예를 들어 mart_orders를 fct_order_items와 dim_order로 분리한다고 하자. 삭제 공지만 보내면 사용자는 새 조인 조건, grain 차이, 환불 처리 로직 변화를 스스로 추론해야 한다. 반대로 migration guide가 있으면 변경은 운영 가능한 작업이 된다.

# Migration: mart_orders -> fct_order_items + dim_order

## Why
- `mart_orders` mixed order-level and item-level grain.
- Refund and discount calculations were ambiguous in downstream dashboards.

## Timeline
- 2026-07-04: new models published
- 2026-07-18: existing dashboards migrated
- 2026-08-01: `mart_orders` marked deprecated
- 2026-09-01: `mart_orders` removed

## Replacement
- order-level fields: `dim_order`
- item-level revenue: `fct_order_items`
- recommended metric: `net_revenue`

## Validation query
- Compare daily net revenue by order_date for the last 90 days.

중요한 점은 deprecated 상태에서도 모델이 한동안 살아 있어야 한다는 것이다. dbt의 model versioning 문서는 breaking change가 있는 모델을 API처럼 보고, 새 버전과 이전 버전을 일정 기간 함께 유지해 소비자가 옮겨 갈 시간을 주는 방식을 설명한다. 동시에 오래된 버전을 영원히 유지하면 warehouse 비용, 문서 혼란, 테스트 부담이 늘어난다. 그래서 deprecation_date나 sunset date 같은 종료 시점을 명확히 두어야 한다.

3. Breaking change와 non-breaking change를 구분한다

모든 변경에 버전업이나 migration window가 필요한 것은 아니다. 그러나 “빌드가 성공했다”와 “소비자가 깨지지 않는다”는 다르다.

특히 계산식 변경은 애매하다. 잘못된 로직을 고치는 것은 bug fix일 수 있지만, 사용자가 보던 지표의 의미가 바뀐다면 breaking change에 가깝다. 이때는 코드 diff보다 소비자가 체감하는 의미 변화를 기준으로 판단한다.

운영적으로는 다음 규칙이 안전하다.

1. public 또는 certified 모델에는 contract와 owner를 둔다.
2. 컬럼 삭제·rename·type 변경·grain 변경은 기본적으로 breaking change로 취급한다.
3. breaking change는 새 모델 또는 새 버전으로 먼저 배포한다.
4. 이전 모델에는 deprecated 표시와 sunset date를 둔다.
5. migration 완료 여부를 lineage와 query log로 확인한다.

4. 문서는 “설명”보다 “오해 방지 장치”에 가깝다

분석 모델 문서는 길수록 좋은 것이 아니라, 소비자가 잘못 쓰기 쉬운 지점을 막아야 한다. 최소 문서 항목은 다음과 같다.

DataHub 같은 catalog 도구는 ownership, tag, glossary term, domain 같은 metadata를 붙여 검색과 책임 경계를 분명히 할 수 있다. dbt의 exposures는 대시보드, 노트북, ML workflow 같은 downstream 사용처를 DAG에 표시한다. Google Knowledge Catalog의 lineage 설명처럼 lineage는 변경 관리, 문제 추적, compliance를 위해 “무엇이 어디로 흘러가는지”를 보여준다.

하지만 도구가 있어도 빈 metadata는 도움이 되지 않는다. 운영자는 다음 두 가지를 자동화 대상으로 삼는 편이 좋다.

• PR에서 public model의 owner, description, columns, tests, exposures 누락을 막는다.
• 매주 또는 매월 catalog에서 owner 없는 모델, 설명 없는 컬럼, deprecated 종료일이 지난 모델을 점검한다.

5. 소비자 커뮤니케이션은 한 번이 아니라 단계별로 한다

모델 변경 사고는 대개 기술 변경 자체보다 커뮤니케이션 공백에서 커진다. 특히 데이터 모델은 소비자가 다양하다. 같은 모델을 읽는 사람이 BI analyst, product manager, data scientist, backend engineer일 수 있다. 모든 사람이 dbt PR을 보지 않는다.

안전한 커뮤니케이션은 다음 순서로 진행한다.

1. 사전 예고: 변경 이유, 영향 범위, 예상 일정 공유
2. 대체 경로 공개: 새 모델, 문서, sample query, 검증 쿼리 제공
3. 병행 운영: 이전 모델과 새 모델을 함께 제공하며 차이 모니터링
4. 잔여 소비자 추적: lineage, query history, BI workspace impact analysis 확인
5. 종료 리마인드: sunset 2주 전, 1주 전, 전날 알림
6. 삭제 후 확인: 실패 쿼리, dashboard refresh 실패, 문의 채널 모니터링

Microsoft Fabric의 impact analysis는 downstream item과 workspace를 보여주고, 관련 contact에게 변경 메시지를 보낼 수 있다. 이 기능의 중요한 교훈은 “영향도 분석”과 “알림”이 분리되어 있지 않다는 점이다. 영향 받는 대상을 찾았다면, 그 대상에게 어떤 행동이 필요한지까지 전달해야 한다.

커뮤니케이션 메시지는 길 필요가 없다. 대신 필요한 행동이 명확해야 한다.

제목: [Action required] mart_orders deprecated, migrate by 2026-09-01

변경 이유:
- order-level과 item-level grain이 섞여 revenue metric이 dashboard마다 달라졌습니다.

영향:
- `mart_orders`를 직접 조회하는 dashboard/notebook/query

해야 할 일:
- order-level 분석은 `dim_order`로 이동
- item-level revenue는 `fct_order_items` 사용
- migration guide의 검증 쿼리로 최근 90일 매출 비교

일정:
- 2026-08-01 deprecated
- 2026-09-01 제거

문의:
- #data-modeling-support

6. Migration은 숫자 검증까지 포함한다

모델 migration의 완료 기준을 “쿼리가 새 모델을 참조한다”로 두면 부족하다. 분석 모델은 숫자가 맞아야 한다. 따라서 migration plan에는 최소 세 종류의 검증이 필요하다.

6.1 Schema validation

새 모델이 기대한 컬럼과 타입을 제공하는지 확인한다. dbt model contracts는 모델 출력의 shape를 보장하는 장치다. public model이나 certified model에는 contract를 적용해 컬럼 누락, 타입 변화 같은 문제를 빌드 단계에서 잡는 편이 안전하다.

6.2 Reconciliation

기존 모델과 새 모델의 핵심 지표를 기간별, segment별로 비교한다.

with old as (
  select order_date, sum(net_revenue) as revenue
  from mart_orders
  where order_date >= current_date - interval '90 day'
  group by 1
),
new as (
  select order_date, sum(net_revenue) as revenue
  from fct_order_items
  where order_date >= current_date - interval '90 day'
  group by 1
)
select
  coalesce(old.order_date, new.order_date) as order_date,
  old.revenue as old_revenue,
  new.revenue as new_revenue,
  new.revenue - old.revenue as diff
from old
full outer join new using (order_date)
where abs(coalesce(new.revenue, 0) - coalesce(old.revenue, 0)) > 1
order by 1;

차이가 0이어야 하는 migration도 있고, 의도적으로 달라져야 하는 migration도 있다. 후자라면 “왜 달라지는지”를 release note에 적어야 한다.

6.3 Consumer validation

대시보드 refresh, notebook run, reverse ETL sync, downstream dbt model build가 실제로 성공하는지 확인한다. dbt exposures를 사용한다면 dbt test -s +exposure:<name>처럼 특정 exposure의 upstream을 대상으로 테스트할 수 있다.

7. 운영 체크리스트

모델 운영을 정착시키려면 모든 변경을 큰 프로세스로 만들기보다, public interface에만 강한 기준을 적용하는 편이 현실적이다.

Public 또는 certified 모델 PR 체크

• [ ] owner와 escalation channel이 있다.
• [ ] grain이 문서화되어 있다.
• [ ] 주요 컬럼 설명과 metric 정의가 있다.
• [ ] freshness 기대치가 있다.
• [ ] column test 또는 contract가 있다.
• [ ] downstream exposures 또는 catalog lineage가 갱신되었다.
• [ ] breaking change 여부를 판단했다.
• [ ] breaking change라면 migration guide와 sunset date가 있다.

Deprecated 모델 주간 점검

• [ ] sunset date가 지난 모델이 남아 있지 않은가?
• [ ] query history에 아직 참조가 남아 있는가?
• [ ] BI refresh 실패나 scheduled query 실패가 발생했는가?
• [ ] 문서와 catalog search에서 deprecated 표시가 보이는가?
• [ ] 대체 모델이 certified 또는 promoted 상태인가?

삭제 직전 점검

• [ ] 지난 N일 동안 실제 쿼리 참조가 0인가?
• [ ] downstream dashboard owner에게 최종 알림을 보냈는가?
• [ ] rollback이 필요한 경우 view alias를 임시 복구할 수 있는가?
• [ ] 삭제 후 모니터링할 실패 로그 위치가 정해져 있는가?

마무리

분석 데이터 모델 운영은 SQL을 깔끔하게 유지하는 작업을 넘어선다. 핵심은 모델을 소비자와의 계약으로 보고, 변경이 필요한 순간마다 영향도와 이관 경로를 관리하는 것이다.

좋은 운영자는 모델을 쉽게 삭제하지 않는다. 먼저 사용자를 찾고, 대체 경로를 만들고, 숫자를 비교하고, 충분히 알린 뒤 제거한다. 반대로 영원히 낡은 모델을 유지하지도 않는다. 종료일 없는 deprecation은 기술 부채를 이름만 바꿔 보관하는 일이다.

정리하면 다음 원칙이 가장 중요하다.

• public model은 owner, grain, contract, documentation을 갖춘다.
• breaking change는 새 버전 또는 새 모델로 먼저 제공한다.
• deprecation에는 대체 경로와 sunset date가 있어야 한다.
• migration 완료는 참조 변경이 아니라 숫자 검증과 consumer validation으로 판단한다.
• lineage와 catalog는 문서가 아니라 변경 관리 도구로 사용한다.

References

• dbt Developer Hub, Model versions
• dbt Developer Hub, Model access
• dbt Developer Hub, Model contracts
• dbt Developer Hub, Add Exposures to your DAG
• dbt Developer Hub, Deprecations
• Google Cloud Documentation, About data lineage
• Microsoft Learn, Impact analysis - Microsoft Fabric
• Microsoft Learn, Endorsement overview - Microsoft Fabric
• DataHub Docs, Ownership
• DataHub Docs, Tags Overview