Bonnes pratiques pour les lacs de données

Recommandations pour la production lors de l’exécution de requêtes sur des formats de table ouverts dans ClickHouse : schémas d’intégration, optimisation des performances des requêtes, configuration du catalogue et Débogage.

Le guide de prise en main vous accompagne dans vos premières requêtes sur Apache Iceberg, Delta Lake, Apache Hudi et Apache Paimon. Une fois la configuration terminée, utilisez cette page pour choisir le bon modèle d’accès, optimiser les performances des requêtes et déboguer les requêtes sur le lac de données en production.

​

Choisissez une méthode d’accès

Méthode d’accès	Quand l’utiliser	Exemples
Fonction de table	Requêtes ad hoc sur un chemin connu	icebergS3(), deltaLake(), hudi(), paimon()
Moteur de table	Requêtes répétées sur le même chemin, sans catalogue	IcebergS3, DeltaLake, Hudi
Moteur de base de données DataLakeCatalog	Workloads de production avec un catalogue ; requêtes fédérées sur de nombreuses tables	AWS Glue, Unity Catalog, REST catalogue

​

Fonctions de table

Indiquez le chemin de stockage et les identifiants en intégré lorsque vous connaissez l’emplacement et n’avez pas besoin d’une définition de table persistante.

SELECT count()
FROM icebergS3('https://my-bucket.s3.amazonaws.com/warehouse/my_table/')
WHERE event_date >= today() - 7

Utilisez la variante S3 pour AWS S3 et GCS. Azure et le système de fichiers local disposent de variantes dédiées (icebergAzure, icebergLocal et leurs équivalents pour les autres formats). Consultez Interroger directement pour la liste complète.

Paimon propose des fonctions de table et des moteurs de table expérimentaux.

​

Moteurs de table

Créez une table avec un moteur de table lorsque vous devez interroger plusieurs fois le même chemin. ClickHouse stocke le chemin et les informations d’authentification dans les métadonnées de la table, ce qui vous permet d’interroger un simple nom de table au lieu de reconstruire l’appel de fonction à chaque fois.

CREATE TABLE events
    ENGINE = IcebergS3('https://my-bucket.s3.amazonaws.com/warehouse/events/')

SELECT count() FROM events WHERE event_date = today()

Les moteurs de table prennent en charge les mêmes fonctionnalités de lecture que les fonctions de table, notamment la mise en cache des données et la mise en cache des métadonnées. Les données ne sont jamais dupliquées dans ClickHouse. Un moteur de table est utile lorsque vous partagez l’accès à la même table avec une équipe ou exécutez des tâches planifiées sur celle-ci.

​

Moteur de base de données DataLakeCatalog

Connectez ClickHouse une seule fois lorsque des tables sont enregistrées dans un catalogue de données. Chaque table du catalogue apparaît automatiquement comme une table ClickHouse, y compris les tables ajoutées ultérieurement dans le catalogue source après la création de la connexion.

CREATE DATABASE my_lake
ENGINE = DataLakeCatalog
SETTINGS
    catalog_type = 'glue',
    region = 'us-east-1',
    aws_access_key_id = '<key>',
    aws_secret_access_key = '<secret>'

SELECT count() FROM my_lake.`analytics.events`

Cette approche passe mieux à l’échelle que la création de définitions de table individuelles lorsque vous gérez de nombreuses tables ou plusieurs catalogues. Consultez Se connecter aux catalogues et les guides des catalogues.

Accents graves pour les noms de table en plusieurs parties

Les catalogues utilisent souvent la convention de nommage database.table. Entourez d’accents graves le nom qualifié par la base de données, comme dans l’exemple ci-dessus.

​

Paramètres requis

De nombreuses intégrations nécessitent l’activation d’un flag avant la première utilisation. Vérifiez la version de votre service si CREATE DATABASE échoue avec une erreur d’autorisation.

Pour les connexions aux catalogues, chaque type de catalogue possède son propre flag. Consultez Se connecter aux catalogues pour une vue d’ensemble, et la référence DataLakeCatalog pour le détail des paramètres. La configuration de chaque catalogue se trouve dans les guides des catalogues.

Pour les écritures, Iceberg nécessite allow_insert_into_iceberg (25.7+, bêta à partir de 26.2). Consultez Écrire dans les lacs de données. Delta Lake nécessite allow_delta_lake_writes (25.9+). La Matrice de prise en charge indique quels flags s’appliquent à chaque format et à chaque opération.

​

Améliorer les performances des requêtes

