ClickHouse - Interroger des fichiers stockés dans OVHcloud Object Storage

Voir en Markdown

Découvrez comment lire, écrire et joindre des fichiers Parquet ou CSV stockés dans OVHcloud Object Storage depuis ClickHouse, sans exposer vos identifiants S3

Objectif

ClickHouse peut interroger des fichiers stockés dans un bucket compatible S3¹ sans les charger au préalable : vous pouvez les lire, y écrire le résultat d'une requête, les joindre à vos tables ou les charger dans une table. Vos données restent dans votre propre bucket OVHcloud Object Storage.

Ce guide explique comment interroger des fichiers stockés dans OVHcloud Object Storage depuis un cluster Public Cloud Analytics avec ClickHouse, et comment donner accès à ces fichiers à d'autres utilisateurs sans partager vos identifiants S3.

Prérequis

Disposer d'un projet Public Cloud dans votre compte OVHcloud.
Disposer d'un cluster ClickHouse en cours d'exécution sur OVHcloud Public Cloud et acceptant les connexions entrantes. Consultez les guides « Comment créer un cluster ClickHouse » et « Comment se connecter à un cluster ClickHouse ».
Disposer du mot de passe de l'utilisateur avnadmin du cluster, ou d'un utilisateur disposant des privilèges décrits dans ce guide.
Disposer d'un bucket OVHcloud Object Storage et d'un utilisateur S3 disposant d'un accès en lecture et en écriture à ce bucket, avec sa clé d'accès et sa clé secrète. Consultez les guides « Object Storage - Premiers pas » et « Object Storage - Gestion des identités et des accès ».

En pratique

Info

Les exemples de ce guide sont des requêtes SQL. Vous pouvez les exécuter avec clickhouse-client ou en HTTPS, comme décrit dans le guide « Comment se connecter à un cluster ClickHouse ».

Étape 1 - Construire l'URL de vos fichiers

ClickHouse désigne un fichier par l'URL du point de terminaison du bucket, suivie du nom du bucket et du chemin du fichier (URL de type path-style) :

https://s3.<region>.io.cloud.ovh.net/<bucket>/<chemin>/<fichier>

<region> est la région de votre bucket en minuscules, par exemple gra ou eu-west-par. Le point de terminaison de chaque région est indiqué dans le guide « Object Storage - Endpoints et géo-disponibilité ».
<bucket> est le nom de votre bucket.
<chemin>/<fichier> est la clé de l'objet, par exemple sales/2026/orders.parquet.

Warning

L'URL doit commencer par https://. Sans ce préfixe, ClickHouse renvoie l'erreur Host is empty in S3 URI.

Étape 2 - Enregistrer vos identifiants S3 dans une named collection

Vous pourriez écrire votre clé d'accès et votre clé secrète dans chaque requête, mais elles apparaîtraient alors dans vos scripts et dans l'historique des requêtes. Enregistrez-les plutôt une fois dans une named collection : ClickHouse les conserve chiffrées et ne les affiche jamais.

Connecté en tant que avnadmin, exécutez :

CREATE NAMED COLLECTION ovh_bucket AS
    url = 'https://s3.<region>.io.cloud.ovh.net/<bucket>/',
    access_key_id = '<cle_acces>',
    secret_access_key = '<cle_secrete>';

Les valeurs sont masquées lorsque vous listez les named collections :

SELECT name, collection FROM system.named_collections;

ovh_bucket   {'access_key_id':'[HIDDEN]','secret_access_key':'[HIDDEN]','url':'[HIDDEN]'}

Dans les étapes suivantes, filename est le chemin du fichier relatif à l'url de la collection.

Tip

Une named collection utilisée par une table ne peut pas être supprimée. Supprimez ou modifiez d'abord la table.

Étape 3 - Lire des fichiers

Lisez un fichier Parquet avec la fonction de table s3 :

SELECT count(), sum(id)
FROM s3(ovh_bucket, filename = 'numbers.parquet', format = 'Parquet');

La structure des fichiers Parquet est détectée automatiquement.

La fonction de table s3 accepte aussi l'URL complète du fichier, la clé d'accès, la clé secrète et le format. Pour les fichiers CSV avec une ligne d'en-tête, utilisez le format CSVWithNames :

SELECT *
FROM s3('https://s3.<region>.io.cloud.ovh.net/<bucket>/exports/customers.csv', '<cle_acces>', '<cle_secrete>', 'CSVWithNames');

Pour lire plusieurs fichiers à la fois, utilisez un caractère générique (*) dans le chemin. La colonne virtuelle _file indique le fichier d'où provient chaque ligne :

