Passer au contenu principal

​
Prérequis

Pour suivre les exemples de cet article, vous aurez besoin de :
  • disposer d’une instance du serveur ClickHouse en cours d’exécution
  • avoir curl installé. Sur Ubuntu ou Debian, exécutez sudo apt install curl ou consultez cette documentation pour les instructions d’installation.

​
Vue d’ensemble

L’interface HTTP vous permet d’utiliser ClickHouse sur n’importe quelle plateforme, depuis n’importe quel langage de programmation, sous la forme d’une API REST. L’interface HTTP est plus limitée que l’interface native, mais elle offre une meilleure prise en charge des langages. Par défaut, clickhouse-server écoute sur les ports suivants :
  • le port 8123 pour HTTP
  • le port 8443 pour HTTPS, si celui-ci est activé
Si vous effectuez une requête GET / sans aucun paramètre, un code de réponse 200 est renvoyé avec la chaîne “Ok.” :
“Ok.” est la valeur par défaut définie dans http_server_default_response et peut être modifiée si nécessaire. Voir aussi : Mises en garde concernant les codes de réponse HTTP.

​
Interface utilisateur web

ClickHouse comprend une interface utilisateur web, accessible à l’adresse suivante :
L’interface web prend en charge l’affichage de la progression pendant l’exécution d’une requête, l’annulation de requête et le streaming des résultats. Elle dispose d’une fonctionnalité cachée pour afficher des graphiques et des graphes de pipelines de requête. Après l’exécution réussie d’une requête, un bouton de téléchargement apparaît et vous permet de télécharger les résultats de la requête dans différents formats, notamment CSV, TSV, JSON, JSONLines, Parquet, Markdown, ou tout autre format personnalisé pris en charge par ClickHouse. La fonctionnalité de téléchargement utilise le cache de requêtes pour récupérer efficacement les résultats sans réexécuter la requête. Elle télécharge l’ensemble du jeu de résultats, même si l’interface n’a affiché qu’une seule page parmi de nombreuses autres. L’interface web est conçue pour des professionnels comme vous. Dans les scripts de vérification d’état, utilisez la requête GET /ping. Ce handler renvoie toujours “Ok.” (avec un saut de ligne à la fin). Disponible à partir de la version 18.12.13. Voir aussi /replicas_status pour vérifier le retard de la réplique.

​
Exécuter des requêtes via HTTP/HTTPS

Pour exécuter des requêtes via HTTP/HTTPS, trois options s’offrent à vous :
  • envoyer la requête en tant que paramètre d’URL ‘query’
  • utiliser la méthode POST.
  • envoyer le début de la requête dans le paramètre ‘query’, et le reste via POST
La taille de l’URL est limitée à 1 MiB par défaut ; cela peut être modifié avec le paramètre http_max_uri_size.
En cas de succès, vous recevez le code de réponse 200 ainsi que le résultat dans le corps de la réponse. Si une erreur se produit, vous recevez le code de réponse 500 et un texte décrivant l’erreur dans le corps de la réponse. Les requêtes utilisant GET sont en mode ‘readonly’. Cela signifie que, pour les requêtes qui modifient des données, vous ne pouvez utiliser que la méthode POST. Vous pouvez envoyer la requête elle-même soit dans le corps de la requête POST, soit dans le paramètre d’URL. Examinons quelques exemples. Dans l’exemple ci-dessous, curl est utilisé pour envoyer la requête SELECT 1. Notez l’utilisation de l’encodage URL pour l’espace : %20.
command
Response
Dans cet exemple, wget est utilisé avec les paramètres -nv (non-verbose) et -O- pour afficher le résultat dans le terminal. Dans ce cas, il n’est pas nécessaire d’utiliser l’encodage URL pour l’espace :
command
Dans cet exemple, nous redirigeons une requête HTTP brute vers netcat :
command
response
Comme vous pouvez le constater, la commande curl est assez peu pratique, car les espaces doivent être encodés dans l’URL. Bien que wget encode tout de lui-même, nous ne recommandons pas de l’utiliser, car il ne fonctionne pas bien avec HTTP 1.1 lors de l’utilisation de keep-alive et de Transfer-Encoding: chunked.
Si une partie de la requête est envoyée via le paramètre et l’autre dans le corps de la requête POST, un saut de ligne est inséré entre ces deux blocs de données. Par exemple, ceci ne fonctionnera pas :
Par défaut, les données sont renvoyées au format TabSeparated. La clause FORMAT est utilisée dans la requête pour spécifier un autre format. Par exemple :
command
Response
Vous pouvez utiliser le paramètre d’URL default_format ou l’en-tête X-ClickHouse-Format pour spécifier un format par défaut autre que TabSeparated.
Vous pouvez utiliser la méthode POST avec des requêtes paramétrées. Les paramètres sont indiqués entre accolades, avec le nom et le type du paramètre, comme {name:Type}. Les valeurs des paramètres sont transmises via param_name :

