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] [,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 (無効) 。
• use_paimon_metadata_files_cache — Paimon のメタデータファイル cache を有効にします (デシリアライズされたマニフェストリストと manifest をキャッシュします) 。有効にするには 1、無効にするには 0 を設定します。デフォルト: 0。この設定の効き方は、table function と persistent table engine で異なります — 下記の注記を参照してください。
• paimon_incremental_read — インクリメンタル読み取りモードを有効にします。
• paimon_metadata_refresh_interval_sec — バックグラウンドでのメタデータのリフレッシュ間隔 (秒) 。0 より大きい値に設定すると、バックグラウンドタスクが定期的にオブジェクトストレージから最新のスナップショットとスキーマを取得します。デフォルト: 30。
• paimon_keeper_path — インクリメンタル読み取り状態のための Keeper パス。設定は必須で、テーブルごとに一意である必要があります。{database}、{table}、{uuid} などのマクロをサポートします。
• paimon_replica_name — インクリメンタル読み取り状態のためのレプリカ名。設定は必須で、レプリカごとに一意である必要があります。{replica} などのマクロをサポートします。

例 (実験的な Paimon エンジンとメタデータファイル cache を有効にする):

SET allow_experimental_paimon_storage_engine = 1;
SET use_paimon_metadata_files_cache = 1;

CREATE TABLE paimon_cached
ENGINE = PaimonS3(paimon_conf, filename = 'paimon_all_types');

Keeper の状態を使用したインクリメンタル読み取り:

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 — 1 回のインクリメンタル読み取りで取り込むスナップショットの最大数。ソースに未読のスナップショットが多数たまっている場合、クエリごとに取り込む数を制限してバッチサイズを制御します。0 は無制限を意味します。デフォルト: 0。

対象スナップショットの読み取り — 現在のウォーターマークにかかわらず、常にスナップショット 1 の差分を返します:

SELECT count()
FROM paimon_inc
SETTINGS paimon_target_snapshot_id = 1;

バッチごとのスナップショット数を制限する — 新しいスナップショットが3つ保留中の場合、1回のクエリで処理するのは最大2つまでです:

SELECT count()
FROM paimon_inc
SETTINGS max_consume_snapshots = 2;

APPEND モードのリフレッシャブルMaterialized Viewを使用すると、Paimon テーブルから MergeTree テーブルへデータを継続的に同期するエンドツーエンドのパイプラインを構築できます。各リフレッシュサイクルでは、Paimon から新しいインクリメンタルデータのみを読み取り、それを宛先テーブルに追記します。

ステップ 1 — インクリメンタル読み取りとメタデータのリフレッシュを有効にした Paimon のソーステーブルを作成します。

以下の例では PaimonLocal を使用します。ストレージバックエンドに応じて、engine を PaimonS3、PaimonAzure、PaimonHDFS、または自動検出される Paimon engine に置き換えてください:

SET allow_experimental_paimon_storage_engine = 1;

-- Local storage
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 storage (the `Paimon` engine defaults to the S3 implementation when no `disk` is specified)
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 より大きい場合、バックグラウンドタスクがオブジェクトストレージから最新のスナップショットとスキーマを定期的に取得するため、クエリによってメタデータ更新がトリガーされるのを待たなくても、MV のリフレッシュサイクルで新たにコミットされたデータを参照できます。デフォルトは 30 です。オブジェクトストレージや Keeper の I/O が過剰にならないよう、多数のテーブルで使用する場合は注意してください。

ステップ 2 — MergeTree の宛先テーブルを作成します (スキーマは Paimon テーブルから複製) :

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

ステップ3 — リフレッシャブルmaterialized viewを作成します:

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;

• インクリメンタル読み取りを行うには、Keeper (ZooKeeper) が設定されている必要があります。
• インクリメンタル読み取りを行うには、paimon_keeper_path を設定し、テーブルごとに一意にする必要があります。
• paimon_replica_name は、同じ Keeper パス 内でレプリカごとに一意でなければなりません。
• インクリメンタル読み取りでは at-most-once 配信が使われます。コミット済みスナップショットは、データが実際に消費される前、データファイルの収集時点で進められます。ファイル収集後にクエリが失敗した場合、スキップされたスナップショットは再試行しても再度読み取られません。
• このテーブルエンジンは読み取り専用で、データの変更はサポートされていません。
• インクリメンタル読み取りでは、Paimon ソースの過去データの削除は扱われません。アップストリームの Paimon データが削除または更新されても、ClickHouse の MergeTree 宛先テーブルにすでに書き込まれている対応する行は自動では削除されません。古くなったデータをクリーンアップするには、MergeTree テーブルに対して ALTER TABLE ... DELETE を手動で実行する必要があります。
• 基になる Paimon テーブルが同じオブジェクトストレージパスで削除されて再作成された場合 (たとえば Flink や Spark 経由) 、対応する ClickHouse テーブルを DROP してから再度 CREATE する必要があります。ClickHouse は schema-0 の作成タイムスタンプを比較して再作成を検出し、エラーを返します。古くなった 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