Choisissez une méthode d’accès
Fonctions de table
icebergAzure, icebergLocal et leurs équivalents pour les autres formats). Consultez Interroger directement pour la liste complète.
Paimon propose uniquement des fonctions de table.
Moteurs de table
Moteur de base de données DataLakeCatalog
Backticks pour les noms de table en plusieurs partiesLes catalogues utilisent souvent la convention de nommage
database.table. Entourez de backticks le nom qualifié par la base de données, comme dans l’exemple ci-dessus.Paramètres requis
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.
Améliorer les performances des requêtes
Bonnes pratiques de requête
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 Partition pruning et la spécification d’Iceberg.
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
'default' sur ClickHouse Cloud). Des variantes cluster existent pour tous les formats pris en charge :
Vous pouvez combiner les lectures sur cluster avec d’autres paramètres de performances.
Limiter les lectures par lot aux instantanés
- 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
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
Paramètres de lecture
Réduire la latence du catalogue
- 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.
- 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.
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
Écritures vers Iceberg
Voir Écriture vers des lacs de données et la référence du moteur Iceberg.
Delta Lake
Delta Kernel
Paramètres de lecture
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
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.
_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
Débogage des requêtes sur le data lake
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 :
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 :
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
_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 :
Vérifier le volume de données parcouru
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 l’optimisation des requêtes 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
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 :
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 manifests 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 noyau 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
- Prise en main — Guide complet, de l’interrogation directe à la réécriture des données
- Interroger directement — Fonctions de table, moteurs et variantes de cluster pour les quatre formats
- Connexion aux catalogues — Configuration de
DataLakeCatalogavec Unity Catalog - Écrire dans des lacs de données — Réécrire les données dans Iceberg et Delta Lake
- Matrice de compatibilité — Comparaison des fonctionnalités entre formats, catalogues et backends de stockage