Premiers pas avec les lacs de données

Le moyen le plus rapide pour démarrer — en particulier pour des requêtes ad hoc ou lorsque vous n’utilisez pas de catalogue — consiste à utiliser la table function icebergS3(). Pointez-la vers une table Iceberg dans S3 et lancez immédiatement une query, sans aucune configuration préalable.

Inspectez le schéma :

DESCRIBE icebergS3('https://datasets-documentation.s3.amazonaws.com/lake_formats/iceberg/')

Exécuter une requête :

SELECT
    url,
    count() AS cnt
FROM icebergS3('https://datasets-documentation.s3.amazonaws.com/lake_formats/iceberg/')
GROUP BY url
ORDER BY cnt DESC
LIMIT 5

ClickHouse lit directement les métadonnées Iceberg depuis S3 et détermine automatiquement le schéma. La même approche fonctionne pour deltaLake(), hudi() et paimon().

Pour en savoir plus : Interroger directement les formats de table ouverts couvre les quatre formats, les variantes de cluster pour les lectures distribuées et les options de backend de stockage (S3, Azure, HDFS, local).

Si vous n’utilisez pas de catalogue mais comptez interroger plusieurs fois le même chemin, créez une table à l’aide du moteur de table Iceberg afin de ne pas avoir à spécifier le chemin à chaque fois. Les données restent dans S3 — aucune donnée n’est dupliquée :

CREATE TABLE hits_iceberg
    ENGINE = IcebergS3('https://datasets-documentation.s3.amazonaws.com/lake_formats/iceberg/')

Interrogez-la maintenant comme n’importe quelle table ClickHouse :

SELECT
    url,
    count() AS cnt
FROM hits_iceberg
GROUP BY url
ORDER BY cnt DESC
LIMIT 5

Le moteur de table prend en charge la mise en cache des données, la mise en cache des métadonnées, l’évolution du schéma et le time travel. Consultez le guide Interroger directement pour en savoir plus sur les fonctionnalités du moteur de table, ainsi que la matrice de compatibilité pour une comparaison complète des fonctionnalités.

Si votre organisation utilise un catalogue de données, c’est l’approche d’intégration que nous recommandons. Les catalogues centralisent les métadonnées des tables et leur découverte — au lieu de gérer une définition de table pour chaque chemin de stockage, connectez-vous une seule fois avec le moteur de base de données DataLakeCatalog. Chaque table du catalogue apparaît comme une table ClickHouse, y compris celles ajoutées en amont après la création de la connexion.

Voici un exemple de connexion à AWS Glue :

CREATE DATABASE my_lake
ENGINE = DataLakeCatalog
SETTINGS
    catalog_type = 'glue',
    region = '<your-region>',
    aws_access_key_id = '<your-access-key>',
    aws_secret_access_key = '<your-secret-key>'

Chaque type de catalogue nécessite ses propres paramètres de connexion — consultez les guides sur les catalogues pour la liste complète des catalogues pris en charge et de leurs options de configuration.

Parcourez les tables et exécutez des requêtes :

SHOW TABLES FROM my_lake;

SELECT count(*) FROM my_lake.`<database>.<table>`

Pour en savoir plus : Se connecter à un catalogue de données explique pas à pas une configuration complète d’Unity Catalog avec des exemples Delta et Iceberg.

Quelle que soit la méthode utilisée ci-dessus — fonction de table, moteur de table ou DataLakeCatalog — le même ClickHouse SQL fonctionne dans tous les cas. En production avec un catalogue, interrogez via la base de données DataLakeCatalog ; les autres exemples restent utiles pour des tests rapides et un accès par chemin :

-- Table function
SELECT url, count() AS cnt
FROM icebergS3('https://datasets-documentation.s3.amazonaws.com/lake_formats/iceberg/')
GROUP BY url ORDER BY cnt DESC LIMIT 5

-- Table engine
SELECT url, count() AS cnt
FROM hits_iceberg
GROUP BY url ORDER BY cnt DESC LIMIT 5

-- Catalog
SELECT url, count() AS cnt
FROM my_lake.`<database>.<table>`
GROUP BY url ORDER BY cnt DESC LIMIT 5

La syntaxe de la requête est identique — seule la clause FROM change. Toutes les fonctions, jointures et agrégations de ClickHouse SQL fonctionnent de la même façon, quelle que soit la source de données.

Interroger Iceberg directement est pratique, mais les performances restent limitées par le débit du réseau et l’organisation des fichiers. Pour les charges de travail analytiques, chargez les données dans une table MergeTree native.

Commencez par exécuter une requête filtrée sur la table Iceberg afin d’établir une référence :

SELECT
    url,
    count() AS cnt
FROM hits_iceberg
WHERE counterid = 38
GROUP BY url
ORDER BY cnt DESC
LIMIT 5

Cette requête parcourt l’intégralité du jeu de données dans S3, car Iceberg ne tient pas compte du filtre counterid — prévoyez plusieurs secondes d’exécution.

Créez maintenant une table MergeTree et chargez les données :

CREATE TABLE hits_clickhouse
(
    url String,
    eventtime DateTime,
    counterid UInt32
)
ENGINE = MergeTree()
ORDER BY (counterid, eventtime);

INSERT INTO hits_clickhouse
SELECT url, eventtime, counterid
FROM hits_iceberg

Réexécutez la même requête sur la table MergeTree :

SELECT
    url,
    count() AS cnt
FROM hits_clickhouse
WHERE counterid = 38
GROUP BY url
ORDER BY cnt DESC
LIMIT 5

Comme counterid est la première colonne de la clé ORDER BY, l’index primaire sparse de ClickHouse saute directement aux granules pertinentes et ne lit que les lignes correspondant à counterid = 38, au lieu de parcourir l’ensemble des 100 millions de lignes. Le résultat est un gain de vitesse spectaculaire.

Le guide accélérer l’analytique va plus loin avec les types LowCardinality, les index de texte intégral et des clés de tri optimisées, en montrant une amélioration d’environ 40x sur un jeu de données de 283 millions de lignes.

Pour en savoir plus : Accélérer l’analytique avec MergeTree couvre l’optimisation du schéma, l’indexation en texte intégral et une comparaison complète des performances avant/après.

ClickHouse peut également écrire des données dans des tables Iceberg, ce qui permet des workflows ETL inversés — publier des résultats agrégés ou des sous-ensembles pour qu’ils soient exploités par d’autres outils (Spark, Trino, DuckDB, etc.).

Créez une table Iceberg de sortie :

CREATE TABLE output_iceberg
(
    url String,
    cnt UInt64
)
ENGINE = IcebergS3('https://your-bucket.s3.amazonaws.com/output/', 'access_key', 'secret_key')

Écrire les résultats agrégés :

SET allow_experimental_insert_into_iceberg = 1;

INSERT INTO output_iceberg
SELECT
    url,
    count() AS cnt
FROM hits_clickhouse
GROUP BY url
ORDER BY cnt DESC

La table Iceberg obtenue peut être lue par tout moteur compatible avec Iceberg.

Pour en savoir plus : Écrire des données dans des formats de tables ouverts explique comment écrire des données brutes et des résultats agrégés à partir du jeu de données UK Price Paid, notamment les considérations de schéma lors de la correspondance entre les types ClickHouse et Iceberg.