Les numéros de version indiqués sur cette page correspondent aux versions publiées de ClickHouse (Cloud et auto-géré). Vérifiez la version de votre service avant d’activer un paramètre ou une fonctionnalité.

Les performances des requêtes sur Lake dépendent de la quantité de métadonnées et du nombre de fichiers Parquet que ClickHouse lit depuis le stockage objet. Comme pour toute table ClickHouse, les performances des requêtes s’améliorent en filtrant sur les colonnes de partition et en sélectionnant un plus petit nombre de colonnes.

​

Bonnes pratiques de requête

Filtrez sur les colonnes de partition dans WHERE. Iceberg et Delta Lake stockent des métadonnées de partition qui permettent à ClickHouse d’ignorer les fichiers non pertinents lors de la planification de la requête. Si votre filtre cible une colonne qui ne figure pas dans la spécification de partitionnement, ClickHouse parcourt chaque fichier correspondant.

Pour les tables Iceberg avec partitionnement masqué, filtrez sur la colonne source dans le schéma de la table, et non sur une colonne de partition distincte ou sur le nom d’un champ transformé. Si la table est partitionnée par day(event_time), ajoutez un prédicat sur event_time. ClickHouse déduit l’élagage des partitions de ce filtre en s’appuyant sur la spécification de partitionnement d’Iceberg. Voir Élagage des partitions et la spécification d’Iceberg.

SELECT count()
FROM my_lake.`logs.application`
WHERE event_time >= '2026-03-01'
  AND event_time < '2026-03-02'

Listez uniquement les colonnes dont vous avez besoin au lieu de SELECT *. ClickHouse lit Parquet colonne par colonne depuis le stockage objet, donc des SELECT plus ciblés réduisent le volume d’octets transférés et décompressés.

Placez les filtres sélectifs dans WHERE. À partir de ClickHouse 26.2, PREWHERE est également pris en charge pour Iceberg et les lectures d’autres tables de data lake, car il filtre au niveau de la couche Parquet avant de lire les colonnes restantes. L’élagage des partitions dépend toujours du filtrage des colonnes sources de partition, et pas du seul PREWHERE.

Les tables Iceberg avec beaucoup de suppressions par position ou par égalité appliquent un filtrage merge-on-read lors du parcours. Attendez-vous à davantage de travail par fichier que ne le laisserait supposer le seul élagage des manifestes.

Dans les déploiements multinœuds, utilisez les fonctions de table cluster pour répartir les lectures de fichiers entre les répliques.

​

Lectures parallèles sur des clusters multinœuds

Sur ClickHouse Cloud et les services multinœuds autogérés, les variantes de cluster des fonctions de table pour les data lakes répartissent la lecture des fichiers Parquet entre les répliques. Le nœud initiateur répartit les fichiers entre les workers en parallèle. Utilisez les variantes de cluster pour les lectures par lot et les chargements planifiés sur de grandes tables. Sur les déploiements à nœud unique, la fonction de table standard suffit.

Indiquez le nom de votre cluster comme premier argument ('default' sur ClickHouse Cloud). Des variantes de cluster existent pour tous les formats pris en charge :

Format	Fonctions cluster
Iceberg	icebergS3Cluster(), icebergAzureCluster()
Delta Lake	deltaLakeCluster(), deltaLakeAzureCluster()
Hudi	hudiCluster()
Paimon	paimonS3Cluster()

Vous pouvez combiner les lectures sur cluster avec d’autres paramètres de performances.

​

Fonctions cluster et On-Demand Compute

Les variantes de cluster telles que icebergS3Cluster et deltaLakeCluster répartissent la lecture des fichiers entre les nodes de votre cluster existant. La fonction de cluster en elle-même n’ajoute pas de compute. On-Demand Compute est une capability de ClickHouse Cloud qui affecte temporairement des workers supplémentaires, issus d’un pool managé, aux requêtes éligibles, via votre service et votre endpoint existants.

Pendant la private preview, On-Demand Compute ne prend en charge que les requêtes SELECT éligibles portant sur des données Apache Iceberg et Delta Lake prises en charge. Consultez la documentation On-Demand Compute pour connaître les conditions d’éligibilité et les limitations.

​

Limiter les lectures par lot aux instantanés

Pour les chargements par lot répétés à partir de tables de data lake, limitez chaque exécution à une plage d’instantanés au lieu de relire la table complète. Sans bornes, ClickHouse peut parcourir toutes les versions et tous les fichiers à chaque exécution, ce qui augmente les lectures sur le stockage objet et le temps de requête.

Stockez l’identifiant de l’instantané de votre dernier chargement réussi et utilisez-le comme borne inférieure lors de l’exécution suivante.