​
Requêtes INSERT via HTTP/HTTPS

La méthode POST est nécessaire pour transmettre des données dans les requêtes INSERT. Dans ce cas, vous pouvez écrire le début de la requête dans le paramètre d’URL et utiliser POST pour transmettre les données à insérer. Les données à insérer peuvent être, par exemple, un dump MySQL séparé par des tabulations. Ainsi, la requête INSERT remplace LOAD DATA LOCAL INFILE de MySQL.

​
Exemples

Pour créer une table :
Pour utiliser la requête INSERT habituelle pour insérer des données :
Pour envoyer les données séparément de la requête :
Tout format de données peut être spécifié. Par exemple, il est possible de spécifier le format ‘Values’, c’est-à-dire le même format que celui utilisé lors de l’écriture de INSERT INTO t VALUES :
Pour insérer des données à partir d’un dump séparé par des tabulations, spécifiez le format correspondant :
Pour lire le contenu de la table :
Les données sont renvoyées dans un ordre aléatoire en raison du traitement parallèle des requêtes
Pour supprimer la table :
Pour les requêtes réussies qui ne renvoient pas de tableau de données, le corps de la réponse est vide.

​
Compression

La compression peut être utilisée pour réduire le trafic réseau lors de la transmission d’un grand volume de données, ou pour créer des dumps déjà compressés. Vous pouvez utiliser le format de compression interne de ClickHouse lors de la transmission de données. Les données compressées ont un format non standard, et vous avez besoin du programme clickhouse-compressor pour les manipuler. Il est installé par défaut avec le paquet clickhouse-client. Pour améliorer l’efficacité de l’insertion de données, désactivez la vérification de la somme de contrôle côté serveur à l’aide du paramètre http_native_compression_disable_checksumming_on_decompress. Si vous spécifiez compress=1 dans l’URL, le serveur compressera les données qu’il vous envoie. Si vous spécifiez decompress=1 dans l’URL, le serveur décompressera les données que vous envoyez dans la méthode POST. Vous pouvez également choisir d’utiliser la compression HTTP. ClickHouse prend en charge les méthodes de compression suivantes :
  • gzip
  • br
  • deflate
  • xz
  • zstd
  • lz4
  • bz2
  • snappy
Pour envoyer une requête POST compressée, ajoutez l’en-tête de requête Content-Encoding: compression_method. Pour que ClickHouse compresse la réponse, ajoutez l’en-tête Accept-Encoding: compression_method à la requête. Vous pouvez configurer le niveau de compression des données à l’aide du paramètre http_zlib_compression_level pour toutes les méthodes de compression.
Certains clients HTTP peuvent décompresser par défaut les données provenant du serveur (avec gzip et deflate), et vous pouvez recevoir des données décompressées même si vous utilisez correctement les paramètres de compression.

​
Exemples

