mapGroupsWithState/flatMapGroupsWithState — GroupState로 임의의 상태 로직 짜기
Spark mapGroupsWithState/flatMapGroupsWithState 및 applyInPandasWithState 공식 문서 종합 (웹 리서치, 2026) — Apache Spark 공식 문서(streaming/structured-streaming-transform-with-state.html) + Databricks 공식 블로그(Python Arbitrary Stateful Processing) The Internals of Spark Structured Streaming — mapGroupsWithState
이 모듈을 다 읽으면
- GroupState가 그룹별 상태를 어떻게 다루는지, 세 가지 타임아웃 방식의 차이를 설명할 수 있다
- 이 연산자들의 출력이 스트림의 outputMode와 독립적으로 결정된다는 것을 설명할 수 있다
spark-learn-53에서 다룬 state store(RocksDB/HDFSBackedStateStore)를 전제로, 미리 정의된 집계 함수가 아니라 개발자가 직접 그룹별 상태 갱신 로직을 코드로 짤 수 있게 해주는 mapGroupsWithState/flatMapGroupsWithState의 핵심 메커니즘을 정리한다.
GroupState — 이전 상태를 받아 개발자가 직접 갱신 로직을 작성
이 두 연산자는 상태 갱신 함수가 이전 상태를 GroupState 타입의 객체로 받아, 그 안에서 개발자가 원하는 임의의 로직으로 상태를 읽고·갱신하고·지울 수 있게 해준다 — 미리 정의된 집계(count, sum 등)가 아니라 세션화, 커스텀 롤업 같은 자유로운 상태 기반 로직을 짤 수 있다는 게 핵심 가치다. mapGroupsWithState는 그룹당 정확히 하나의 출력 행만 낼 수 있는 반면, flatMapGroupsWithState는 0개 이상의 출력 행을 낼 수 있다는 게 두 API의 시그니처 차이다.
핵심 포인트
- GroupState 객체로 이전 상태를 받아 개발자가 직접 임의의 상태 갱신 로직(세션화, 커스텀 롤업 등)을 작성 가능
- mapGroupsWithState는 그룹당 정확히 1개 출력 행, flatMapGroupsWithState는 0개 이상의 출력 행 — 이 반환 개수 차이가 두 API의 핵심 시그니처 차이
세 가지 타임아웃 — 없음/처리시간/이벤트시간(워터마크 필요)
타임아웃 설정은 세 가지 중 하나다 — 타임아웃 없음(상태가 명시적으로 지워질 때까지 무기한 유지), 처리시간(processing-time) 기반(실제 벽시계 시간 기준으로 일정 시간 갱신이 없으면 만료), 이벤트시간(event-time) 기반(레코드의 타임스탬프 기준이라 워터마크가 정의돼 있어야만 동작). 이벤트시간 기반 타임아웃을 쓰려면 spark-learn-44에서 다룬 워터마크 설정이 전제조건이라는 점이 다른 두 방식과 구분되는 지점이다.
핵심 포인트
- 타임아웃 없음(무기한 유지)/처리시간 기반(벽시계 시간 기준)/이벤트시간 기반(레코드 타임스탬프 기준, 워터마크 필수) 세 가지
- 이벤트시간 기반 타임아웃은 spark-learn-44의 워터마크 설정이 반드시 전제돼야 동작
출력은 자체 로직으로 결정 — outputMode와 무관
일반적인 Structured Streaming 연산은 append/update/complete 같은 outputMode에 따라 결과가 어떻게 방출되는지가 달라지지만, mapGroupsWithState와 flatMapGroupsWithState는 자체적인 커스텀 로직으로 언제 무엇을 방출할지 결정하기 때문에 스트림의 outputMode 설정 자체가 이 연산자들의 동작에 영향을 주지 않는다 — 즉 개발자가 작성한 상태 갱신 함수 코드 안의 로직이 방출 시점과 내용을 전적으로 결정한다.
핵심 포인트
- mapGroupsWithState/flatMapGroupsWithState는 자체 커스텀 로직으로 방출을 결정 — 스트림의 outputMode(append/update/complete) 설정과 무관하게 동작