• Pour Iceberg, lisez une vue à un instant donné avec iceberg_snapshot_id ou iceberg_timestamp_ms (25.4+). Pour les tables en ajout uniquement, combinez les paramètres d’instantané avec des filtres de partition dans WHERE. Utilisez system.iceberg_history (25.6+) pour retrouver les ID d’instantané entre les exécutions.
• Pour Delta Lake, lisez les changements entre deux versions avec delta_lake_snapshot_start_version et delta_lake_snapshot_end_version (25.12+). Lisez un instantané unique avec delta_lake_snapshot_version (25.8+). Consultez Delta change data feed pour un exemple de CDF.

​

Mettre les fichiers Parquet en cache localement

Les deux formats prennent en charge enable_filesystem_cache pour conserver sur le disque local les fichiers Parquet les plus sollicités entre les requêtes. Dans les déploiements autogérés, configurez un filesystem cache disk dans la configuration du serveur afin que ce paramètre dispose d’un espace de stockage où écrire. ClickHouse Cloud gère automatiquement la mise en cache. Définissez enable_filesystem_cache = 0 lors des tests de performance afin que les accès au cache ne masquent pas les changements entre les exécutions.

​

Apache Iceberg

La plupart des optimisations de lecture d’Apache Iceberg sont activées par défaut. Les paramètres ci-dessous contrôlent l’élagage des partitions, la mise en cache des métadonnées et les allers-retours vers le catalogue.

​

Paramètres de lecture

Paramètre	Depuis	Par défaut	Remarques
use_iceberg_partition_pruning	25.1	1 à partir de 25.6	Ignore les fichiers de données à l’aide des métadonnées de partition présentes dans les manifestes
use_iceberg_metadata_files_cache	25.4	1	Met en cache en mémoire les listes de manifestes et les métadonnées JSON
iceberg_metadata_staleness_ms	26.3	0	Paramètre de requête. Utilise les métadonnées en cache lorsqu’elles sont plus récentes que cet intervalle, au lieu d’interroger le catalogue à chaque requête
iceberg_use_version_hint	25.6	—	Lit version-hint.text pour accélérer la résolution des métadonnées lors d’un accès direct par chemin

​

Réduire la latence du catalogue

Les tables Iceberg reliées à un catalogue nécessitent une récupération des métadonnées à chaque requête, sauf si vous mettez ces métadonnées en cache. Combinez deux paramètres (26.4+) :

1. Définissez iceberg_metadata_async_prefetch_period_ms lors de la création de la table pour précharger les métadonnées en arrière-plan.
2. Définissez iceberg_metadata_staleness_ms (26.3+) dans les requêtes pour accepter des métadonnées légèrement périmées et ainsi éviter l’aller-retour vers le catalogue.

CREATE TABLE events
    ENGINE = IcebergS3('https://my-bucket.s3.amazonaws.com/warehouse/events/')
SETTINGS iceberg_metadata_async_prefetch_period_ms = 60000;

SELECT count()
FROM events
SETTINGS iceberg_metadata_staleness_ms = 60000;

Une valeur de staleness de 0 récupère toujours les métadonnées les plus récentes. Augmentez cette fenêtre pour les charges de travail à forte intensité de lecture, où les tables changent rarement.

Lorsque ClickHouse sélectionne le mauvais fichier de métadonnées (plusieurs fichiers .metadata.json dans le chemin de la table), forcez la résolution avec iceberg_metadata_file_path (25.4+) ou iceberg_metadata_table_uuid lors de la création de la table. Voir Résolution du fichier de métadonnées.

​

Voyage temporel

Lisez un instantané historique avec iceberg_timestamp_ms ou iceberg_snapshot_id (tous deux disponibles à partir de la version 25.4). Ne définissez pas les deux dans la même requête. Consultez la lignée des instantanés dans system.iceberg_history (25.6+) avant de choisir un ID. Pour des chargements par lot répétés, voir Limiter les lectures par lot aux instantanés.

SELECT count()
FROM my_iceberg_table
SETTINGS iceberg_timestamp_ms = 1714636800000

​

Écritures vers Iceberg

Au-delà de allow_insert_into_iceberg (25.7+, bêta à partir de 26.2), contrôlez la taille des fichiers de sortie et le nombre de partitions à l’insertion :

Paramètre	Depuis	Objectif
iceberg_insert_max_rows_in_data_file	25.9	Nombre maximal de lignes par fichier de données de sortie
iceberg_insert_max_bytes_in_data_file	25.9	Taille maximale en octets par fichier de données de sortie
iceberg_insert_max_partitions	25.12	Nombre maximal de partitions écrites lors d’une seule insertion

