Moteur de table Paimon

Ce moteur fournit une intégration en lecture seule avec des tables Apache Paimon existantes dans Amazon S3, Azure, HDFS ou stockées localement. Il prend en charge la lecture de snapshots, la lecture incrémentielle et l’élagage basique des partitions assuré par le moteur.

Notez que la table Paimon doit déjà exister dans le stockage ; cette commande n'accepte pas de paramètres DDL pour créer une nouvelle table. La création de tables Paimon* est conditionnée par allow_experimental_paimon_storage_engine (désactivé par défaut) ; activez-le donc avant d'exécuter 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])

La description des arguments est identique à celle des arguments des moteurs S3, AzureBlobStorage, HDFS et File, respectivement. format désigne le format des fichiers de données de la table Paimon.

Les paramètres du moteur peuvent être spécifiés à l’aide de collections nommées

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

Utilisation des collections nommées :

<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')

• Lecture des snapshots à partir du dernier snapshot de la table.
• Lecture incrémentielle basée sur l’ID de snapshot validé, lorsqu’elle est activée.
• Élagage des partitions lorsque use_paimon_partition_pruning est activé.
• Actualisation facultative des métadonnées en arrière-plan lorsqu’elle est configurée.
• UUID de table stable lors de l’utilisation de bases de données Atomic/Replicated, permettant d’utiliser les macros {uuid} dans les chemins Keeper.

Ce moteur utilise les mêmes paramètres que les moteurs de stockage objet correspondants et ajoute des paramètres spécifiques à Paimon :

• allow_experimental_paimon_storage_engine — active la création des moteurs de table Paimon, PaimonS3, PaimonAzure, PaimonHDFS et PaimonLocal. Par défaut : 0 (désactivé).
• use_paimon_metadata_files_cache — active le cache des fichiers de métadonnées Paimon (met en cache les manifest lists et manifests désérialisés). Définissez 1 pour l’activer et 0 pour le désactiver. Par défaut : 0. La façon dont ce paramètre s’applique diffère entre les fonctions de table et les moteurs de table persistants — voir la note ci-dessous.
• paimon_incremental_read — active le mode de lecture incrémentielle.
• paimon_metadata_refresh_interval_sec — intervalle de rafraîchissement des métadonnées en arrière-plan, en secondes. Lorsqu’il est défini sur une valeur supérieure à 0, une tâche en arrière-plan récupère périodiquement le dernier snapshot et le schéma depuis le stockage objet. Par défaut : 30.
• paimon_keeper_path — chemin Keeper pour l’état de lecture incrémentielle. Doit être défini et unique pour chaque table ; prend en charge des macros telles que {database}, {table}, {uuid}.
• paimon_replica_name — nom de réplique pour l’état de lecture incrémentielle. Doit être défini et unique pour chaque réplique ; prend en charge des macros telles que {replica}.

Exemple (activez le moteur Paimon expérimental et le cache des fichiers de métadonnées) :

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');

Lecture incrémentielle avec l’état de 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}';

Les paramètres suivants sont au niveau de la requête (passés via SELECT ... SETTINGS, et non dans CREATE TABLE). Ils contrôlent le comportement des lectures incrémentales pour chaque requête :

• paimon_target_snapshot_id — lit uniquement le delta du snapshot spécifié. Le watermark enregistré dans Keeper n’est pas avancé ; le même snapshot peut donc être relu autant de fois que nécessaire. Par défaut : -1 (désactivé).
• max_consume_snapshots — nombre maximal de snapshots à consommer lors d’une seule lecture incrémentale. Lorsque la source a accumulé de nombreux snapshots non lus, ce paramètre limite le nombre de snapshots consommés par requête afin de contrôler la taille du lot. 0 signifie aucune limite. Par défaut : 0.

Lecture ciblée d’un snapshot — renvoie toujours le delta du snapshot 1, indépendamment du watermark actuel :

SELECT count()
FROM paimon_inc
SETTINGS paimon_target_snapshot_id = 1;

Limiter le nombre de snapshots par lot — si trois nouveaux snapshots sont en attente, n’en traitez pas plus de deux par requête :