Pour envoyer des données compressées au serveur :
Pour recevoir l’archive de données compressée depuis le serveur :
Pour recevoir des données compressées du serveur, utilisez gunzip afin d’obtenir des données décompressées :

​
Base de données par défaut

Vous pouvez utiliser le paramètre d’URL database ou l’en-tête X-ClickHouse-Database pour indiquer la base de données par défaut.
Par défaut, la base de données enregistrée dans les paramètres du serveur est utilisée comme base de données par défaut. Par défaut, il s’agit de la base de données nommée default. Vous pouvez également toujours préciser la base de données en la faisant précéder d’un point avant le nom de la table.

​
Authentification

Le nom d’utilisateur et le mot de passe peuvent être indiqués de l’une des trois manières suivantes :
  1. En utilisant l’authentification HTTP Basic.
Par exemple :
  1. Dans les paramètres d’URL user et password
Nous déconseillons d’utiliser cette méthode, car ces paramètres peuvent être enregistrés par un proxy web et mis en cache par le navigateur.
Par exemple :
  1. Utilisation des en-têtes ‘X-ClickHouse-User’ et ‘X-ClickHouse-Key’
Par exemple :
Si le nom d’utilisateur n’est pas spécifié, le nom default est utilisé. Si le mot de passe n’est pas spécifié, un mot de passe vide est utilisé. Vous pouvez également utiliser les paramètres d’URL pour définir des réglages pour le traitement d’une seule requête ou de profils complets de réglages. Par exemple :
Pour en savoir plus, consultez :

​
Utilisation des sessions ClickHouse avec le protocole HTTP

Vous pouvez également utiliser les sessions ClickHouse avec le protocole HTTP. Pour ce faire, vous devez ajouter le paramètre GET session_id à la requête. Vous pouvez utiliser n’importe quelle chaîne comme identifiant de session. Par défaut, la session prend fin après 60 secondes d’inactivité. Pour modifier ce délai d’expiration (en secondes), modifiez le paramètre default_session_timeout dans la configuration du serveur, ou ajoutez le paramètre GET session_timeout à la requête. Pour vérifier l’état de la session, utilisez le paramètre session_check=1. Une seule requête à la fois peut être exécutée dans une même session. Vous pouvez recevoir des informations sur la progression d’une requête dans les en-têtes de réponse X-ClickHouse-Progress. Pour ce faire, activez send_progress_in_http_headers. Vous trouverez ci-dessous un exemple de séquence d’en-têtes :
Les champs d’en-tête possibles sont : Les requêtes en cours d’exécution ne s’arrêtent pas automatiquement si la connexion HTTP est perdue. L’analyse syntaxique et le formatage des données sont effectués côté serveur, et le recours au réseau peut s’avérer peu efficace. Les paramètres facultatifs suivants existent : L’interface HTTP permet de transmettre des données externes (tables temporaires externes) pour l’exécution de requêtes. Pour plus d’informations, consultez “External data for query processing”.

​
Mise en tampon des réponses

La mise en tampon des réponses peut être activée côté serveur. Les paramètres d’URL suivants sont disponibles à cet effet :
  • buffer_size
  • wait_end_of_query
Les paramètres suivants peuvent être utilisés : buffer_size détermine le nombre d’octets du résultat à mettre en tampon dans la mémoire du serveur. Si le corps d’un résultat dépasse ce seuil, le tampon est écrit dans le canal HTTP et les données restantes sont envoyées directement à ce canal. Pour garantir que l’intégralité de la réponse soit mise en tampon, définissez wait_end_of_query=1. Dans ce cas, les données qui ne sont pas stockées en mémoire seront mises en tampon dans un fichier temporaire sur le serveur. Par exemple :
Utilisez la mise en mémoire tampon pour éviter les situations où une erreur de traitement de la requête survient après l’envoi au client du code de réponse et des en-têtes HTTP. Dans ce cas, un message d’erreur est ajouté à la fin du corps de la réponse et, côté client, l’erreur ne peut être détectée qu’au stade de l’analyse.

