메인 콘텐츠로 건너뛰기
이 엔진은 Amazon S3, Azure, HDFS 및 로컬에 저장된 기존 Apache Paimon 테이블에 대한 읽기 전용 통합을 제공합니다. 스냅샷 읽기, 증분 읽기, 그리고 엔진에서 제공하는 기본적인 파티션 프루닝을 지원합니다.

테이블 생성

Paimon 테이블은 저장소에 이미 존재해야 합니다. 이 명령은 새 테이블을 생성하기 위한 DDL 매개변수를 받지 않습니다. Paimon* 테이블 생성은 allow_experimental_paimon_storage_engine으로 제어되며(기본적으로 비활성화됨), 따라서 CREATE TABLE을 실행하기 전에 이를 활성화해야 합니다.

엔진 인수

인수 설명은 각각 S3, AzureBlobStorage, HDFS, File 엔진의 인수 설명과 동일합니다. format은 Paimon 테이블의 데이터 파일 포맷을 나타냅니다. 엔진 매개변수는 이름이 지정된 컬렉션을 사용하여 지정할 수 있습니다.

예시

이름이 지정된 컬렉션 사용하기:

기능

  • 최신 테이블 스냅샷을 기준으로 읽습니다.
  • 활성화된 경우 커밋된 스냅샷 ID를 기반으로 증분 읽기를 수행합니다.
  • use_paimon_partition_pruning이 활성화된 경우 파티션 프루닝을 수행합니다.
  • 설정된 경우 메타데이터를 백그라운드에서 선택적으로 갱신합니다.
  • Atomic/Replicated 데이터베이스를 사용하는 경우 테이블 UUID가 안정적으로 유지되므로 Keeper 경로에서 {uuid} 매크로를 사용할 수 있습니다.

기본 키(primary key) 테이블

읽기 시 머지(merge-on-read)가 구현되어 있지 않으므로 기본 키 테이블은 읽을 수 없습니다. reader는 스냅샷의 데이터 파일을 단순히 합친 원시(raw) 결과를 반환하며, 여기에는 이후 업서트로 대체된 이전 행 버전이 그대로 남아 있습니다. 따라서 스키마에 primary-key가 선언된 테이블을 읽으면 예외가 발생합니다.

삭제 벡터(deletion vectors)가 있는 테이블

삭제 벡터는 적용되지 않으므로 삭제 벡터가 있는 스냅샷은 읽을 수 없습니다. 읽더라도 결과(result)에는 이후 DELETE 및 UPDATE SQL 문으로 제거된 행(rows)이 그대로 남아 있게 됩니다. 따라서 index manifest에 삭제 벡터가 나열된 스냅샷을 읽으면, deletion-vectors.enabled를 끈 후에도 예외가 발생합니다. Paimon에서 전체 컴팩션(compact_strategy => 'full')을 수행하면 삭제 벡터가 적용되며, 이후 생성된 스냅샷은 다시 읽을 수 있습니다. 증분 읽기(Incremental read)는 아직 소비되지 않은 스냅샷 중 삭제 벡터가 있는 첫 번째 스냅샷에서 멈추며, 전체 컴팩션을 수행한 후에도 그 지점에 머무릅니다. 해당 컴팩션까지의 모든 스냅샷에 동일한 삭제 벡터가 나열되어 있기 때문입니다. 커서(Cursor)도 앞으로 이동하지 않습니다. Paimon이 해당 스냅샷을 만료시키거나, 커서를 전체 컴팩션 스냅샷으로 옮겨 해당 스냅샷들을 건너뛰면 읽기가 재개됩니다. 커서를 옮기면 그 지점까지 아직 소비되지 않은 모든 스냅샷이 삭제됩니다(스냅샷을 읽을 수 없는 경우 참조):
어느 경우든 해당 삭제 벡터(deletion vectors)로 제거된 행(rows)은 증분 읽기(Incremental read)로 이미 전달된 결과에 그대로 남아 있습니다.

