오프라인 테이블 업서트

오프라인 테이블 업서트 (Offline Table Upsert)

배치 수집되는 오프라인 테이블에서 업서트 시맨틱을 사용하는 페이지예요.

출처: Offline Table Upsert

본문

Pinot은 PR #17789을 포함하는 빌드에서 OFFLINE 테이블의 업서트를 지원해요.

배치 수정, 재생(replay), 지연 도착 레코드에 사용해요.

업서트 기능(비교 컬럼, 삭제 컬럼, TTL, 메타데이터 관리)의 전체 개요는 주요 Upsert 페이지 참고. 이 페이지는 OFFLINE 특정 설정과 차이점을 다뤄요.

오프라인 업서트 동작 방식

Pinot은 기본 키당 하나의 행을 유지해요.

중복 키의 경우 Pinot은 비교 값이 가장 큰 행을 유지해요.

comparisonColumns를 설정하지 않으면 Pinot은 테이블 시간 컬럼을 사용해요.

오프라인 업서트 테이블은 upsertConfig.comparisonColumns 또는 segmentsConfig.timeColumnName 중 하나를 반드시 정의해야 해요. 둘 다 설정되지 않으면 Pinot은 테이블 설정을 거부해요; 세그먼트 생성 시간은 암묵적 비교 값으로 사용되지 않아요.

오프라인 업서트는 전체 행을 교체해요.

부분 행을 병합하지 않아요.

오프라인 업서트 구성

기본 키 정의

스키마에 primaryKeyColumns를 추가해요.

{
  "schemaName": "orders",
  "primaryKeyColumns": ["order_id"]
}

오프라인 테이블에서 업서트 활성화

tableType을 OFFLINE로 설정.

upsertConfig.mode를 FULL로 설정.

{
  "tableName": "orders_OFFLINE",
  "tableType": "OFFLINE",
  "segmentsConfig": {
    "timeColumnName": "event_time",
    "retentionTimeUnit": "DAYS",
    "retentionTimeValue": "30",
    "replication": "3"
  },
  "upsertConfig": {
    "mode": "FULL",
    "comparisonColumns": ["event_time"]
  }
}

누락된 비교 컬럼 생성 (선택)

OFFLINE 테이블의 경우 ingestionConfig.transformConfigs가 모든 휘발성(volatility) 카테고리의 등록된 스칼라 함수를 사용할 수 있어요. 배치 파일에 행 버전이나 타임스탬프 컬럼이 없으면 스키마에서 비교 컬럼을 선언하고 수집 중에 채워요. 예를 들어:

{
  "upsertConfig": {
    "mode": "FULL",
    "comparisonColumns": ["ingestionTime"]
  },
  "ingestionConfig": {
    "transformConfigs": [
      {
        "columnName": "ingestionTime",
        "transformFunction": "now()"
      }
    ]
  }
}

스키마에서 ingestionTime을 밀리초 epoch 포맷의 LONG 날짜-시간 필드로 선언하세요. 실시간 테이블 수준 변환은 여전히 불변 함수를 요구해요.

세그먼트 수집 또는 교체

평소처럼 오프라인 세그먼트를 생성하고 업로드해요.

Pinot은 그 세그먼트를 로드할 때 업서트 시맨틱을 적용해요.

점진적 수정에는 append 방식 업로드를 사용해요.

기존 배치를 교체할 때는 refresh 방식 업로드를 사용해요.

언제 사용할까

업데이트가 파일로 도착할 때 오프라인 업서트를 사용해요.

일일 수정에 사용.

백필에 사용.

스냅샷을 오프라인 세그먼트로 재생하려 할 때 사용.

실시간 업서트와의 차이점

오프라인 업서트는 스트림을 소비하지 않아요.

저수준 소비자가 필요 없어요.

스트림 파티셔닝에 의존하지 않아요.

배치 수집과 세그먼트 교체 워크플로에 잘 맞아요.

스트림 기반 업데이트에는 스트림 수집 + Upsert를 사용하세요.

운영 참고

기본 키를 바꾸려면 전체 재구축이 필요해요.

비교 컬럼을 바꾸는 것도 전체 재구축이 필요해요.

이런 변경에는 리로드만으로는 충분하지 않아요.

하이브리드 테이블을 사용한다면 오프라인과 실시간 시간 범위가 겹치지 않도록 하세요.

서버 재시작 중 업서트 메타데이터 프리로드

PR #19271을 포함하는 빌드는 OFFLINE 테이블 데이터 매니저에 대한 업서트 프리로드를 지원해요. 오프라인 세그먼트를 로드하거나 교체하기 전에 Pinot은 지속된 validDocIds 스냅샷에서 파티션의 업서트 메타데이터를 복원해요. 이것은 서버가 재시작될 때 복구 시간을 줄일 수 있어요.

테이블 설정에서 스냅샷과 프리로드를 활성화해요:

{
  "upsertConfig": {
    "mode": "FULL",
    "snapshot": "ENABLE",
    "preload": "ENABLE"
  }
}

또한 서버에 양수의 프리로드 스레드 수를 구성해요:

pinot.server.instance.max.segment.preload.threads=4

업서트가 구성되지 않았거나 프리로드가 비활성화되면 프리로드 경로는 no-op이에요. 각 오프라인 세그먼트는 올바른 파티션 매니저를 복원할 수 있도록 파티션 메타데이터를 가져야 해요. 공유 스냅샷 수명주기와 재시작 주의사항은 더 빠른 서버 재시작을 위한 프리로드 활성화 참고.

오프라인 테이블 업서트