Skip to main content
L’intégration au catalogue SeaweedFS fonctionne uniquement avec les tables Iceberg.
ClickHouse prend en charge l’intégration à plusieurs catalogues (Unity, Glue, REST, Polaris, etc.). Ce guide explique comment interroger vos données à l’aide de ClickHouse et du catalogue SeaweedFS. SeaweedFS est un stockage distribué open source de fichiers et d’objets doté d’une passerelle compatible S3. Ses S3 Table Buckets fournissent les deux composants d’un déploiement Iceberg : le catalogue Iceberg REST intégré sert les métadonnées des tables, tandis que le bucket de tables stocke les données sous forme de fichiers Parquet via le même endpoint S3 :
  • Service unique - les métadonnées du catalogue et les données Parquet sont fournies par un seul processus, sans base de données de métadonnées distincte
  • Conformité de l’API REST à la spécification du catalogue REST Iceberg
  • Maintenance côté serveur - compaction automatique des fichiers Parquet et expiration des snapshots, sans service de maintenance externe
Cette fonctionnalité étant expérimentale, vous devez l’activer à l’aide de : SET allow_experimental_database_iceberg = 1;

Configuration de développement local

Pour le développement et les tests en local, vous pouvez exécuter SeaweedFS et ClickHouse avec Docker Compose. Cette approche est idéale pour l’apprentissage, le prototypage et les environnements de développement.

Prérequis

  1. Docker et Docker Compose : assurez-vous que Docker est installé et en cours d’exécution
  2. Versions : SeaweedFS 4.42 ou version ultérieure ; ClickHouse 26.8 ou version ultérieure (les versions remontant à 25.8 peuvent lire et insérer, mais la création de tables via le catalogue nécessite la version 26.8)
  3. Python avec PyIceberg (facultatif) : utilisé ci-dessous pour générer des données d’exemple

Configuration du catalogue SeaweedFS local

Étape 1 : Créez un dossier dans lequel exécuter l’exemple, puis créez un fichier s3config.json contenant les identifiants de la passerelle S3 et du catalogue :
Étape 2 : Créez un fichier docker-compose.yml avec la configuration suivante :
La commande mini démarre l’ensemble de la stack SeaweedFS dans un seul conteneur. L’option -tableBucket=analytics crée à l’avance un bucket S3 Tables nommé analytics, qui sert de warehouse Iceberg. Étape 3 : Exécutez la commande suivante pour démarrer les services :

Ajout de données d’exemple

Le catalogue est initialement vide. Créez une table et ajoutez-y quelques lignes avec PyIceberg (pip install pyiceberg pyarrow) :

Connexion au catalogue SeaweedFS local

Connectez-vous à votre conteneur ClickHouse :
Créez ensuite la connexion à la base de données avec le catalogue SeaweedFS :
Les arguments de l’engine contiennent les identifiants S3 que ClickHouse utilise pour lire les données de la table, tandis que catalog_credential et oauth_server_uri permettent de s’authentifier auprès du catalogue via le flux client credentials OAuth2. SeaweedFS accepte la même clé d’accès et la même clé secrète pour les deux.

Interroger les tables du catalogue SeaweedFS à l’aide de ClickHouse

Maintenant que la connexion est établie, vous pouvez commencer à effectuer des requêtes via le catalogue SeaweedFS. Par exemple :
Backticks obligatoiresLes backticks sont obligatoires, car ClickHouse ne prend pas en charge plusieurs espaces de noms.
Pour interroger une table :

Création de tables et écriture de données depuis ClickHouse

Vous pouvez également créer des tables dans le catalogue SeaweedFS et y écrire directement depuis ClickHouse :
La clause du moteur IcebergS3 indique le chemin de stockage de la nouvelle table, et write_full_path_in_iceberg_metadata permet à ClickHouse d’enregistrer l’emplacement complet de la table dans le catalogue.
La création de tables via un catalogue nécessite ClickHouse 26.8 ou une version ultérieure. Les versions 26.4 à 26.7 écrivent les fichiers de la table avant d’enregistrer l’espace de noms, ce que SeaweedFS rejette à moins que cet espace de noms n’existe déjà dans le catalogue ; les versions antérieures à 26.4 semblent aboutir, mais les fichiers de la table sont écrits dans le stockage d’objets sans être enregistrés dans le catalogue.
Lorsque ClickHouse valide une insertion, le catalogue SeaweedFS corrige les métadonnées que le writer expérimental ne génère pas encore : il renseigne les ID de champ manquants dans les manifestes, réécrit les chemins de fichiers relatifs au bucket en emplacements absolus et attribue à la table un mappage de noms par défaut. Les lecteurs stricts tels que PyIceberg et Spark peuvent alors lire les lignes écrites par ClickHouse. Cela nécessite SeaweedFS 4.42 ou une version ultérieure.

Chargement des données de votre lac de données dans ClickHouse

Si vous devez charger des données du catalogue SeaweedFS dans ClickHouse, commencez par créer une table ClickHouse locale :
Chargez ensuite les données depuis votre table de catalogue SeaweedFS à l’aide d’un INSERT INTO SELECT :
Dernière modification le 16 août 2026