Moteur de table Paimon - ClickHouse Documentation

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.

Créer une table

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

Arguments du moteur

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

Exemple

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

Fonctionnalités

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.

Paramètres

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

Cycle de vie de use_paimon_metadata_files_cacheLa manière dont use_paimon_metadata_files_cache est appliqué dépend de la façon dont la table Paimon est accédée :

Table functions (par ex. SELECT ... FROM paimonS3(...)) : la décision d’utiliser le cache est évaluée pour chaque query, vous pouvez donc passer SETTINGS use_paimon_metadata_files_cache = 1 directement dans le SELECT.
Persistent table engines (PaimonS3, PaimonAzure, PaimonHDFS, PaimonLocal et l’alias Paimon) : la décision d’utiliser le cache est figée une seule fois lorsque les métadonnées de la table sont initialisées et stockées dans des composants persistants immuables ; le chemin de mise à jour des métadonnées ne relit délibérément pas ce paramètre. Par conséquent, passer SETTINGS use_paimon_metadata_files_cache = 1 dans un SELECT sur une table persistante déjà initialisée n’a aucun effet — la décision précédemment figée continue d’être utilisée. Pour la modifier, définissez use_paimon_metadata_files_cache avant l’initialisation des métadonnées de la table, ou utilisez DROP puis recréez la table avec CREATE avec la valeur souhaitée.

La capacité du cache au niveau du server (paimon_metadata_files_cache_size) n’est pas figée : c’est un paramètre de runtime qui peut être modifié via SYSTEM RELOAD CONFIG et prend effet immédiatement, même pour les tables déjà initialisées.

Exemples de lecture incrémentielle

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

Paramètres de requête pour la lecture incrémentale

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;

De Paimon vers MergeTree via une vue matérialisée actualisable

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;

Arrêtez la MV avant de la supprimer pour éviter qu’un rafraîchissement en arrière-plan ne bloque les opérations DDL.

Limites

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.

Alias

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.

Colonnes virtuelles

_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

Type de données Paimon	Type de données 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

Prise en charge des partitions

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

​Créer une table

​Arguments du moteur

​Exemple

​Fonctionnalités

​Paramètres

​Exemples de lecture incrémentielle

​Paramètres de requête pour la lecture incrémentale

​De Paimon vers MergeTree via une vue matérialisée actualisable

​Limites

​Alias

​Colonnes virtuelles

​Types de données pris en charge

​Prise en charge des partitions

Créer une table

Arguments du moteur

Exemple

Fonctionnalités

Paramètres

Exemples de lecture incrémentielle

Paramètres de requête pour la lecture incrémentale

De Paimon vers MergeTree via une vue matérialisée actualisable

Limites

Alias

Colonnes virtuelles

Types de données pris en charge

Prise en charge des partitions