Voir Écriture vers des lacs de données et la référence du moteur Iceberg.

​

Delta Lake

À partir de la version 25.6, ClickHouse lit Delta Lake sur S3 et GCS via le kernel Rust de Delta Lake. Le paramètre se nomme allow_delta_kernel_rs à partir de la version 26.8, et allow_experimental_delta_kernel_rs dans les versions 25.5 à 26.7. Sur Azure Blob Storage, utilisez deltaLakeAzure() avec le lecteur legacy, car le kernel y est désactivé. Sans le kernel, l’élagage des partitions, le flux de données des modifications et la lecture de versions d’instantané ne sont pas disponibles.

​

Delta Kernel

Le paramètre Delta Kernel doit être activé pour l’élagage des partitions, le flux de données des modifications et la lecture de versions d’instantané. Il est activé par défaut sur S3 et GCS à partir de la version 25.5. Lorsque vous l’activez explicitement, utilisez le nom correspondant à votre version de ClickHouse.

Pour la version 26.8 et ultérieures :

SET allow_delta_kernel_rs = 1;

Pour les versions 25.5 à 26.7 :

SET allow_experimental_delta_kernel_rs = 1;

​

Paramètres de lecture

Setting	Since	Default	Notes
delta_lake_enable_engine_predicate	25.8	1	Transmet les filtres au kernel pour l’élagage des partitions. Nécessite Delta Kernel
delta_lake_reload_schema_for_consistency	26.3	0	Recharge le schéma avant chaque requête lorsque des writers concurrents font évoluer le schéma
delta_lake_snapshot_start_version / delta_lake_snapshot_end_version	25.12	-1	Lit les changements CDF entre deux versions d’instantané. Nécessite que CDF soit activé en amont
delta_lake_snapshot_version	25.8	-1	Lit un instantané historique unique. Définissez -1 pour le plus récent (0 est valide)

Les tables avec des deletion vectors (26.2+) appliquent un filtrage au niveau des lignes pendant la lecture. ClickHouse gère cela automatiquement, mais les parcours sur les tables contenant beaucoup de DV demandent plus de travail par fichier.

​

Flux de données des modifications Delta

Pour lire uniquement les lignes modifiées entre deux instantanés Delta, définissez delta_lake_snapshot_start_version et delta_lake_snapshot_end_version (25.12+). La table doit avoir le flux de données des modifications activé dans la source amont (delta.enableChangeDataFeed). Définissez les versions de début et de fin dans les paramètres de requête. Définir uniquement la version de fin provoque une erreur.

SELECT *
FROM deltaLake('s3://my-bucket/warehouse/ga4_events/')
SETTINGS
    delta_lake_snapshot_start_version = 42,
    delta_lake_snapshot_end_version = 47

Conservez la version de fin après chaque chargement réussi et réutilisez-la comme version de début lors de l’exécution suivante. Le résultat comprend des colonnes CDF (_change_type, _commit_version, _commit_timestamp). Traitez-les avant de charger les données dans votre table cible. Pour le modèle général des instantanés, voir Limiter les lectures en lot aux instantanés.

​

Écritures Delta Lake

En plus de allow_delta_lake_writes (25.9+), contrôlez la taille des fichiers de sortie à l’insertion :

Paramètre	Depuis	Objectif
delta_lake_insert_max_rows_in_data_file	25.9	Nombre maximal de lignes par fichier de données de sortie
delta_lake_insert_max_bytes_in_data_file	25.9	Taille maximale en octets par fichier de données de sortie

SET allow_delta_lake_writes = 1;

INSERT INTO my_delta_table
SETTINGS
    delta_lake_insert_max_rows_in_data_file = 1000000,
    delta_lake_insert_max_bytes_in_data_file = 134217728
SELECT * FROM source_table

Les opérations d’écriture nécessitent Delta Kernel sur S3 ou GCS. Consultez la référence du moteur DeltaLake pour des exemples.

​

Débogage des requêtes sur le data lake

Les requêtes sur le data lake qui s’exécutent lentement ou renvoient des résultats inattendus sont généralement liées aux lectures de métadonnées, à l’élagage des partitions ou à la connectivité du catalogue. Commencez par les vérifications ci-dessous, puis utilisez si nécessaire les journaux de métadonnées propres au format concerné.

​

Vérifier la connectivité du catalogue

CREATE DATABASE avec DataLakeCatalog ne valide pas les identifiants. Une base de données peut exister même si la connexion au catalogue est rompue. À partir de ClickHouse 26.4, effectuez une vérification d’état légère :

