Paimon 테이블 엔진

이 엔진은 Amazon S3, Azure, HDFS 및 로컬에 저장된 기존 Apache Paimon 테이블에 대한 읽기 전용 통합을 제공합니다.

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

​

테이블 생성

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

SET allow_experimental_paimon_storage_engine = 1;

CREATE TABLE paimon_table_s3
    ENGINE = PaimonS3(url,  [, access_key_id, secret_access_key] [,format] [,structure] [,compression])

CREATE TABLE paimon_table_azure
    ENGINE = PaimonAzure(connection_string|storage_account_url, container_name, blobpath, [,account_name], [,account_key] [,format] [,compression_method])

CREATE TABLE paimon_table_hdfs
    ENGINE = PaimonHDFS(path_to_table, [,format] [,compression_method])

CREATE TABLE paimon_table_local
    ENGINE = PaimonLocal(path_to_table, [,format] [,compression_method])

​

엔진 인수

인수 설명은 각각 S3, AzureBlobStorage, HDFS, File 엔진의 인수 설명과 동일합니다. format은 Paimon 테이블의 데이터 파일 포맷을 나타냅니다.

엔진 매개변수는 이름이 지정된 컬렉션을 사용하여 지정할 수 있습니다.

​

예시

CREATE TABLE paimon_table ENGINE=PaimonS3('http://test.s3.amazonaws.com/clickhouse-bucket/test_table', 'test', 'test')

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

<clickhouse>
    <named_collections>
        <paimon_conf>
            <url>http://test.s3.amazonaws.com/clickhouse-bucket/</url>
            <access_key_id>test</access_key_id>
            <secret_access_key>test</secret_access_key>
        </paimon_conf>
    </named_collections>
</clickhouse>

CREATE TABLE paimon_table ENGINE=PaimonS3(paimon_conf, filename = 'test_table')

​

기능

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

​

설정

이 엔진은 해당 객체 스토리지 엔진과 동일한 설정을 사용하며, 여기에 Paimon 전용 설정이 추가됩니다:

• allow_experimental_paimon_storage_engine — Paimon, PaimonS3, PaimonAzure, PaimonHDFS, PaimonLocal 테이블 엔진을 생성할 수 있도록 활성화합니다. 기본값: 0(비활성화).
• paimon_incremental_read — 증분 읽기 모드를 활성화합니다.
• paimon_metadata_refresh_interval_sec — 백그라운드 메타데이터 갱신 간격(초)입니다. 0보다 큰 값으로 설정하면 백그라운드 작업이 주기적으로 객체 스토리지에서 최신 스냅샷과 스키마를 가져옵니다. 기본값: 30.
• paimon_keeper_path — 증분 읽기 상태를 위한 Keeper 경로입니다. 반드시 설정해야 하며 테이블마다 고유해야 합니다. {database}, {table}, {uuid}와 같은 매크로를 지원합니다.
• paimon_replica_name — 증분 읽기 상태를 위한 레플리카 이름입니다. 반드시 설정해야 하며 각 레플리카마다 고유해야 합니다. {replica}와 같은 매크로를 지원합니다.

​

증분 읽기 예시

Keeper state를 이용한 증분 읽기:

CREATE TABLE paimon_inc
ENGINE = PaimonS3(paimon_conf, filename = 'paimon_all_types')
SETTINGS
    paimon_incremental_read = 1,
    paimon_keeper_path = '/clickhouse/{database}/{uuid}',
    paimon_replica_name = '{replica}';

​

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

다음 설정은 쿼리 수준 설정으로, CREATE TABLE이 아니라 SELECT ... SETTINGS를 통해 전달됩니다. 이 설정은 증분 읽기의 쿼리별 동작을 제어합니다:

• paimon_target_snapshot_id — 지정한 스냅샷의 델타만 읽습니다. Keeper의 커밋된 워터마크는 앞으로 이동하지 않으므로, 동일한 스냅샷을 원하는 만큼 다시 읽을 수 있습니다. 기본값: -1(비활성화).
• max_consume_snapshots — 단일 증분 읽기에서 처리할 스냅샷의 최대 개수입니다. source에 아직 읽지 않은 스냅샷이 많이 누적된 경우, 쿼리당 처리하는 개수를 제한해 Batch 크기를 제어합니다. 0은 제한이 없음을 의미합니다. 기본값: 0.

특정 스냅샷 읽기 — 현재 워터마크와 관계없이 항상 스냅샷 1의 델타를 반환합니다:

SELECT count()
FROM paimon_inc
SETTINGS paimon_target_snapshot_id = 1;

배치당 스냅샷 수 제한 — 새 스냅샷 3개가 대기 중이면 쿼리당 최대 2개만 처리합니다:

SELECT count()
FROM paimon_inc
SETTINGS max_consume_snapshots = 2;

