구조적 스트리밍에 대한 출력 모드 선택

아티클
01/22/2025

이 문서에서는 상태 저장 스트리밍에 대한 출력 모드 선택에 대해 설명합니다. 집계를 포함하는 상태 저장 스트림만 출력 모드 구성이 필요합니다.

조인은 추가 출력 모드만 지원하며 출력 모드는 중복 제거에 영향을 주지 않습니다. 임의의 상태 저장 연산자 mapGroupsWithState와 flatMapGroupsWithState는 자체 사용자 정의 로직을 사용하여 레코드를 방출하므로 스트림의 출력 모드가 해당 동작에 영향을 미치지 않습니다.

상태 비저장 스트리밍의 경우 모든 출력 모드가 동일하게 작동합니다.

출력 모드를 올바르게 구성하려면 상태 저장 스트리밍, 워터마크 및 트리거를 이해해야 합니다. 다음 문서를 참조하세요.

출력 모드란?

구조적 스트리밍 쿼리의 출력 모드는 각 트리거 중에 쿼리 연산자가 내보내는 레코드를 결정합니다. 내보낼 수 있는 레코드의 세 가지 유형은 다음과 같습니다.

이후 처리가 변경되지 않는 레코드입니다.
마지막 트리거 이후 변경된 레코드입니다.
상태 테이블의 모든 레코드입니다.

상태 저장 연산자가 생성한 특정 행이 트리거에서 트리거로 변경될 수 있으므로 상태 저장 연산자에게 내보내야 할 레코드 형식을 아는 것이 중요합니다. 예를 들어 스트리밍 집계 연산자가 특정 창에 대해 더 많은 행을 받으면 해당 창의 집계 값이 트리거 간에 변경될 수 있습니다.

상태 비지방 연산자의 경우 레코드 형식을 구분해도 연산자의 동작에는 영향을 주지 않습니다. 트리거 중에 상태 비스테이션 연산자가 내보내는 레코드는 항상 해당 트리거 중에 처리되는 원본 레코드입니다.

사용 가능한 출력 모드

운영자에게 특정 트리거 중에 내보낸 레코드를 알려주는 세 가지 출력 모드가 있습니다.

출력 모드	설명
추가 모드(기본값)	기본적으로 스트리밍 쿼리는 추가 모드에서 실행됩니다. 이 모드에서 연산자는 이후 트리거에서 변경되지 않는 행만 내보낸다. 상태를 저장하는 연산자는 워터마크를 사용하여 이런 일이 발생할 때를 결정합니다.
업데이트 모드	업데이트 모드에서 연산자는 내보낸 레코드가 후속 트리거에서 변경될 수 있더라도 트리거 중에 변경된 모든 행을 내보냅니다.
전체 모드	전체 모드는 스트리밍 집계에서만 작동합니다. 전체 모드에서는 연산자가 생성한 모든 결과 행이 다운스트림으로 내보내집니다.

프로덕션 고려 사항

많은 상태 저장 스트리밍 작업의 경우 추가 모드와 업데이트 모드 중에서 선택해야 합니다. 다음 섹션에서는 결정을 알릴 수 있는 고려 사항을 간략하게 설명합니다.

참고 항목

전체 모드에는 일부 애플리케이션이 있지만 데이터 크기 조정으로 성능이 저조할 수 있습니다. Databricks는 많은 상태 저장 작업에 대한 의미 체계 보장을 얻기 위해 증분 처리를 사용할 때 전체 모드와 관련된 구체화된 뷰를 사용하는 것을 권장합니다. Databricks SQL에서 구체화된 뷰 사용을 참조하기 .

애플리케이션 의미 체계

애플리케이션 의미 체계는 다운스트림 애플리케이션에서 스트리밍 데이터를 사용하는 방법을 설명합니다.

다운스트림 서비스가 모든 다운스트림 쓰기에 대해 단일 작업을 수행해야 하는 경우 대부분의 경우 추가 모드를 사용합니다. 예를 들어 싱크에 기록된 모든 새 레코드에 대한 알림을 보내는 다운스트림 알림 서비스가 있는 경우 추가 모드는 각 레코드가 한 번만 기록되도록 합니다. 업데이트 모드는 상태 정보가 변경될 때마다 레코드를 작성하므로 많은 업데이트가 발생합니다.

다운스트림 서비스에 새로운 결과가 필요한 경우 업데이트 모드를 사용하면 싱크가 가능한 up-to-date로 유지됩니다. 예를 들어 실시간으로 기능을 읽는 기계 학습 모델 또는 실시간 집계를 추적하는 분석 대시보드가 있습니다.

연산자 및 싱크 호환성