CHECK DATABASE my_lake;

Dans les versions antérieures, vérifiez la connectivité avec SHOW TABLES FROM my_lake et examinez le message d’erreur. Utilisez SHOW CREATE TABLE avec un nom de table entre accents graves pour vérifier le chemin de stockage résolu et le type de moteur :

SHOW CREATE TABLE my_lake.`db.table`;

Si les tables du catalogue n’apparaissent pas dans system.tables, activez show_remote_databases_in_system_tables (25.8+). Par défaut, les tables du catalogue sont masquées dans les informations d’introspection du système. Dans les versions antérieures à 26.6, utilisez son ancien nom, show_data_lake_catalogs_in_system_tables.

​

Voir quels fichiers sont lus

Iceberg et Delta Lake exposent des colonnes virtuelles (_path, _file, _size, _time, _etag) lors de chaque lecture. Regroupez par _path pour voir si l’élagage des partitions fonctionne ou si une requête lit plus de fichiers que prévu. Pour les tables Iceberg avec partitionnement masqué, filtrez sur la colonne source (par exemple event_time), et non sur une colonne de partition distincte :

SELECT _path, count() AS rows
FROM my_lake.`logs.application`
WHERE event_time >= '2026-03-01'
  AND event_time < '2026-03-02'
GROUP BY _path
ORDER BY rows DESC;

​

Vérifier le volume du parcours des données

Comparez read_rows et read_bytes dans system.query_log avant et après l’ajout de filtres ou le réglage des paramètres. Des ProfileEvents comme ReadBufferFromS3Bytes et CachedReadBufferReadFromCacheBytes indiquent quelle quantité de données provient du stockage objet par rapport au cache local. Consultez Diagnostiquer les requêtes lentes pour une présentation complète de query_log et d’EXPLAIN.

Désactivez enable_filesystem_cache lors du benchmarking afin que les accès au cache ne masquent pas les changements entre les exécutions.

​

Journaux de métadonnées

ClickHouse expose trois tables système pour le débogage au niveau des métadonnées. Activez la journalisation uniquement au moment de la requête. Elles ne sont pas conçues pour un Monitoring continu.

Table système	Format	Depuis	Activer avec	Permet de
system.iceberg_metadata_log	Iceberg	25.9	iceberg_metadata_log_level sur la requête	Suivre les fichiers de métadonnées lus et les décisions d’élagage des partitions
system.iceberg_history	Iceberg	25.6	Alimentée automatiquement pour les tables Iceberg dans ClickHouse	Examiner la lignée des instantanés avant les requêtes de voyage temporel
system.delta_lake_metadata_log	Delta Lake	25.10	delta_lake_log_metadata = 1 sur la requête	Suivre les fichiers de métadonnées Delta et la résolution des instantanés

Exécutez une requête avec la journalisation activée, forcez l’écriture dans le journal, puis examinez les entrées pour ce query_id :

SELECT count() FROM my_iceberg_table
SETTINGS iceberg_metadata_log_level = 'manifest_file_entry';

SYSTEM FLUSH LOGS iceberg_metadata_log;

SELECT content_type, file_path, pruning_status
FROM system.iceberg_metadata_log
WHERE query_id = '<previous_query_id>';

Sur ClickHouse Cloud, les données de logs sont locales à chaque nœud. Utilisez clusterAllReplicas pour obtenir une vue d’ensemble complète sur l’ensemble des répliques.

Les niveaux de logs Iceberg les plus verbeux désactivent la mise en cache des métadonnées pour les listes de manifeste et les fichiers, ce qui ralentit les requêtes ultérieures sur la même table. N’utilisez une verbosité élevée que pendant vos investigations. En cas de problème de prédicat avec Delta Lake, activez delta_lake_throw_on_engine_predicate_error (25.8+) pour échouer immédiatement lorsque le kernel ne peut pas pousser un filtre jusqu’à la source de données.

Consultez les pages de référence iceberg_metadata_log et delta_lake_metadata_log pour plus de détails sur les colonnes et les options de verbosité.

​

Étapes suivantes

• Bien démarrer — Guide de bout en bout, de l’interrogation directe à la réécriture des données
• Interroger directement — Fonctions de table, moteurs et variantes de cluster pour les quatre formats
• Se connecter aux catalogues — Configuration de DataLakeCatalog avec Unity Catalog
• Écrire dans les lacs de données — Réécrire les données dans Iceberg et Delta Lake
• Matrice de prise en charge — Comparaison des fonctionnalités entre les formats, les catalogues et les systèmes de stockage sous-jacents