Bonnes pratiques pour les lacs de données

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.

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.

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.

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.

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 Connexion 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+, Beta à partir de 26.2). Consultez Écriture dans les lacs de données. Delta Lake nécessite allow_delta_lake_writes (25.9+). La matrice de compatibilité indique quels flags s’appliquent à chaque format et à chaque opération.

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.

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.

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 :

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

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.

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.

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.

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.

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

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 :

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

À 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.

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;

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.

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.

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

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.

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é.

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.

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;

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.

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.

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é.

• 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