SELECT count()
FROM paimon_inc
SETTINGS max_consume_snapshots = 2;

Vous pouvez créer un pipeline de bout en bout qui synchronise en continu les données d’une table Paimon vers une table MergeTree à l’aide d’une vue matérialisée actualisable en mode APPEND. Chaque cycle d’actualisation lit uniquement les nouvelles données incrémentielles depuis Paimon et les ajoute à la table de destination.

Étape 1 — Créez la table source Paimon avec la lecture incrémentielle et le rafraîchissement des métadonnées activés.

L’exemple ci-dessous utilise PaimonLocal. Remplacez le moteur par PaimonS3, PaimonAzure, PaimonHDFS ou le moteur Paimon à détection automatique, selon votre système de stockage :

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 définit l’intervalle de rafraîchissement des métadonnées en arrière-plan, en secondes. Lorsqu’il est supérieur à 0, une tâche en arrière-plan récupère périodiquement le dernier snapshot et le schéma depuis le stockage objet, afin que le cycle d’actualisation de la MV puisse voir les données nouvellement validées sans attendre qu’une requête déclenche la mise à jour des métadonnées. La valeur par défaut est 30. À utiliser avec précaution sur un grand nombre de tables afin d’éviter des E/S excessives sur le stockage objet et Keeper.

Étape 2 — Créez la table de destination MergeTree (schéma cloné depuis la table Paimon) :

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

Étape 3 — Créez la vue matérialisée actualisable :

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

Toutes les 10 secondes, la MV lance un SELECT * FROM paimon_mv_source, qui ne renvoie que les lignes ajoutées depuis le dernier snapshot validé, puis les ajoute à paimon_mv_dest.

Nettoyage :

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;

• La lecture incrémentielle nécessite que Keeper (ZooKeeper) soit configuré.
• La lecture incrémentielle nécessite que paimon_keeper_path soit défini et unique pour chaque table.
• paimon_replica_name doit être unique pour chaque réplique dans le même chemin Keeper.
• La lecture incrémentielle utilise un mode de livraison « au plus une fois » : le snapshot validé est avancé lorsque les fichiers de données sont collectés, avant que les données ne soient réellement consommées. Si la requête échoue après la collecte des fichiers, les snapshots ignorés ne seront pas relus en cas de nouvelle tentative.
• Le moteur de table est en lecture seule ; la modification des données n'est pas prise en charge.
• La lecture incrémentielle ne gère pas les suppressions de données historiques depuis la source Paimon. Si les données Paimon en amont sont supprimées ou mises à jour, les lignes correspondantes déjà écrites dans une table de destination ClickHouse MergeTree ne seront pas automatiquement supprimées. Vous devez exécuter manuellement ALTER TABLE ... DELETE sur la table MergeTree pour nettoyer les données obsolètes.
• Si la table Paimon sous-jacente est supprimée puis recréée au même chemin du stockage d’objets (par exemple via Flink ou Spark), vous devez DROP puis re-CREATE la table ClickHouse correspondante. ClickHouse détecte cette recréation en comparant le timestamp de création de schema-0 et renvoie une erreur ; la table ClickHouse obsolète ne peut pas être utilisée tant qu’elle n’a pas été recréée.

Le moteur de table Paimon détecte automatiquement le backend de stockage à partir du paramètre disk et utilise en conséquence PaimonS3, PaimonAzure ou PaimonLocal. Lorsqu'aucun disk n'est spécifié, il utilise par défaut l'implémentation PaimonS3.

• _path — Chemin du fichier. Type : LowCardinality(String).
• _file — Nom du fichier. Type : LowCardinality(String).
• _size — Taille du fichier en octets. Type : Nullable(UInt64). Si la taille du fichier est inconnue, la valeur est NULL.
• _time — Date et heure de la dernière modification du fichier. Type : Nullable(DateTime). Si cette date et heure sont inconnues, la valeur est NULL.
• _etag — ETag du fichier. Type : LowCardinality(String). Si l’ETag est inconnu, la valeur est NULL.

Types de données pris en charge dans les clés de partition Paimon :

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