설정

이 엔진은 해당 객체 스토리지 엔진과 동일한 설정을 사용하며, 여기에 Paimon 전용 설정이 추가됩니다:
  • allow_experimental_paimon_storage_engine — Paimon, PaimonS3, PaimonAzure, PaimonHDFS, PaimonLocal 테이블 엔진을 생성할 수 있도록 활성화합니다. 기본값: 0(비활성화).
  • use_paimon_metadata_files_cache — Paimon 메타데이터 파일 캐시를 활성화합니다(역직렬화된 manifest 목록과 manifest를 캐시함). 활성화하려면 1, 비활성화하려면 0으로 설정합니다. 기본값: 0입니다. 이 설정의 적용 방식은 테이블 함수와 영속 테이블 엔진마다 다릅니다. 아래 참고를 확인하십시오.
  • paimon_incremental_read — 증분 읽기 모드를 활성화합니다.
  • paimon_metadata_refresh_interval_sec — 백그라운드 메타데이터 갱신 간격(초)입니다. 0보다 큰 값으로 설정하면 백그라운드 작업이 주기적으로 객체 스토리지에서 최신 스냅샷과 스키마를 가져옵니다. 기본값: 30.
  • paimon_keeper_path — 증분 읽기 상태를 위한 Keeper 경로입니다. 반드시 설정해야 하며 테이블마다 고유해야 합니다. {database}, {table}, {uuid}와 같은 매크로를 지원합니다.
  • paimon_replica_name — 증분 읽기 상태를 위한 레플리카 이름입니다. 반드시 설정해야 하며 각 레플리카마다 고유해야 합니다. {replica}와 같은 매크로를 지원합니다.
예시(실험적 Paimon 엔진과 메타데이터 파일 캐시 활성화):
use_paimon_metadata_files_cache의 적용 방식은 Paimon 테이블에 접근하는 방법에 따라 달라집니다.
  • 테이블 함수(예: SELECT ... FROM paimonS3(...)): 캐시 사용 여부는 쿼리별로 평가되므로 SELECT에 SETTINGS use_paimon_metadata_files_cache = 1을 직접 지정할 수 있습니다.
  • 영속 테이블 엔진(PaimonS3, PaimonAzure, PaimonHDFS, PaimonLocal, 그리고 Paimon 별칭): 캐시 사용 여부는 테이블 메타데이터가 초기화될 때 한 번만 결정되며, 변경 불가능한 영속 구성 요소에 저장됩니다. 메타데이터 업데이트 경로에서는 의도적으로 이 설정을 다시 읽지 않습니다. 따라서 이미 초기화된 영속 테이블에 대해 SELECT에 SETTINGS use_paimon_metadata_files_cache = 1을 지정해도 효과가 없습니다 — 이전에 확정된 결정이 계속 사용됩니다. 이를 변경하려면 테이블 메타데이터가 초기화되기 전에 use_paimon_metadata_files_cache를 설정하거나, 원하는 값으로 테이블을 DROP한 후 다시 CREATE하십시오.
서버 수준 캐시 용량(paimon_metadata_files_cache_size)은 고정되지 않습니다. 이는 SYSTEM RELOAD CONFIG를 통해 변경할 수 있는 런타임 설정이며, 이미 초기화된 테이블에도 즉시 적용됩니다.

증분 읽기 예시

Keeper state를 이용한 증분 읽기:

증분 읽기를 위한 쿼리 수준 설정