구조적 스트리밍은 Apache Spark에서 사용할 수 있는 모든 작업을 지원하지 않으며 일부 스트리밍 작업은 모든 출력 모드에서 지원되지 않습니다. 운영자 제한 사항에 대한 자세한 내용은 OSS 스트리밍 문서를 참조하세요.

모든 싱크가 모든 출력 모드를 지원하는 것은 아닙니다. 모든 Unity 카탈로그 관리 테이블을 지원하는 Delta Lake와 Kafka는 모두 모든 출력 모드를 지원합니다. 싱크 호환성에 대한 자세한 내용은 OSS 스트리밍 문서를 참조하세요.

대기 시간 및 비용

출력 모드는 레코드를 작성하기 전에 경과해야 하는 시간에 영향을 줍니다. 기록된 데이터의 빈도와 양은 스트리밍 파이프라인과 관련된 비용에 영향을 줄 수 있습니다.

추가 모드는 상태 저장 연산자가 상태 저장 결과가 완료된 후에만 결과를 내보내도록 강제합니다. 이는 워터마크 지연만큼 이상입니다. 덧붙이기 출력 모드에서 1 hour 워터마크 지연은 레코드가 다운스트림으로 내보내지기 전에 적어도 1시간 지연됨을 의미합니다.

업데이트 모드는 집계 값당 트리거당 하나의 쓰기를 생성합니다. 싱크가 레코드당 쓰기마다 요금을 부과하는 경우, 워터마크 지연이 지나기 전에 레코드가 여러 번 업데이트되면 비용이 많이 발생할 수 있습니다.

구성 예

다음 코드 예제에서는 Unity 카탈로그 테이블에 대한 업데이트를 스트리밍하기 위한 출력 모드를 구성하는 방법을 보여 줍니다.

Python

# Append output mode (default)
(df.writeStream
  .toTable("target_table")
)

# Append output mode (same as default behavior)
(df.writeStream
  .outputMode("append")
  .toTable("target_table")
)

# Update output mode
(df.writeStream
  .outputMode("update")
  .toTable("target_table")
)

# Complete output mode
(df.writeStream
  .outputMode("complete")
  .toTable("target_table")
)

Scala

// Append output mode (default)
df.writeStream
  .toTable("target_table")

// Append output mode (same as default behavior)
df.writeStream
  .outputMode("append")
  .toTable("target_table")

// Update output mode
df.writeStream
  .outputMode("update")
  .toTable("target_table")

// Complete output mode
df.writeStream
  .outputMode("complete")
  .toTable("target_table")

PySpark DataStreamWriter.outputMode 또는 Scala DataStreamWriter.outputMode에 대한 OSS 문서를 참조하세요.

상태 저장 스트리밍 및 출력 모드 예제

다음 예제는 출력 모드가 상태 저장 스트리밍을 위해 워터마크와 상호 작용하는 방법을 추론하는 데 도움이 됩니다.

워터마크 지연이 15분인 매장에서 매시간 발생하는 총 수익을 계산하는 스트리밍 집계를 생각해 봅시다. 첫 번째 마이크로배치는 다음 레코드를 처리합니다.

오후 2시 40분 $15
오후 2시 30분 $10
오후 3시 10분 $30

이 시점에서 엔진의 워터마크는 오후 2시 55분으로, 최대 시간(오후 3시 10분)에서 15분(지연)을 빼기 때문입니다. 스트리밍 집계 연산자의 상태는 다음과 같습니다.

[2pm, 3pm]: $25
[3pm, 4pm]: $30

다음 표에서는 각 출력 모드에서 발생하는 일을 간략하게 설명합니다.

출력 모드	결과 및 이유
Append	스트리밍 집계 연산자는 다운스트림을 내보내지 않습니다. 이 두 창은 후속 트리거와 함께 새 값이 표시될 때 변경될 수 있기 때문입니다. 오후 2시 55분의 워터마크는 오후 2시 55분 이후의 레코드가 여전히 도착할 수 있음을 나타내며 해당 레코드는 `[2pm, 3pm]` 창 또는 `[3pm, 4pm]` 창에 속할 수 있습니다.
업데이트	두 레코드가 모두 업데이트를 받았기 때문에 연산자는 두 레코드를 모두 내보낸다.
Complete	연산자는 모든 레코드를 내보낸다.

이제 스트림이 하나 이상의 레코드를 수신한다고 가정합니다.

오후 3시 20분 $20

워터마크는 엔진이 오후 3시 20분부터 15분을 빼기 때문에 오후 3시 05분으로 업데이트됩니다. 이 시점에서 스트리밍 집계 연산자의 상태는 다음과 같습니다.

[2pm, 3pm]: $25
[3pm, 4pm]: $50