영업팀의 ‘활성 고객’ 숫자와 재무팀의 숫자가 다르다. 둘 다 같은 테이블의 `active` 값을 읽지만, 어느 날 생산팀이 ‘최근 30일 로그인’의 의미를 ‘최근 30일 결제’로 바꿨다. 컬럼 이름과 자료형은 그대로여서 파이프라인도 테스트도 초록색이다. 그러나 대시보드와 AI 분석의 해석은 달라졌다. 데이터 계약은 파일 형식뿐 아니라 그 값이 무엇을 뜻하는지 합의하는 장치다.
Confluent의 데이터 계약 문서는 구조 외에도 무결성 규칙, 메타데이터, 정책과 변경 규칙을 계약의 요소로 설명한다. 특정 스트리밍 제품이 없어도 같은 질문이 적용된다. 누가 데이터를 만들고, 누가 읽으며, 무엇이 바뀌면 누구에게 알려야 하는가?
데이터 계약은 생산자와 소비자의 대화다
생산자는 주문 시스템일 수 있고 소비자는 대시보드, 정산 시스템, AI 피처 파이프라인일 수 있다. 생산자는 새 값을 만들 때 모든 소비자를 알지 못하고, 소비자는 원래 업무 규칙을 모를 수 있다. 계약에는 데이터셋이나 이벤트 이름, 소유 팀, 주요 소비자, 필드 정의, 예제, 생성 시각과 갱신 기대, 오류 문의 경로를 적는다. 단순한 문서에 그치지 않게 배포와 검증 절차에 연결한다.
예를 들어 `order_amount`가 부가세 포함인지, 할인 전인지, 환불 반영 후인지에 따라 같은 숫자도 전혀 다르다. `created_at`이 고객의 클릭 시각인지 서버 저장 시각인지도 중요하다. 통화 단위, 시간대, 결측값의 의미, 취소 주문을 포함하는지까지 정의해야 재무·영업·운영이 같은 질문에 같은 답을 얻는다. 모든 필드를 한 번에 완벽히 정의할 필요는 없지만, 의사결정에 쓰이는 핵심 필드부터 시작해야 한다.
스키마와 의미·품질을 나눠 검증한다
첫 층은 구조다. 필드가 있고 타입이 맞으며 필수값이 존재하는가? 둘째는 도메인 규칙이다. 수량이 음수가 될 수 있는가? 주문 상태가 정의된 값 안에 있는가? 셋째는 운영 품질이다. 정해진 시각까지 데이터가 도착했는가, 특정 고객사의 데이터만 갑자기 사라지지 않았는가? 넷째는 의미와 소유권이다. 이 데이터가 어떤 업무 사건을 나타내고 변경 책임자는 누구인가?
품질 규칙에도 오탐과 예외가 있다. 할인으로 금액이 0이 되는 주문이 정상일 수 있다. 점검으로 야간 데이터가 일시적으로 늦을 수도 있다. 그러므로 규칙 위반을 모두 삭제하지 말고 차단, 경고, 검토 중 어떤 행동을 할지 정한다. 고객사별 예외가 필요하면 누가 승인하고 언제 끝나는지 기록한다. 일시적 예외가 무기한 기본 규칙이 되지 않게 해야 한다.
변경은 호환성과 의미를 함께 본다
새 필드를 추가하는 것은 대개 필드를 제거하는 것보다 안전해 보인다. 하지만 새 필드가 기존 필드의 해석을 바꾸거나 결측값의 의미를 바꾸면 여전히 소비자가 깨질 수 있다. Confluent의 스키마 진화 문서는 이전 데이터를 새 소비자가 읽을 수 있는지, 새 데이터를 옛 소비자가 읽을 수 있는지에 따라 호환성 방향이 다르다고 설명한다. 형식 호환성 검사와 함께 대표 소비자의 결과 테스트를 해야 한다.
변경 제안에는 바꾸려는 이유, 영향을 받는 필드, 새 의미, 이전 값과의 차이, 적용 날짜, 영향을 받는 소비자, 되돌리는 방법을 담는다. 소비자 팀은 실제 집계 쿼리나 모델 입력 테스트로 확인한다. 일정 기간 옛 필드와 새 필드를 함께 제공할 수도 있지만, 두 값이 언제까지 병행되는지 종료일을 정해야 한다. 무기한 이중 지원은 또 다른 데이터 혼란을 만든다.
계약을 코드와 운영에 연결한다
데이터 계약을 위키 한 페이지에만 두면 업데이트를 놓치기 쉽다. 스키마 정의와 예제 데이터, 필수 규칙을 버전 관리하고 생산자 배포 시 호환성 검사를 돌린다. 소비자는 자신이 기대하는 필드와 의미를 테스트 사례로 제공한다. 파이프라인에는 지연·결측·규칙 위반 모니터링을 붙인다. 장애가 나면 어떤 계약 버전과 어떤 데이터 배치에서 시작됐는지 추적할 수 있어야 한다.
개인정보나 민감한 사업 정보의 분류도 계약에 담는다. 어떤 필드는 분석 환경으로 복제하면 안 되고, 어떤 필드는 마스킹이 필요할 수 있다. 태그 하나가 보안을 자동으로 보장하지는 않지만, 소비자가 데이터를 사용할 때 적용해야 할 정책을 분명하게 전달한다. 새 소비자를 붙일 때도 계약의 허용 목적과 권한을 검토해야 한다.
작게 시작하려면 문제가 자주 나는 데이터셋 하나를 고른다. 생산자와 소비자가 함께 가장 중요한 필드 다섯 개의 정의, 갱신 시각, 품질 규칙, 연락 담당자를 적는다. 최근 변경 하나를 다시 검토하며 계약이 있었다면 무엇을 사전에 발견했을지 확인한다. 그다음 자동 검증을 붙인다. 도구를 먼저 고르기보다 팀 사이의 용어를 일치시키는 편이 빠르다.
실무 체크리스트
- 데이터 생산자와 실제 소비자가 누구인지 적었는가?
- 핵심 필드의 단위·시간대·결측·포함 범위를 정의했는가?
- 구조, 도메인 규칙, 도착 시각을 분리해 검사하는가?
- 형식 호환성뿐 아니라 소비자 결과를 테스트하는가?
- 깨지는 변경의 병행 기간과 종료일이 있는가?
- 민감 필드의 사용 목적과 보호 정책이 표시되는가?
- 위반 시 차단·경고·검토 중 행동이 정해져 있는가?
데이터 계약의 목적은 문서를 하나 더 만드는 것이 아니다. 같은 이름의 데이터가 다른 뜻으로 흐르기 전에 생산자와 소비자가 변화를 발견하고 합의하는 것이다. 그래야 대시보드와 AI가 숫자를 읽을 때 그 숫자를 믿을 수 있다.