다음 설정은 쿼리 수준 설정으로, CREATE TABLE이 아니라 SELECT ... SETTINGS를 통해 전달됩니다. 이 설정은 증분 읽기의 쿼리별 동작을 제어합니다:
  • paimon_target_snapshot_id — 지정한 스냅샷의 델타만 읽습니다. Keeper의 커밋된 워터마크는 앞으로 이동하지 않으므로, 동일한 스냅샷을 원하는 만큼 다시 읽을 수 있습니다. 기본값: -1(비활성화).
  • max_consume_snapshots — 단일 증분 읽기에서 처리할 스냅샷의 최대 개수입니다. source에 아직 읽지 않은 스냅샷이 많이 누적된 경우, 쿼리당 처리하는 개수를 제한해 Batch 크기를 제어합니다. 0은 제한이 없음을 의미합니다. 기본값: 0.
특정 스냅샷 읽기 — 현재 워터마크와 관계없이 항상 스냅샷 1의 델타를 반환합니다:
배치당 스냅샷 수 제한 — 새 스냅샷 3개가 대기 중이면 쿼리당 최대 2개만 처리합니다:

웨어하우스(warehouse) 되감기

paimon_keeper_path에 있는 Keeper 커서(Cursor)는 스트림을 어디까지 소비했는지 기록하며, 증분 읽기(Incremental read)는 웨어하우스가 항상 앞으로만 진행한다고 가정합니다. Paimon 스냅샷 id는 단조 증가하며 재사용되지 않습니다. 오래된 스냅샷을 만료시키는 것은 문제가 되지 않습니다. 만료는 앞부분의 id만 제거하고 그 이후의 id는 그대로 두기 때문입니다. 웨어하우스를 뒤로 되돌리면 이 가정이 깨집니다. 오래된 백업(backup)에서 웨어하우스를 복원하거나, 다른 엔진으로 롤백하거나, 같은 경로에서 Paimon 테이블(Paimon table)을 삭제(dropping)한 뒤 다시 생성하면 모두 스냅샷 id가 되감기며, 그 결과 writer는 커서가 이미 소비한 id를 재사용하게 됩니다. 웨어하우스를 되감을 때는 같은 작업에서 커서도 함께 초기화해야 합니다. id가 재사용되면 ClickHouse는 컨슈머가 어떤 스냅샷을 이미 수신했는지 재구성할 수 없습니다. 따라서 되감기 후 커서를 그대로 두면 전달 동작이 정의되지 않으며, 재사용된 id의 스냅샷을 건너뛸 수 있습니다. 되감기로 인해 커서가 웨어하우스의 최신 스냅샷보다 뒤쪽을 가리키게 되면, 읽기는 새 데이터가 없다고 보고하지 않고 INVALID_STATE로 실패하며, 오류 메시지에 복구 명령이 표시됩니다. 아무것도 읽지 않고 커서도 변경되지 않으므로, 문제를 해결할 때까지 이후의 모든 폴링이 같은 방식으로 실패합니다:
복구 목적으로 committed_snapshot 노드를 삭제하지 마십시오. 커서가 없으면 “한 번도 소비되지 않음”으로 간주되므로, 다음 읽기는 이전 위치에서 재개되지 않고 전체 테이블을 처음부터 다시 읽게 됩니다. 커서를 초기화하기 전에 갱신 가능 구체화 뷰를 포함하여 paimon_keeper_path를 공유하는 모든 컨슈머를 일시 중지하고, 전송 중인 읽기가 모두 완료될 때까지 기다리십시오. 읽기의 커밋은 해당 읽기가 관찰한 커서를 전제 조건으로 합니다. 관찰 이후 커밋 전에 커서가 변경되면 해당 읽기는 INVALID_STATE 오류로 실패하고 아무것도 전달하지 않으며, 사용자가 설정한 값은 그대로 유지됩니다. 단, 이미 커밋된 읽기는 커서가 초기화된 후에도 해당 배치를 전달할 수 있으므로, 커서를 되감으면 그 배치가 중복으로 전달될 수 있습니다. processing_lock을 수동으로 삭제하거나 대체하지 마십시오. 이 노드는 증분 읽기를 실행 중인 ClickHouse Keeper 세션이 소유하는 일시적 노드이며, 그 수명 주기는 운영자가 복구 용도로 다루는 인터페이스가 아닙니다.