​

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

APPEND 모드의 갱신 가능 구체화 뷰를 사용하면 Paimon 테이블의 데이터를 MergeTree 테이블로 지속적으로 동기화하는 end-to-end 파이프라인을 구축할 수 있습니다. 각 갱신 주기마다 Paimon에서 새로운 증분 데이터만 읽어 대상 테이블에 추가합니다.

1단계 — 증분 읽기와 메타데이터 갱신을 활성화한 Paimon 원본 테이블을 생성합니다.

아래 예시에서는 PaimonLocal을 사용합니다. 스토리지 백엔드에 맞게 엔진을 PaimonS3, PaimonAzure, PaimonHDFS 또는 Paimon 별칭으로 대체하십시오:

SET allow_experimental_paimon_storage_engine = 1;

-- 로컬 스토리지
CREATE TABLE paimon_mv_source
ENGINE = PaimonLocal('/path/to/paimon/table')
SETTINGS
    paimon_incremental_read = 1,
    paimon_keeper_path = '/clickhouse/tables/{uuid}',
    paimon_replica_name = '{replica}',
    paimon_metadata_refresh_interval_sec = 1;

-- S3 스토리지 (Paimon은 PaimonS3의 별칭(alias))
CREATE TABLE paimon_mv_source
ENGINE = Paimon('http://minio:9000/bucket/path/to/table', 'access_key', 'secret_key')
SETTINGS
    paimon_incremental_read = 1,
    paimon_keeper_path = '/clickhouse/tables/{uuid}',
    paimon_replica_name = '{replica}',
    paimon_metadata_refresh_interval_sec = 1;

paimon_metadata_refresh_interval_sec는 백그라운드 메타데이터 갱신 주기를 초 단위로 설정합니다. 0보다 크면 백그라운드 작업이 객체 스토리지에서 최신 스냅샷(snapshot)과 스키마(schema)를 주기적으로 가져오므로, 쿼리가 메타데이터 업데이트를 트리거할 때까지 기다리지 않고도 MV 갱신 주기(refresh cycle)에서 새로 커밋된 데이터를 확인할 수 있습니다. 기본값은 30입니다. 객체 스토리지 및 Keeper I/O가 과도해지지 않도록 많은 테이블에 사용할 때는 주의해서 사용하십시오.

2단계 — MergeTree 대상 테이블 생성(스키마는 Paimon 테이블에서 복제):

CREATE TABLE paimon_mv_dest AS paimon_mv_source
ENGINE = MergeTree()
ORDER BY tuple();

3단계 — 갱신 가능 구체화 뷰를 생성합니다:

CREATE MATERIALIZED VIEW paimon_mv
REFRESH EVERY 10 SECOND
APPEND
TO paimon_mv_dest
AS SELECT * FROM paimon_mv_source;

10초마다 MV가 SELECT * FROM paimon_mv_source를 실행하며, 마지막으로 커밋된 스냅샷 이후에 추가된 행만 반환해 paimon_mv_dest에 덧붙입니다.

정리:

SYSTEM STOP VIEW paimon_mv;
DROP VIEW IF EXISTS paimon_mv SYNC;
DROP TABLE IF EXISTS paimon_mv_dest SYNC;
DROP TABLE IF EXISTS paimon_mv_source SYNC;

백그라운드 갱신으로 인해 DDL 작업이 차단되지 않도록, 삭제하기 전에 MV를 중지하십시오.

​

제한 사항

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

​

별칭

테이블 엔진 Paimon은 이제 PaimonS3의 별칭으로 사용됩니다.

​

가상 컬럼

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

​

지원되는 데이터 타입

Paimon 데이터 타입	ClickHouse 데이터 타입
BOOLEAN	Int8
TINYINT	Int8
SMALLINT	Int16
INTEGER	Int32
BIGINT	Int64
FLOAT	Float32
DOUBLE	Float64
STRING,VARCHAR,BYTES,VARBINARY	String
DATE	Date
TIME(p),TIME	Time(‘UTC’)
TIMESTAMP(p) WITH LOCAL TIME ZONE	DateTime64
TIMESTAMP(p)	DateTime64(‘UTC’)
CHAR	FixedString(1)
BINARY(n)	FixedString(n)
DECIMAL(P,S)	Decimal(P,S)
ARRAY	Array
MAP	Map

​

지원되는 파티션

Paimon 파티션 키에서 지원되는 데이터 타입은 다음과 같습니다:

• CHAR
• VARCHAR
• BOOLEAN
• DECIMAL
• TINYINT
• SMALLINT
• INTEGER
• DATE
• TIME
• TIMESTAMP
• TIMESTAMP WITH LOCAL TIME ZONE
• BIGINT
• FLOAT
• DOUBLE