​
Définir un rôle avec des paramètres de requête

Cette fonctionnalité a été ajoutée dans ClickHouse 24.4. Dans certains cas, il peut être nécessaire de définir d’abord le rôle accordé avant d’exécuter l’instruction proprement dite. Cependant, il n’est pas possible d’envoyer SET ROLE et l’instruction en une seule fois, car les requêtes multi-instructions ne sont pas autorisées :
La commande ci-dessus provoque une erreur :
Pour contourner cette limitation, utilisez plutôt le paramètre de requête role :
Cela revient à exécuter SET ROLE my_role avant l’instruction. De plus, il est possible de spécifier plusieurs paramètres de requête role :
Dans ce cas, ?role=my_role&role=my_other_role fonctionne comme si SET ROLE my_role, my_other_role était exécuté avant l’instruction.

​
Mises en garde concernant les codes de réponse HTTP

En raison des limites du protocole HTTP, un code de réponse HTTP 200 ne garantit pas qu’une requête a abouti. Voici un exemple :
La raison de ce comportement tient à la nature du protocole HTTP. L’en-tête HTTP est envoyé en premier avec un code HTTP 200, suivi du corps HTTP, puis l’erreur est injectée dans le corps sous forme de texte brut. Ce comportement est indépendant du format utilisé, qu’il s’agisse de Native, TSV ou JSON ; le message d’erreur se trouvera toujours au milieu du flux de réponse. Vous pouvez atténuer ce problème en activant wait_end_of_query=1 (mise en tampon des réponses). Dans ce cas, l’envoi de l’en-tête HTTP est différé jusqu’à ce que la requête soit entièrement traitée. Cependant, cela ne résout pas complètement le problème, car le résultat doit toujours tenir dans http_response_buffer_size, et d’autres paramètres comme send_progress_in_http_headers peuvent empêcher ce délai d’être appliqué à l’en-tête.
La seule façon de détecter toutes les erreurs consiste à analyser le corps HTTP avant de le parser dans le format requis.
Dans ClickHouse, ces exceptions ont un format cohérent, comme ci-dessous, quel que soit le format utilisé (par ex. Native, TSV, JSON, etc.) lorsque http_write_exception_in_output_format=0 (par défaut). Cela facilite l’analyse et l’extraction des messages d’erreur côté client.
Où <TAG> est un tag aléatoire de 16 octets, identique à celui envoyé dans l’en-tête de réponse X-ClickHouse-Exception-Tag. Le <error message> correspond au message d’exception proprement dit (sa longueur exacte figure dans <message_length>). L’ensemble du bloc d’exception décrit ci-dessus peut atteindre 16 Kio. Voici un exemple au format JSON
Voici un exemple similaire, mais au format CSV

​
Requêtes avec paramètres

Vous pouvez créer une requête avec des paramètres et leur attribuer des valeurs à partir des paramètres de la requête HTTP correspondante. Pour en savoir plus, consultez Requêtes avec paramètres pour l’interface CLI.

​
Exemple

​
Tabulations dans les paramètres d’URL

Les paramètres de requête sont analysés à partir du format “escaped”. Cela présente certains avantages, comme la possibilité d’analyser sans ambiguïté les valeurs NULL sous la forme \N. Cela signifie que le caractère de tabulation doit être encodé sous la forme \t (ou \ suivi d’une tabulation). Par exemple, ce qui suit contient une véritable tabulation entre abc et 123, et la chaîne d’entrée est divisée en deux valeurs :
Cependant, si vous essayez d’encoder un caractère de tabulation réel avec %09 dans un paramètre d’URL, il ne sera pas correctement interprété :
Si vous utilisez des paramètres d’URL, vous devrez encoder \t sous la forme %5C%09. Par exemple :

​
Interface HTTP prédéfinie