스냅샷을 읽을 수 없는 경우

Paimon에서 만료된 스냅샷은 자동으로 건너뜁니다. 만료 시에는 스냅샷 ID의 앞부분(접두사)이 제거되므로, 웨어하우스(warehouse)에서 가장 오래된 스냅샷보다 앞선 스냅샷은 이미 사라진 것으로 판단되며 커서(Cursor)는 해당 구간을 지나 이동합니다. 그 밖의 이유로 스냅샷을 읽지 못하면(예: 일시적인 객체 스토리지 오류, 손상된 스냅샷 파일) 쿼리가 실패하고 커서는 현재 위치에 그대로 남습니다. 이러한 실패를 허용하는 설정은 의도적으로 제공하지 않습니다. 읽지 않은 스냅샷을 건너뛰면 해당 스냅샷에 커밋된 데이터가 영구적으로 삭제되며, 「오류 허용」 스위치를 상시 켜 둘 수 있다면 이후 발생하는 모든 일시적인 네트워크 장애가 아무런 경고 없이 데이터 손실로 이어집니다. 커서는 변경되지 않으므로 일시적인 오류에는 별도의 조치가 전혀 필요하지 않습니다. 다음 폴링에서 동일한 범위를 다시 읽으면 성공합니다. 스냅샷을 정말로 읽을 수 없고 스트림을 계속 진행해야 한다면, 해당 스냅샷을 명시적으로 포기하십시오. 오류 메시지에 사용할 명령이 표시되지만, 그에 따르는 대가에 유의하십시오. 실패한 읽기에서는 아무것도 전달되지 않았으므로, 커서를 읽을 수 없는 스냅샷으로 옮기면 해당 스냅샷 하나만이 아니라 그 스냅샷까지 아직 소비되지 않은 모든 스냅샷을 포기하게 됩니다. 커서가 1에 있고 스냅샷 2, 3, 4가 대기 중이며 그중 3을 읽을 수 없는 경우의 예는 다음과 같습니다.
읽을 수 있는 스냅샷을 보존하려면 먼저 읽을 수 없는 스냅샷 직전까지 비우십시오. 폴링할 때마다 스냅샷 하나를 소비하고 커서(Cursor)를 앞으로 이동하며, 읽을 수 없는 스냅샷에 도달할 때까지 이 과정이 반복됩니다.
어느 쪽이든 이 결정은 설정을 통해 추론되는 것이 아니라 운영자가 명시적으로 수행한 조치로 기록됩니다.

갱신 가능 구체화 뷰를 사용한 Paimon에서 MergeTree로의 동기화

APPEND 모드의 갱신 가능 구체화 뷰를 사용하면 Paimon 테이블의 데이터를 MergeTree 테이블로 지속적으로 동기화하는 end-to-end 파이프라인을 구축할 수 있습니다. 각 갱신 주기마다 Paimon에서 새로운 증분 데이터만 읽어 대상 테이블에 추가합니다. 1단계 — 증분 읽기와 메타데이터 갱신을 활성화한 Paimon 원본 테이블을 생성합니다. 아래 예시에서는 PaimonLocal을 사용합니다. 스토리지 백엔드에 맞게 엔진을 PaimonS3, PaimonAzure, PaimonHDFS 또는 자동 감지하는 Paimon 엔진으로 대체하십시오:
paimon_metadata_refresh_interval_sec는 백그라운드 메타데이터 갱신 주기를 초 단위로 설정합니다. 0보다 크면 백그라운드 작업이 객체 스토리지에서 최신 스냅샷(snapshot)과 스키마(schema)를 주기적으로 가져오므로, 쿼리가 메타데이터 업데이트를 트리거할 때까지 기다리지 않고도 MV 갱신 주기(refresh cycle)에서 새로 커밋된 데이터를 확인할 수 있습니다. 기본값은 30입니다. 객체 스토리지 및 Keeper I/O가 과도해지지 않도록 많은 테이블에 사용할 때는 주의해서 사용하십시오. 2단계 — MergeTree 대상 테이블 생성(스키마는 Paimon 테이블에서 복제):
3단계 — 갱신 가능 구체화 뷰를 생성합니다:
10초마다 MV가 SELECT * FROM paimon_mv_source를 실행하며, 마지막으로 커밋된 스냅샷 이후에 추가된 행만 반환해 paimon_mv_dest에 덧붙입니다. 정리:
백그라운드 갱신으로 인해 DDL 작업이 차단되지 않도록, 삭제하기 전에 MV를 중지하십시오.