SELECT _file, count()
FROM s3('https://s3.<region>.io.cloud.ovh.net/<bucket>/sales/*.parquet', '<cle_acces>', '<cle_secrete>', 'Parquet')
GROUP BY _file;

Étape 4 - Créer une table sur vos fichiers

Pour interroger régulièrement les mêmes fichiers, créez une table avec le moteur S3. Les données restent dans votre bucket et sont lues à chaque requête :

CREATE TABLE numbers_s3 (id UInt64, label String)
ENGINE = S3(ovh_bucket, filename = 'numbers.parquet', format = 'Parquet');

SELECT count() FROM numbers_s3;

Étape 5 - Joindre des fichiers à vos tables, ou les charger

Vous pouvez joindre des fichiers aux tables de votre cluster dans une même requête :

SELECT o.customer_id, sum(o.amount)
FROM orders AS o
INNER JOIN s3(ovh_bucket, filename = 'referential/customers.parquet', format = 'Parquet') AS c
    ON o.customer_id = c.id
GROUP BY o.customer_id;

Pour charger le contenu de fichiers dans une table de votre cluster, utilisez INSERT … SELECT :

INSERT INTO orders_history
SELECT * FROM s3(ovh_bucket, filename = 'archive/orders_2025.parquet', format = 'Parquet');

Étape 6 - Exporter le résultat d'une requête vers votre bucket

Écrivez le résultat d'une requête dans un fichier avec INSERT INTO FUNCTION :

INSERT INTO FUNCTION s3(ovh_bucket, filename = 'exports/orders_2026.parquet', format = 'Parquet')
SELECT * FROM orders WHERE toYear(order_date) = 2026;

Pour remplacer un fichier existant, ajoutez SETTINGS s3_truncate_on_insert = 1 à la fin de la requête.

Étape 7 - Donner accès aux fichiers à d'autres utilisateurs

Connecté en tant que avnadmin, accordez aux autres utilisateurs les droits nécessaires en SQL. Pour un utilisateur qui lit seulement les fichiers via la named collection ovh_bucket, sans connaître les identifiants S3 :

GRANT READ ON S3 TO <utilisateur>;
GRANT NAMED COLLECTION ON ovh_bucket TO <utilisateur>;
GRANT CREATE TEMPORARY TABLE ON *.* TO <utilisateur>;
GRANT SELECT ON <base>.* TO <utilisateur>;

READ ON S3 autorise la lecture depuis S3.
NAMED COLLECTION ON ovh_bucket autorise l'utilisation de la named collection, sans en voir les valeurs.
CREATE TEMPORARY TABLE est nécessaire pour utiliser la fonction de table s3.
SELECT sur la base est nécessaire pour interroger les tables créées avec le moteur S3.

Résolution des problèmes

Erreur	Cause et solution
`HTTP response code: 403 … Please check your AWS credentials and permissions`	La clé d'accès ou la clé secrète est incorrecte, ou l'utilisateur S3 n'a pas accès au bucket. Vérifiez les identifiants de l'utilisateur S3 et ses droits sur le bucket.
`Host is empty in S3 URI`	L'URL ne commence pas par `https://`. Reportez-vous à l'étape 1 ci-dessus.
`Not enough privileges. … necessary to have the grant READ ON S3`	L'utilisateur n'est pas autorisé à lire depuis S3. Reportez-vous à l'étape 7 ci-dessus.
`Not enough privileges. … necessary to have the grant CREATE TEMPORARY TABLE ON .`	L'utilisateur peut utiliser la named collection mais pas la fonction de table `s3`. Accordez-lui `CREATE TEMPORARY TABLE ON .`.
`A named collection … already exists`	Choisissez un autre nom, ou supprimez la collection existante avec `DROP NAMED COLLECTION`.

Aller plus loin

Nous serions ravis de répondre à vos questions et apprécions tout retour que vous pourriez nous faire.

Pour une formation ou une assistance technique sur la mise en œuvre de nos solutions, contactez votre commercial ou consultez la page Professional Services pour obtenir un devis et faire analyser votre projet par nos experts.

Vous êtes sur Discord ? Rejoignez notre chaîne via https://discord.gg/ovhcloud et interagissez directement avec l'équipe qui développe notre service Analytics !

Rejoignez notre communauté d'utilisateurs.

¹ : S3 est une marque déposée appartenant à Amazon Technologies, Inc. Les services OVHcloud ne sont pas sponsorisés, approuvés, ou affiliés de quelque manière que ce soit.

Cette page vous a-t-elle aidé ?