ClickHouse prend en charge certaines requêtes via l’interface HTTP. Par exemple, vous pouvez écrire des données dans une table comme suit :
ClickHouse prend également en charge une Interface HTTP prédéfinie, ce qui peut faciliter l’intégration avec des outils tiers comme Prometheus exporter. Prenons un exemple. Tout d’abord, ajoutez cette section à votre fichier de configuration du serveur. http_handlers est configuré pour contenir plusieurs rule. ClickHouse fera correspondre les requêtes HTTP reçues au type prédéfini dans rule, et la première règle qui correspond exécutera le gestionnaire. Ensuite, ClickHouse exécutera la requête prédéfinie correspondante si la correspondance aboutit.
config.xml
Vous pouvez maintenant interroger directement l’URL pour des données au format Prometheus :
Les options de configuration de http_handlers sont les suivantes. rule permet de configurer les paramètres suivants :
  • method
  • headers
  • url
  • full_url
  • handler
Chacun de ces paramètres est décrit ci-dessous :
  • method sert à faire correspondre la partie méthode de la requête HTTP. method est entièrement conforme à la définition de [method] (https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods) dans le protocole HTTP. Il s’agit d’une configuration facultative. S’il n’est pas défini dans le fichier de configuration, aucune correspondance n’est effectuée sur la partie méthode de la requête HTTP.
  • url sert à faire correspondre la partie URL (chemin et chaîne de requête) de la requête HTTP. Si url est préfixé par regex:, il attend des expressions régulières RE2. Il s’agit d’une configuration facultative. S’il n’est pas défini dans le fichier de configuration, aucune correspondance n’est effectuée sur la partie URL de la requête HTTP.
  • full_url est identique à url, mais inclut l’URL complète, c.-à-d. schema://host:port/path?query_string. Remarque : ClickHouse ne prend pas en charge les « hôtes virtuels », donc host est une adresse IP (et non la valeur de l’en-tête Host).
  • empty_query_string - garantit l’absence de chaîne de requête (?query_string) dans la requête
  • headers servent à faire correspondre la partie en-têtes de la requête HTTP. Ils sont compatibles avec les expressions régulières RE2. Il s’agit d’une configuration facultative. S’ils ne sont pas définis dans le fichier de configuration, aucune correspondance n’est effectuée sur la partie en-têtes de la requête HTTP.
  • handler contient la partie principale du traitement. Il peut avoir le type suivant : Et les paramètres suivants :
    • query — à utiliser avec le type predefined_query_handler, exécute la query lorsque le gestionnaire est appelé.
    • query_param_name — à utiliser avec le type dynamic_query_handler, extrait et exécute la valeur correspondant à query_param_name dans les paramètres de requête HTTP.
    • status — à utiliser avec le type static, code d’état de la réponse.
    • content_type — à utiliser avec n’importe quel type, content-type de la réponse.
    • http_response_headers — à utiliser avec n’importe quel type, map des en-têtes de la réponse. Peut également être utilisé pour définir le type de contenu.
    • response_content — à utiliser avec le type static, contenu de la réponse envoyé au client ; lors de l’utilisation du préfixe ‘file://’ ou ‘config://’, le contenu est lu depuis le fichier ou la configuration, puis envoyé au client.
    • user - utilisateur avec lequel exécuter la query (l’utilisateur par défaut est default). Remarque, vous n’avez pas besoin de spécifier de password pour cet utilisateur.
Les méthodes de configuration pour les différents type sont décrites ci-dessous.

​
predefined_query_handler

predefined_query_handler prend en charge la définition des valeurs Settings et query_params. Vous pouvez configurer query pour le type predefined_query_handler. La valeur query est une requête prédéfinie de predefined_query_handler, exécutée par ClickHouse lorsqu’une requête HTTP correspond, puis le résultat de la requête est renvoyé. Cette configuration est obligatoire. L’exemple suivant définit les valeurs des paramètres max_threads et max_final_threads, puis interroge la table système pour vérifier si ces paramètres ont bien été définis.
Pour conserver les handlers par défaut tels que query, play, ping, ajoutez la règle <defaults/>.
Par exemple :