제한 사항

  • 증분 읽기를 사용하려면 Keeper(ZooKeeper)가 구성되어 있어야 합니다.
  • 증분 읽기를 사용하려면 paimon_keeper_path를 설정해야 하며, 테이블별로 고유해야 합니다.
  • paimon_replica_name은 동일한 Keeper 경로 내에서 각 레플리카마다 고유해야 합니다.
  • 증분 읽기는 at-most-once 전달 방식을 사용합니다. 즉, 데이터가 실제로 처리되기 전에 데이터 파일을 수집하는 시점에 커밋된 스냅샷이 다음으로 넘어갑니다. 파일 수집 후 쿼리가 실패하면 건너뛴 스냅샷은 재시도해도 다시 읽지 않습니다.
  • 이 테이블 엔진은 읽기 전용이며, 데이터 수정은 지원되지 않습니다.
  • 증분 읽기는 Paimon source의 과거 데이터 삭제를 처리하지 않습니다. 업스트림 Paimon 데이터가 삭제되거나 업데이트되더라도 ClickHouse MergeTree 대상 테이블에 이미 기록된 해당 행은 자동으로 제거되지 않습니다. 오래된 데이터를 정리하려면 MergeTree 테이블에서 ALTER TABLE ... DELETE를 수동으로 실행해야 합니다.
  • 기반 Paimon 테이블이 동일한 객체 스토리지 경로에 삭제된 후 다시 생성되면(예: Flink 또는 Spark를 통해) 해당 ClickHouse 테이블도 DROP한 뒤 다시 CREATE해야 합니다. ClickHouse는 schema-0 생성 timestamp를 비교해 재생성을 감지하고 오류를 발생시킵니다. 오래된 ClickHouse 테이블은 다시 생성하기 전까지 사용할 수 없습니다.

별칭

Paimon 테이블 엔진은 disk 설정을 바탕으로 스토리지 백엔드를 자동으로 감지한 뒤, 이에 따라 PaimonS3, PaimonAzure 또는 PaimonLocal을 사용합니다. disk를 지정하지 않으면 기본적으로 PaimonS3 구현이 사용됩니다.

가상 컬럼

  • _path — 파일 경로입니다. 유형: LowCardinality(String).
  • _file — 파일 이름입니다. 유형: LowCardinality(String).
  • _size — 파일 크기(바이트)입니다. 유형: Nullable(UInt64). 파일 크기를 알 수 없으면 값은 NULL입니다.
  • _time — 파일의 마지막 수정 시간입니다. 유형: Nullable(DateTime). 시간을 알 수 없으면 값은 NULL입니다.
  • _etag — 파일의 etag입니다. 유형: LowCardinality(String). etag를 알 수 없으면 값은 NULL입니다.

지원되는 데이터 타입

지원되는 파티션

Paimon 파티션 키에서 지원되는 데이터 타입은 다음과 같습니다:
  • CHAR
  • VARCHAR
  • BOOLEAN
  • DECIMAL
  • TINYINT
  • SMALLINT
  • INTEGER
  • DATE
  • TIME
  • TIMESTAMP
  • TIMESTAMP WITH LOCAL TIME ZONE
  • BIGINT
  • FLOAT
  • DOUBLE