​
Paramètre virtuel _request_body

En plus des paramètres d’URL, des en-têtes et des paramètres de requête, predefined_query_handler prend en charge un paramètre virtuel spécial, _request_body. Il contient le corps brut de la requête HTTP sous forme de chaîne de caractères. Cela vous permet de créer des API REST flexibles, capables d’accepter des formats de données arbitraires et de les traiter dans vos requêtes. Par exemple, vous pouvez utiliser _request_body pour implémenter un point de terminaison REST qui accepte des données JSON dans une requête POST et les insère dans une table :
Vous pouvez ensuite envoyer des données à ce point de terminaison :
Dans un predefined_query_handler, une seule query est acceptée.

​
dynamic_query_handler

Dans dynamic_query_handler, la requête est écrite comme paramètre de la requête HTTP. La différence est que, dans predefined_query_handler, la requête est écrite dans le fichier de configuration. query_param_name peut être configuré dans dynamic_query_handler. ClickHouse extrait et exécute la valeur associée à query_param_name dans l’URL de la requête HTTP. La valeur par défaut de query_param_name est /query . Cette configuration est facultative. Si rien n’est défini dans le fichier de configuration, le paramètre n’est pas transmis. Pour tester cette fonctionnalité, l’exemple suivant définit les valeurs de max_threads et max_final_threads, puis vérifie par une requête si les paramètres ont bien été définis. Exemple :

​
static

static peut renvoyer content_type, status et response_content. response_content peut renvoyer le contenu indiqué. Par exemple, pour renvoyer le message “Bonjour !” :
http_response_headers peut être utilisé pour définir le type de contenu à la place de content_type.
Retrouvez le contenu de la configuration envoyée au client.
Pour trouver le contenu du fichier transmis au client :

​
redirect

redirect effectue une redirection 302 vers location Par exemple, voici comment ajouter automatiquement set user à play dans ClickHouse play :

​
En-têtes de réponse HTTP

ClickHouse vous permet de configurer des en-têtes de réponse HTTP personnalisés, applicables à tout type de gestionnaire configurable. Ces en-têtes peuvent être définis à l’aide du paramètre http_response_headers, qui accepte des paires clé-valeur représentant les noms des en-têtes et leurs valeurs. Cette fonctionnalité est particulièrement utile pour mettre en place des en-têtes de sécurité personnalisés, des politiques CORS ou toute autre exigence relative aux en-têtes HTTP sur votre interface HTTP ClickHouse. Par exemple, vous pouvez configurer des en-têtes pour :
  • Points de terminaison de requête standard
  • Web UI
  • Vérification d’état.
Il est également possible de spécifier common_http_response_headers. Ceux-ci seront appliqués à tous les gestionnaires HTTP définis dans la configuration. Les en-têtes seront inclus dans la réponse HTTP de chaque gestionnaire configuré. Dans l’exemple ci-dessous, chaque réponse du serveur contiendra deux en-têtes personnalisés : X-My-Common-Header et X-My-Custom-Header.

​
Réponse JSON/XML valide en cas d’exception lors du streaming HTTP

Lorsqu’une requête est exécutée via HTTP, une exception peut se produire alors qu’une partie des données a déjà été envoyée. En général, l’exception est envoyée au client en texte brut. Même si un format de données spécifique a été utilisé pour la sortie, celle-ci peut devenir invalide au regard du format spécifié. Pour éviter cela, vous pouvez utiliser le paramètre http_write_exception_in_output_format (désactivé par défaut), qui indique à ClickHouse d’écrire l’exception dans le format spécifié (actuellement pris en charge pour les formats XML et JSON*). Exemples :
Dernière modification le 2 juillet 2026