Client ClickHouse - ClickHouse Documentation

ClickHouse fournit un client en ligne de commande natif permettant d’exécuter des requêtes SQL directement sur un serveur ClickHouse. Il prend en charge à la fois le mode interactif (pour l’exécution en direct des requêtes) et le mode batch (pour les scripts et l’automatisation). Les résultats des requêtes peuvent être affichés dans le terminal ou exportés vers un fichier, avec la prise en charge de tous les formats de sortie de ClickHouse, tels que Pretty, CSV, JSON, etc. Le client fournit un retour en temps réel sur l’exécution des requêtes grâce à une barre de progression, au nombre de lignes lues, au nombre d’octets traités et au temps d’exécution des requêtes. Il prend en charge à la fois les options de ligne de commande et les fichiers de configuration.

Installation

Pour télécharger ClickHouse, exécutez :

curl https://clickhouse.com/ | sh

Pour l’installer également, exécutez :

sudo ./clickhouse install

Voir Installer ClickHouse pour découvrir d’autres options d’installation. Les différentes versions du client et du serveur sont compatibles entre elles, mais certaines fonctionnalités peuvent ne pas être disponibles dans les anciennes versions du client. Nous vous recommandons d’utiliser la même version pour le client et le serveur.

Exécuter

Si vous avez seulement téléchargé ClickHouse sans l’installer, utilisez ./clickhouse client au lieu de clickhouse-client.

Pour vous connecter à un serveur ClickHouse, exécutez :

$ clickhouse-client --host server

ClickHouse client version 24.12.2.29 (official build).
Connecting to server:9000 as user default.
Connected to ClickHouse server version 24.12.2.

:)

Précisez des détails de connexion supplémentaires si nécessaire :

Option	Description
`--port <port>`	Le port sur lequel le serveur ClickHouse accepte les connexions. Les ports par défaut sont 9440 (TLS) et 9000 (sans TLS). Si ni `--port` ni `--secure` n’est spécifié, les deux ports par défaut sont essayés simultanément et celui qui répond en premier est utilisé, ce qui permet de se connecter à un serveur qui n’écoute que sur l’un d’eux sans attendre l’expiration du délai de connexion de l’autre. Notez que ClickHouse Client utilise le protocole natif, et non HTTP(S).
`-s [ --secure ]`	Indique s’il faut utiliser TLS (généralement détecté automatiquement).
`-u [ --user ] <username>`	L’utilisateur de base de données avec lequel se connecter. Par défaut, la connexion s’effectue avec l’utilisateur `default`.
`--password <password>`	Le mot de passe de l’utilisateur de base de données. Vous pouvez également spécifier le mot de passe d’une connexion dans le fichier de configuration. Si vous ne spécifiez pas le mot de passe, le client le demandera.
`-c [ --config ] <path-to-file>`	L’emplacement du fichier de configuration de ClickHouse Client, s’il ne se trouve pas dans l’un des emplacements par défaut. Voir Fichiers de configuration.
`--connection <name>`	Le nom de détails de connexion préconfigurés issus du fichier de configuration.

Pour obtenir la liste complète des options de ligne de commande, voir Options de ligne de commande.

Se connecter à ClickHouse Cloud

Les informations de votre service ClickHouse Cloud sont disponibles dans la console ClickHouse Cloud. Sélectionnez le service auquel vous souhaitez vous connecter, puis cliquez sur Connect :

Choisissez Native : les informations de connexion s’affichent avec un exemple de commande clickhouse-client :

Stocker des connexions dans un fichier de configuration

Vous pouvez enregistrer les détails de connexion d’un ou de plusieurs serveurs ClickHouse dans un fichier de configuration. Le format est le suivant :

<config>
    <connections_credentials>
        <connection>
            <name>default</name>
            <hostname>hostname</hostname>
            <port>9440</port>
            <secure>1</secure>
            <user>default</user>
            <password>password</password>
            <!-- <history_file></history_file> -->
            <!-- <history_max_entries></history_max_entries> -->
            <!-- <accept-invalid-certificate>false</accept-invalid-certificate> -->
            <!-- <prompt></prompt> -->
        </connection>
    </connections_credentials>
</config>

Voir la section sur les fichiers de configuration pour plus d’informations.

Afin de se concentrer sur la syntaxe des requêtes, les exemples suivants omettent les informations de connexion (--host, --port, etc.). N’oubliez pas de les ajouter lorsque vous utilisez ces commandes.

Mode interactif

Utilisation du mode interactif

Pour exécuter ClickHouse en mode interactif, il suffit d’exécuter :

clickhouse-client

Cela ouvre l’environnement Read-Eval-Print Loop (REPL), dans lequel vous pouvez commencer à saisir des requêtes SQL de manière interactive. Une fois connecté, une invite s’affiche et vous pouvez saisir des requêtes :

ClickHouse client version 25.x.x.x
Connecting to localhost:9000 as user default.
Connected to ClickHouse server version 25.x.x.x

hostname :)

En mode interactif, le format de sortie par défaut est PrettyCompact. Vous pouvez modifier le format dans la clause FORMAT de la requête ou en spécifiant l’option de ligne de commande --format. Pour utiliser le format Vertical, vous pouvez utiliser --vertical ou ajouter \G à la fin de la requête. Dans ce format, chaque valeur est affichée sur une ligne distincte, ce qui est pratique pour les tables larges. En mode interactif, par défaut, tout ce que vous saisissez est exécuté lorsque vous appuyez sur Enter. Il n’est pas nécessaire de terminer la requête par un point-virgule. Vous pouvez démarrer le client avec le paramètre -m, --multiline. Pour saisir une requête sur plusieurs lignes, entrez une barre oblique inverse \ avant le retour à la ligne. Après avoir appuyé sur Enter, vous serez invité à saisir la ligne suivante de la requête. Pour exécuter la requête, terminez-la par un point-virgule et appuyez sur Enter. ClickHouse Client est basé sur replxx (similaire à readline), il utilise donc des raccourcis clavier familiers et conserve un historique. L’historique est écrit dans ~/.clickhouse-client-history par défaut. Pour quitter le client, appuyez sur Ctrl+D ou saisissez l’une des commandes suivantes à la place d’une requête :

exit ou exit;
quit ou quit;
q, Q ou :q
logout ou logout;

Obtenir de l’aide

Vous pouvez consulter la documentation de n’importe quelle fonction, moteur de table, type de données, format, paramètre ou autre composant du système sans quitter le client. Saisissez help suivi d’un nom (les formes équivalentes /help, man et /man fonctionnent également) :

help domainWithoutWWW

La recherche est insensible à la casse et interroge la table system.documentation. La documentation correspondante est affichée dans le terminal à partir du Markdown, avec du texte en gras/en italique, des tableaux et des blocs de code avec coloration syntaxique. Lorsqu’un même nom correspond à plusieurs composants (par exemple file, qui est à la fois une fonction et un moteur de table), ils sont tous affichés. Lorsqu’aucune correspondance exacte n’est trouvée, le client liste les noms similaires (en tolérant les fautes de frappe) ainsi que les composants dont la documentation mentionne ce mot :

help maxx_threads

Saisir simplement help affiche un bref résumé d’utilisation.

Commandes

Le client exécute lui-même certaines commandes commençant par /, au lieu de les envoyer au serveur :

Commande	Description
`/help <name>`, `/man <name>`	Affiche la documentation de `<name>`, comme `help` ci-dessus
`/clear`	Efface le terminal

La saisie de / au début de l’entrée affiche la liste des commandes sous forme d’indications ; à mesure que vous saisissez le nom, la liste se restreint. Tab complète la commande en cours de saisie, y compris lorsque les indications sont désactivées. Un / saisi seul n’est pas une commande : comme dans Oracle SQL*Plus, il répète la dernière entrée. Un nom de commande mal orthographié est signalé comme tel, avec les commandes auxquelles il pourrait correspondre, au lieu d’être exécuté comme une requête :

:) /hepl

Exception on client:
Code: 36. DB::Exception: Unknown command `/hepl`. Maybe you meant: ['/help']. Type `/` at the beginning of the line to see all the commands. (BAD_ARGUMENTS)

Informations sur le traitement des requêtes

Lors du traitement d’une requête, le client affiche :

La progression, qui n’est, par défaut, pas mise à jour plus de 10 fois par seconde. Pour les requêtes rapides, elle peut ne pas avoir le temps de s’afficher.
La requête mise en forme après l’analyse, à des fins de débogage.
Le résultat dans le format spécifié.
Le nombre de lignes du résultat, le temps écoulé et la vitesse moyenne de traitement de la requête. Tous les volumes de données se rapportent à des données non compressées.

Vous pouvez annuler une requête longue en appuyant sur Ctrl+C. Cependant, vous devrez tout de même attendre un peu que le serveur interrompe la requête. Il n’est pas possible d’annuler une requête à certaines étapes. Si vous n’attendez pas et appuyez une deuxième fois sur Ctrl+C, le client se fermera. ClickHouse Client permet de transmettre des données externes (tables temporaires externes) pour exécuter des requêtes. Pour plus d’informations, consultez la section Données externes pour le traitement des requêtes.

Aliases

Vous pouvez utiliser les alias suivants depuis le REPL :

\l - SHOW DATABASES
\d - SHOW TABLES
\d <TABLE> - DESCRIBE TABLE <TABLE>
\c <DATABASE> - USE <DATABASE>
. - répéter la dernière requête

Un argument de \d qui prolonge la requête SHOW TABLES au lieu de désigner une table — comme dans \d FROM system ou \d LIKE 'hits%' — conserve le listing. Une table dont le nom correspond à l’une de ces clauses doit être placée entre accents graves : \d `format`.

Raccourcis clavier

Alt (Option) + Shift + e - ouvre l’éditeur avec la requête en cours. Il est possible de définir l’éditeur à utiliser via la variable d’environnement EDITOR. Par défaut, vim est utilisé.
Alt (Option) + # - commenter la ligne.
Ctrl + r - recherche floue dans l’historique.

La liste complète des raccourcis clavier disponibles est consultable sur replxx.

Pour configurer correctement la touche Meta (Option) sur MacOS :iTerm2 : accédez à Preferences -> Profile -> Keys -> Left Option key, puis cliquez sur Esc+

Mode batch

Utiliser le mode batch

Au lieu d’utiliser le client ClickHouse en mode interactif, vous pouvez l’exécuter en mode batch. En mode batch, ClickHouse exécute une seule requête puis se ferme immédiatement - il n’y a ni invite interactive ni boucle. Vous pouvez spécifier une seule requête comme ceci :

$ clickhouse-client "SELECT sum(number) FROM numbers(10)"
45

Vous pouvez également utiliser l’option --query en ligne de commande :

$ clickhouse-client --query "SELECT uniq(number) FROM numbers(10)"
10

Vous pouvez fournir une requête via stdin :

$ echo "SELECT avg(number) FROM numbers(10)" | clickhouse-client
4.5

En supposant qu’une table messages existe, vous pouvez également insérer des données depuis la ligne de commande :

$ echo "Hello\nGoodbye" | clickhouse-client --query "INSERT INTO messages FORMAT CSV"

Lorsque --query est spécifié, toute entrée est ajoutée à la requête après un retour à la ligne.

Insertion d’un fichier CSV dans un service ClickHouse distant

Cet exemple insère un jeu de données CSV d’exemple, cell_towers.csv, dans la table existante cell_towers de la base de données default :

clickhouse-client --host HOSTNAME.clickhouse.cloud \
  --port 9440 \
  --user default \
  --password PASSWORD \
  --query "INSERT INTO cell_towers FORMAT CSVWithNames" \
  < cell_towers.csv

Exemples d’insertion de données en ligne de commande

Il existe plusieurs façons d’insérer des données en ligne de commande. L’exemple ci-dessous insère deux lignes de données CSV dans une table ClickHouse en mode batch :

echo -ne "1, 'some text', '2016-08-14 00:00:00'\n2, 'some more text', '2016-08-14 00:00:01'" | \
  clickhouse-client --database=test --query="INSERT INTO test FORMAT CSV";

Dans l’exemple ci-dessous, cat <<_EOF démarre un heredoc qui lit tout le contenu jusqu’à ce qu’il rencontre à nouveau _EOF, puis l’affiche :

cat <<_EOF | clickhouse-client --database=test --query="INSERT INTO test FORMAT CSV";
3, 'some text', '2016-08-14 00:00:00'
4, 'some more text', '2016-08-14 00:00:01'
_EOF

Dans l’exemple ci-dessous, le contenu de file.csv est envoyé vers stdout à l’aide de cat, puis transmis à clickhouse-client via un pipe en entrée :

cat file.csv | clickhouse-client --database=test --query="INSERT INTO test FORMAT CSV";

En mode batch, le format de données par défaut est TabSeparated. Vous pouvez définir le format dans la clause FORMAT de la requête, comme indiqué dans l’exemple ci-dessus.

Requêtes paramétrées

Vous pouvez définir des paramètres dans une requête et leur transmettre des valeurs à l’aide d’options en ligne de commande. Cela évite d’avoir à formater la requête avec des valeurs dynamiques spécifiques côté client. Par exemple :

$ clickhouse-client --param_parName="[1, 2]" --query "SELECT {parName: Array(UInt16)}"
[1,2]

Il est également possible de définir des paramètres dans une session interactive :

$ clickhouse-client
ClickHouse client version 25.X.X.XXX (official build).

:) SET param_parName='[1, 2]';

SET param_parName = '[1, 2]'

Query id: 7ac1f84e-e89a-4eeb-a4bb-d24b8f9fd977

Ok.

0 rows in set. Elapsed: 0.000 sec.

:) SELECT {parName:Array(UInt16)}

SELECT {parName:Array(UInt16)}

Query id: 0358a729-7bbe-4191-bb48-29b063c548a7

   ┌─_CAST([1, 2]⋯y(UInt16)')─┐
1. │ [1,2]                    │
   └──────────────────────────┘

1 row in set. Elapsed: 0.006 sec.

Syntaxe de la requête

Dans la requête, placez entre accolades les valeurs que vous souhaitez renseigner à l’aide des paramètres de ligne de commande, au format suivant :

{<name>:<data type>}

Paramètre	Description
`name`	Identifiant de substitution. L’option de ligne de commande correspondante est `--param_<name> = value`.
`data type`	type de données du paramètre. Par exemple, une structure de données comme `(integer, ('string', integer))` peut avoir pour type de données `Tuple(UInt8, Tuple(String, UInt8))` (vous pouvez également utiliser d’autres types entier). Il est également possible de transmettre en paramètres le nom de la table, le nom de la base de données et les noms des colonnes ; dans ce cas, vous devrez utiliser `Identifier` comme type de données.

Exemples

$ clickhouse-client --param_tuple_in_tuple="(10, ('dt', 10))" \
    --query "SELECT * FROM table WHERE val = {tuple_in_tuple:Tuple(UInt8, Tuple(String, UInt8))}"

$ clickhouse-client --param_tbl="numbers" --param_db="system" --param_col="number" --param_alias="top_ten" \
    --query "SELECT {col:Identifier} as {alias:Identifier} FROM {db:Identifier}.{tbl:Identifier} LIMIT 10"

Génération SQL assistée par IA

ClickHouse Client inclut une assistance IA intégrée pour générer des requêtes SQL à partir de descriptions en langage naturel. Cette fonctionnalité permet aux utilisateurs de rédiger des requêtes complexes sans avoir besoin de connaissances approfondies en SQL. L’assistance IA fonctionne immédiatement si la variable d’environnement OPENAI_API_KEY ou ANTHROPIC_API_KEY est définie. Pour une configuration plus avancée, consultez la section Configuration.

Utilisation

Pour utiliser la génération SQL par IA, faites précéder votre requête en langage naturel de ?? :

:) ?? show all users who made purchases in the last 30 days

L’IA va :

Explorer automatiquement le schéma de votre base de données
Générer une requête SQL adaptée en fonction des tables et des colonnes détectées
Exécuter immédiatement la requête générée

Exemple

:) ?? count orders by product category

Starting AI SQL generation with schema discovery...
──────────────────────────────────────────────────

🔍 list_databases
   ➜ system, default, sales_db

🔍 list_tables_in_database
   database: sales_db
   ➜ orders, products, categories

🔍 get_schema_for_table
   database: sales_db
   table: orders
   ➜ CREATE TABLE orders (order_id UInt64, product_id UInt64, quantity UInt32, ...)

✨ SQL query generated successfully!
──────────────────────────────────────────────────

SELECT
    c.name AS category,
    COUNT(DISTINCT o.order_id) AS order_count
FROM sales_db.orders o
JOIN sales_db.products p ON o.product_id = p.product_id
JOIN sales_db.categories c ON p.category_id = c.category_id
GROUP BY c.name
ORDER BY order_count DESC

Configuration

La génération SQL par IA nécessite de configurer un fournisseur d’IA dans le fichier de configuration de votre client ClickHouse. Vous pouvez utiliser OpenAI, Anthropic ou tout service d’API compatible avec OpenAI.

Bascule de secours via l’environnement

Si aucune configuration d’IA n’est spécifiée dans le fichier de configuration, ClickHouse Client essaiera automatiquement d’utiliser les variables d’environnement :

Vérifie d’abord la variable d’environnement OPENAI_API_KEY
Si elle n’est pas trouvée, vérifie la variable d’environnement ANTHROPIC_API_KEY
Si aucune des deux n’est trouvée, les fonctionnalités d’IA seront désactivées

Cela permet une configuration rapide sans fichier de configuration :

# Using OpenAI
export OPENAI_API_KEY=your-openai-key
clickhouse-client

# Using Anthropic
export ANTHROPIC_API_KEY=your-anthropic-key
clickhouse-client

Fichier de configuration

Pour mieux maîtriser les paramètres de l’IA, configurez-les dans le fichier de configuration de votre ClickHouse Client, situé à l’un des emplacements suivants :

$XDG_CONFIG_HOME/clickhouse/config.xml (ou ~/.config/clickhouse/config.xml si XDG_CONFIG_HOME n’est pas défini) (format XML)
$XDG_CONFIG_HOME/clickhouse/config.yaml (ou ~/.config/clickhouse/config.yaml si XDG_CONFIG_HOME n’est pas défini) (format YAML)
~/.clickhouse-client/config.xml (format XML, emplacement legacy)
~/.clickhouse-client/config.yaml (format YAML, emplacement legacy)
Ou indiquez un emplacement personnalisé avec --config-file

XML
YAML

<config>
    <ai>
        {/* Requis : votre clé API (ou définie via une variable d’environnement) */}
        <api_key>your-api-key-here</api_key>

        {/* Requis : type de fournisseur (openai, anthropic) */}
        <provider>openai</provider>

        {/* Modèle à utiliser (les valeurs par défaut varient selon le fournisseur) */}
        <model>gpt-4o</model>

        {/* Facultatif : point de terminaison de l’API personnalisé pour les services compatibles OpenAI */}
        {/* <base_url>https://openrouter.ai/api</base_url> */}

        {/* Paramètres d’exploration du schéma */}
        <enable_schema_access>true</enable_schema_access>

        {/* Paramètres de génération */}
        {/* Facultatif : `temperature` n’est envoyé au modèle que lorsqu’il est défini ici.
             Il est omis par défaut, car certains modèles rejettent ce paramètre. */}
        {/* <temperature>0.0</temperature> */}
        <max_tokens>1000</max_tokens>
        <timeout_seconds>30</timeout_seconds>
        <max_steps>10</max_steps>

        {/* Facultatif : prompt système personnalisé */}
        {/* <system_prompt>You are an expert ClickHouse SQL assistant...</system_prompt> */}
    </ai>
</config>

ai:
  # Requis : votre clé API (ou définie via une variable d’environnement)
  api_key: your-api-key-here

  # Requis : type de fournisseur (openai, anthropic)
  provider: openai

  # Modèle à utiliser
  model: gpt-4o

  # Facultatif : point de terminaison de l’API personnalisé pour les services compatibles OpenAI
  # base_url: https://openrouter.ai/api

  # Active l’accès au schéma - permet à l’IA d’interroger les informations sur les bases de données et les tables
  enable_schema_access: true

  # Paramètres de génération
  # `temperature` n’est envoyé au modèle que lorsqu’il est défini ici ; il est omis par défaut
  # car certains modèles rejettent ce paramètre.
  # temperature: 0.0    # Contrôle le niveau d’aléa (0.0 = déterministe)
  max_tokens: 1000      # Longueur maximale de la réponse
  timeout_seconds: 30   # Délai d’expiration de la requête
  max_steps: 10         # Nombre maximal d’étapes d’exploration du schéma

  # Facultatif : prompt système personnalisé
  # system_prompt: |
  #   You are an expert ClickHouse SQL assistant. Convert natural language to SQL.
  #   Focus on performance and use ClickHouse-specific optimizations.
  #   Always return executable SQL without explanations.

Utilisation d’API compatibles OpenAI (par ex. OpenRouter) :

ai:
  provider: openai  # Use 'openai' for compatibility
  api_key: your-openrouter-api-key
  base_url: https://openrouter.ai/api/v1
  model: anthropic/claude-3.5-sonnet  # Use OpenRouter model naming

Exemples de configuration minimale :

# Minimal config - uses environment variable for API key
ai:
  provider: openai  # Will use OPENAI_API_KEY env var

# No config at all - automatic fallback
# (Empty or no ai section - will try OPENAI_API_KEY then ANTHROPIC_API_KEY)

# Only override model - uses env var for API key
ai:
  provider: openai
  model: gpt-3.5-turbo

Paramètres

Paramètres requis

api_key - Votre clé API pour le service d’IA. Peut être omise si elle est définie via une variable d’environnement :
- OpenAI : OPENAI_API_KEY
- Anthropic : ANTHROPIC_API_KEY
- Remarque : la clé API du fichier de configuration prévaut sur la variable d’environnement
provider - Le fournisseur d’IA : openai ou anthropic
- S’il est omis, le système utilise automatiquement les variables d’environnement disponibles

Configuration du modèle

model - Le modèle à utiliser (par défaut : selon le fournisseur)
- OpenAI : gpt-4o, gpt-4, gpt-3.5-turbo, etc.
- Anthropic : claude-3-5-sonnet-20241022, claude-3-opus-20240229, etc.
- OpenRouter : utilisez leur convention de nommage des modèles, par exemple anthropic/claude-3.5-sonnet

Paramètres de connexion

base_url - point de terminaison de l’API personnalisé pour les services compatibles OpenAI (facultatif)
timeout_seconds - Délai d’expiration de la requête, en secondes (par défaut : 30)

Exploration du schéma

enable_schema_access - Autoriser l’IA à explorer les schémas de la base de données (par défaut : true)
max_steps - Nombre maximal d’étapes d’appel d’outils pour l’exploration du schéma (par défaut : 10)

Paramètres de génération

temperature - Contrôle le niveau d’aléa, 0.0 = déterministe, 1.0 = créatif. Omis par défaut et envoyé au modèle uniquement lorsqu’il est explicitement défini, car certains modèles rejettent ce paramètre.
max_tokens - Longueur maximale de la réponse en tokens (par défaut : 1000)
system_prompt - Instructions personnalisées pour l’IA (facultatif)

Fonctionnement

Le générateur SQL par IA suit un processus en plusieurs étapes :

Découverte du schéma

L’IA utilise des outils intégrés pour explorer votre base de données

Répertorie les bases de données disponibles
Identifie les tables dans les bases de données pertinentes
Examine la structure des tables à l’aide d’instructions CREATE TABLE

Génération de requêtes

À partir du schéma découvert, l’IA génère du SQL qui :

Correspond à votre intention exprimée en langage naturel
Utilise les noms de tables et de colonnes corrects
Applique les jointures et agrégations appropriées

Exécution

Le SQL généré est exécuté automatiquement et les résultats sont affichés

Limitations

Nécessite une connexion Internet active
L’utilisation de l’API est soumise aux limites de requêtes et aux coûts du fournisseur d’IA
Les requêtes complexes peuvent nécessiter plusieurs ajustements
L’IA a un accès en lecture seule aux informations de schéma, et non aux données elles-mêmes

Sécurité

Les clés API ne sont jamais envoyées aux serveurs ClickHouse
L’IA n’a accès qu’aux informations de schéma (noms des tables/colonnes et types), pas aux données elles-mêmes
Toutes les requêtes générées respectent les permissions existantes de votre base de données

Chaîne de connexion

Utilisation

ClickHouse Client prend également en charge la connexion à un serveur ClickHouse au moyen d’une chaîne de connexion semblable à celles de MongoDB, PostgreSQL et MySQL. La syntaxe est la suivante :

clickhouse:[//[user[:password]@][hosts_and_ports]][/database][?query_parameters]

Composant (tous facultatifs)	Description	Par défaut
`user`	Nom d’utilisateur de la base de données.	`default`
`password`	Mot de passe de l’utilisateur de la base de données. Si `:` est spécifié et que le mot de passe est vide, le client invitera l’utilisateur à saisir son mot de passe.	-
`hosts_and_ports`	Liste d’hôtes et, éventuellement, de ports `host[:port] [, host:[port]], ...`.	`localhost:9000`
`database`	Nom de la base de données.	`default`
`query_parameters`	Liste de paires clé-valeur `param1=value1[,&param2=value2], ...`. Pour certains paramètres, aucune valeur n’est requise. Les noms et les valeurs des paramètres sont sensibles à la casse.	-

Remarques

Si le nom d’utilisateur, le mot de passe ou la base de données sont spécifiés dans la chaîne de connexion, ils ne peuvent pas l’être avec --user, --password ou --database (et inversement). La composante host peut être soit un nom d’hôte, soit une adresse IPv4 ou IPv6. Les adresses IPv6 doivent être entre [] :

clickhouse://[2001:db8::1234]

Les chaînes de connexion peuvent contenir plusieurs hôtes. ClickHouse Client essaiera de se connecter à ces hôtes dans l’ordre (de gauche à droite). Une fois la connexion établie, il n’essaiera pas de se connecter aux hôtes restants. La chaîne de connexion doit être spécifiée comme premier argument de clickhouse-client. La chaîne de connexion peut être combinée avec n’importe quel nombre d’autres options de ligne de commande, à l’exception de --host et --port. Les clés suivantes sont autorisées pour query_parameters :

Key	Description
`secure` (or `s`)	Si elle est spécifiée, le client se connectera au serveur via une connexion sécurisée (TLS). Voir `--secure` dans les options de ligne de commande.

Encodage en pourcentage Les caractères non ASCII, les espaces et les caractères spéciaux dans les paramètres suivants doivent être encodés en pourcentage :

user
password
hosts
database
query parameters

Exemples

Connectez-vous à localhost sur le port 9000 et exécutez la requête SELECT 1.

clickhouse-client clickhouse://localhost:9000 --query "SELECT 1"

Connectez-vous à localhost avec l’utilisateur john, le mot de passe secret, l’hôte 127.0.0.1 et le port 9000

clickhouse-client clickhouse://john:secret@127.0.0.1:9000

Connectez-vous à localhost avec l’utilisateur default, à l’hôte ayant l’adresse IPv6 [::1] et sur le port 9000.

clickhouse-client clickhouse://[::1]:9000

Connectez-vous à localhost sur le port 9000 en mode multiligne.

clickhouse-client clickhouse://localhost:9000 '-m'

Connectez-vous à localhost sur le port 9000 en tant qu’utilisateur default.

clickhouse-client clickhouse://default@localhost:9000

# equivalent to:
clickhouse-client clickhouse://localhost:9000 --user default

Connectez-vous à localhost sur le port 9000 et utilisez la base de données my_database par défaut.

clickhouse-client clickhouse://localhost:9000/my_database

# equivalent to:
clickhouse-client clickhouse://localhost:9000 --database my_database

Connectez-vous à localhost sur le port 9000, utilisez par défaut la base de données my_database spécifiée dans la chaîne de connexion et activez une connexion sécurisée à l’aide du paramètre abrégé s.

clickhouse-client clickhouse://localhost/my_database?s

# equivalent to:
clickhouse-client clickhouse://localhost/my_database -s

Connectez-vous à l’hôte par défaut à l’aide du port par défaut, de l’utilisateur default et de la base de données par défaut.

clickhouse-client clickhouse:

Connectez-vous à l’hôte par défaut via le port par défaut, avec l’utilisateur my_user et sans mot de passe.

clickhouse-client clickhouse://my_user@

# Using a blank password between : and @ means to asking the user to enter the password before starting the connection.
clickhouse-client clickhouse://my_user:@

Connectez-vous à localhost en utilisant l’adresse e-mail comme nom d’utilisateur. Le symbole @ est encodé au format pourcentage sous la forme %40.

clickhouse-client clickhouse://some_user%40some_mail.com@localhost:9000

Connectez-vous à l’une de ces deux adresses IP : 192.168.1.15, 192.168.1.25.

clickhouse-client clickhouse://192.168.1.15,192.168.1.25

Format de l’identifiant de requête

En mode interactif, ClickHouse Client affiche l’identifiant de requête pour chaque requête. Par défaut, l’identifiant se présente ainsi :

Query id: 927f137d-00f1-4175-8914-0dd066365e96

Un format personnalisé peut être défini dans un fichier de configuration, à l’intérieur d’une balise query_id_formats. Le marqueur {query_id} dans la chaîne de format est remplacé par l’ID de la requête. Plusieurs chaînes de format sont autorisées à l’intérieur de la balise. Cette fonctionnalité peut être utilisée pour générer des URL afin de faciliter le profiling des requêtes. Exemple

<config>
  <query_id_formats>
    <speedscope>http://speedscope-host/#profileURL=qp%3Fid%3D{query_id}</speedscope>
  </query_id_formats>
</config>

Avec la configuration ci-dessus, l’identifiant d’une requête s’affiche au format suivant :

speedscope:http://speedscope-host/#profileURL=qp%3Fid%3Dc8ecc783-e753-4b38-97f1-42cddfb98b7d

Fichiers de configuration

ClickHouse Client utilise le premier fichier existant dans la liste suivante :

Un fichier défini avec le paramètre -c [ -C, --config, --config-file ].
./clickhouse-client.[xml|yaml|yml]
$XDG_CONFIG_HOME/clickhouse/config.[xml|yaml|yml] (ou ~/.config/clickhouse/config.[xml|yaml|yml] si XDG_CONFIG_HOME n’est pas défini)
~/.clickhouse-client/config.[xml|yaml|yml]
/etc/clickhouse-client/config.[xml|yaml|yml]

Consultez l’exemple de fichier de configuration dans le dépôt ClickHouse : clickhouse-client.xml

XML
YAML

<config>
    <user>username</user>
    <password>password</password>
    <secure>true</secure>
    <openSSL>
      <client>
        <caConfig>/etc/ssl/cert.pem</caConfig>
      </client>
    </openSSL>
</config>

user: username
password: 'password'
secure: true
openSSL:
  client:
    caConfig: '/etc/ssl/cert.pem'

Options des variables d’environnement

Le nom d’utilisateur, le mot de passe et l’hôte peuvent être définis à l’aide des variables d’environnement CLICKHOUSE_USER, CLICKHOUSE_PASSWORD et CLICKHOUSE_HOST. Les arguments de ligne de commande --user, --password ou --host, ou une chaîne de connexion (si elle est spécifiée), sont prioritaires sur les variables d’environnement.

Options en ligne de commande

Toutes les options en ligne de commande peuvent être spécifiées directement sur la ligne de commande ou définies par défaut dans le fichier de configuration.

Options générales

Option	Description	Par défaut
`-c [ -C, --config, --config-file ] <path-to-file>`	Emplacement du fichier de configuration du client, s’il ne se trouve pas dans l’un des emplacements par défaut. Voir Fichiers de configuration.	-
`--help`	Affiche un résumé de l’utilisation puis quitte. Combinez avec `--verbose` pour afficher toutes les options possibles, y compris les paramètres de requête.	-
`--history_file <path-to-file>`	Chemin vers un fichier contenant l’historique des commandes.	-
`--history_max_entries`	Nombre maximal d’entrées dans le fichier d’historique.	`1000000` (1 million)
`--prompt <prompt>`	Spécifie une invite personnalisée.	Le `display_name` du serveur
`--verbose`	Augmente le niveau de verbosité de la sortie.	-
`-V [ --version ]`	Affiche la version puis quitte.	-

Options de connexion

Option	Description	Par défaut
`--connection <name>`	Le nom des informations de connexion préconfigurées issues du fichier de configuration. Voir Identifiants de connexion.	*
`-d [ --database ] <database>`	Sélectionne la base de données utilisée par défaut pour cette connexion.	La base de données actuelle issue des paramètres du serveur (`default` par défaut)
`-h [ --host ] <host>`	Le nom d’hôte du serveur ClickHouse auquel se connecter. Il peut s’agir d’un nom d’hôte, d’une adresse IPv4 ou d’une adresse IPv6. Plusieurs hôtes peuvent être fournis à l’aide de plusieurs arguments.	`localhost`
`--jwt <value>`	Utilise un JSON Web Token (JWT) pour l’authentification. L’autorisation JWT côté serveur est disponible uniquement dans ClickHouse Cloud.	-
`--login`	Lance le flux OAuth de type device grant afin de s’authentifier via un IdP. Pour les hôtes ClickHouse Cloud, les variables OAuth sont inférées ; sinon, elles doivent être fournies avec `--oauth-url`, `--oauth-client-id` et `--oauth-audience`.	*
`--no-warnings`	Désactive l’affichage des avertissements de `system.warnings` lorsque le client se connecte au serveur.	-
`--no-server-client-version-message`	Supprime le message d’incompatibilité de version entre le serveur et le client lorsque le client se connecte au serveur.	*
`--password <password>`	Le mot de passe de l’utilisateur de la base de données. Vous pouvez également définir le mot de passe d’une connexion dans le fichier de configuration. Si vous ne spécifiez pas le mot de passe, le client vous le demandera.	-
`--port <port>`	Le port sur lequel le serveur accepte les connexions. Les ports par défaut sont 9440 (TLS) et 9000 (sans TLS). Remarque : le client utilise le protocole natif, et non HTTP(S).	`9440` si `--secure` est spécifié, `9000` sinon. Utilise toujours `9440` par défaut si le nom d’hôte se termine par `.clickhouse.cloud`. Si ni `--port` ni `--secure` ne sont spécifiés, les ports `9000` et `9440` sont sondés simultanément et celui qui répond le premier est utilisé.
`-s [ --secure ]`	Indique s’il faut utiliser TLS. Activé automatiquement lors d’une connexion au port 9440 (le port sécurisé par défaut) ou à ClickHouse Cloud, ainsi que lorsqu’aucun `--port` ni `--secure` n’est spécifié et que le port sécurisé répond le premier à la sonde — ce qui est toujours le cas pour un serveur répondant uniquement sur le port sécurisé (par exemple `play.clickhouse.com`, où le port non chiffré est protégé par un pare-feu), et peut être le cas pour un serveur écoutant sur les deux ports. Comme TLS n’a pas été demandé dans ce cas, un port sécurisé qui s’avère inutilisable (par exemple en raison d’un certificat non approuvé) ne génère pas d’erreur : le client se rabat sur le port non chiffré, auquel il se serait connecté sans le choix automatique. Spécifiez `--secure` pour exiger TLS. Vous devrez peut-être configurer vos certificats CA dans le fichier de configuration. Les paramètres de configuration disponibles sont les mêmes que pour la configuration TLS côté serveur.	Activé automatiquement lors d’une connexion au port 9440 ou à ClickHouse Cloud
`--ssh-key-file [path-to-file]`	Fichier contenant la clé privée SSH permettant de s’authentifier auprès du serveur. Le nom de fichier peut être omis : le client sélectionne le premier fichier d’identité disponible configuré pour cet hôte dans `~/.ssh/config`, puis les fichiers d’identité par défaut, tels que `~/.ssh/id_ed25519`. Pour chaque identité, la copie détenue par l’`ssh-agent` est privilégiée car elle ne nécessite pas de phrase secrète ; l’agent est sélectionné à l’aide du paramètre `IdentityAgent` correspondant, ou de `SSH_AUTH_SOCK` lorsque celui-ci n’est pas configuré.	*
`--ssh-key-passphrase <value>`	Phrase secrète de la clé privée SSH spécifiée dans `--ssh-key-file`. Si elle n’est pas spécifiée et que le fichier de clé est chiffré, la phrase secrète est demandée de manière interactive.	-
`--tls-sni-override <server name>`	Si TLS est utilisé, le nom de serveur (SNI) à transmettre lors de la négociation initiale.	L’hôte fourni via `-h` ou `--host`.
`-u [ --user ] <username>`	L’utilisateur de la base de données avec lequel se connecter.	`default`

Au lieu des options --host, --port, --user et --password, le client prend également en charge les chaînes de connexion.

Options de requête

Option	Description
`--param_<name>=<value>`	Valeur de substitution pour un paramètre d’une requête avec paramètres.
`-q [ --query ] <query>`	Requête à exécuter en mode batch. Peut être spécifiée plusieurs fois (`--query "SELECT 1" --query "SELECT 2"`) ou une seule fois avec plusieurs requêtes séparées par des points-virgules (`--query "SELECT 1; SELECT 2;"`). Dans ce dernier cas, les requêtes `INSERT` utilisant des formats autres que `VALUES` doivent être séparées par des lignes vides. Une requête unique peut aussi être spécifiée sans paramètre : `clickhouse-client "SELECT 1"` Ne peut pas être utilisée avec `--queries-file`.
`--queries-file <path-to-file>`	Chemin vers un fichier contenant des requêtes. `--queries-file` peut être spécifiée plusieurs fois, par exemple `--queries-file queries1.sql --queries-file queries2.sql`. Ne peut pas être utilisée avec `--query`.
`-m [ --multiline ]`	Si cette option est spécifiée, autorise les requêtes sur plusieurs lignes (la requête n’est pas envoyée lorsque vous appuyez sur Entrée). Les requêtes ne sont envoyées qu’une fois terminées par un point-virgule.
`--inline-insert-data`	Envoie `INSERT ... VALUES` (et les autres formats intégrés) tels quels dans le texte de la requête au lieu de convertir les données en blocs au format natif. Le serveur analyse lui-même les données intégrées, ce qui évite l’aller-retour nécessaire pour renvoyer au client la structure de la table et les valeurs par défaut des colonnes. Cela peut améliorer les performances lors de nombreuses petites insertions via le protocole natif. Définit automatiquement `send_table_structure_on_insert_with_inline_data` sur `0`. Ne peut pas être combiné avec des données intégrées et des données externes (depuis stdin ou `INFILE`).

Paramètres de requête

Les paramètres de requête peuvent être définis à l’aide d’options de ligne de commande dans le client, par exemple :

$ clickhouse-client --max_threads 1

Voir Paramètres pour la liste des paramètres.

Options de formatage

Option	Description	Valeur par défaut
`-f [ --format ] <format>`	Utilisez le format spécifié pour afficher le résultat. Consultez Formats des données d’entrée et de sortie pour obtenir la liste des formats pris en charge.	`TabSeparated`
`--pager <command>`	Redirigez toute la sortie vers cette commande. Généralement `less` (par ex. `less -S` pour afficher des jeux de résultats très larges) ou une commande similaire.	-
`-E [ --vertical ]`	Utilisez le format Vertical pour afficher le résultat. Cela équivaut à `–-format Vertical`. Dans ce format, chaque valeur est affichée sur une ligne distincte, ce qui est utile pour afficher des tables avec de nombreuses colonnes.	-
`--echo [ <bool> ]`	Affiche chaque requête avant son exécution. Accepte une valeur booléenne facultative.	`true` en mode interactif, `false` en mode non interactif (batch)
`--echo-formatted [ <bool> ]`	Met en forme les requêtes affichées. Accepte une valeur booléenne facultative.	`true` en mode interactif, `false` en mode non interactif (batch)
`--echo-query-id [ <bool> ]`	Affiche l’identifiant de requête avant son exécution. Accepte une valeur booléenne facultative.	`true` en mode interactif, `false` en mode non interactif (batch)
`--echo-query-separator <string>`	Affiche ce séparateur avant la requête affichée et mise en forme (nécessite `--echo-formatted`), afin de distinguer plus facilement la requête saisie de son écho remis en forme.	Vide (désactivé)
`--highlight [ --hilite ] <bool>`	Active ou désactive la coloration syntaxique de l’invite de commande et des requêtes affichées.	`true`
`--hints <bool>`	Affiche pendant la saisie des indications d’autocomplétion (texte « fantôme » intégré) correspondant à la meilleure suggestion lorsque le curseur se trouve à la fin de l’entrée. Parcourez les indications avec Haut/Bas (ou Ctrl-Haut/Ctrl-Bas) ; acceptez l’indication intégrée avec Tab ou Droite ; `Enter` n’accepte une indication qu’après sa sélection explicite et, sinon, exécute la requête ; `Tab` ouvre également la liste classique de complétion. Nécessite `--highlight` (les indications ont besoin de couleur). Les indications de suggestion nécessitent également le mécanisme de suggestion, ainsi `--disable_suggestion` les désactive ; les commandes `/` du client constituent une liste statique et restent indiquées tant que `--hints` et `--highlight` sont activés. `Tab` complète les commandes `/` même lorsque les indications sont désactivées.	`true`

Détails d’exécution

Option	Description	Par défaut
`--chime [N]`	Écrit le caractère de contrôle `BEL` sur `stderr` lorsqu’une requête se termine (qu’elle réussisse ou échoue) après avoir duré au moins `N` secondes. N’est émis que lorsque `stderr` est connecté à un terminal (TTY) ; la redirection de `stderr` (par ex. `2>err.log`) le supprime, tandis que la redirection de `stdout` (par ex. `> result.tsv`) ne le supprime pas. Passer `--chime` sans valeur utilise le seuil par défaut. Définissez `--chime 0` pour le désactiver.	`5` secondes
`--enable-progress-table-toggle`	Active l’affichage/masquage du tableau de progression en appuyant sur la touche de contrôle (Espace). S’applique uniquement en mode interactif lorsque l’affichage du tableau de progression est activé.	`activé`
`--hardware-utilization`	Affiche les informations d’utilisation du matériel dans la barre de progression.	-
`--memory-usage`	Si spécifié, affiche l’utilisation de la mémoire sur `stderr` en mode non interactif. Valeurs possibles : • `none` - n’affiche pas l’utilisation de la mémoire • `default` - affiche le nombre d’octets • `readable` - affiche l’utilisation de la mémoire dans un format lisible par l’humain	-
`--print-profile-events`	Affiche les paquets `ProfileEvents`.	-
`--progress`	Affiche la progression de l’exécution de la requête. Valeurs possibles : • `tty\|on\|1\|true\|yes` - sortie vers le terminal en mode interactif • `err` - sortie vers `stderr` en mode non interactif • `off\|0\|false\|no` - désactive l’affichage de la progression	`tty` en mode interactif, `off` en mode non interactif (`batch`)
`--progress-table`	Affiche un tableau de progression avec des métriques mises à jour pendant l’exécution de la requête. Valeurs possibles : • `tty\|on\|1\|true\|yes` - sortie vers le terminal en mode interactif • `err` - sortie vers `stderr` en mode non interactif • `off\|0\|false\|no` - désactive le tableau de progression	`tty` en mode interactif, `off` en mode non interactif (`batch`)
`--stacktrace`	Affiche les stack traces des exceptions.	-
`-t [ --time ]`	Affiche le temps d’exécution de la requête sur `stderr` en mode non interactif (pour les benchmarks).	-

​Installation

​Exécuter

​Se connecter à ClickHouse Cloud

​Stocker des connexions dans un fichier de configuration

​Mode interactif

​Utilisation du mode interactif

​Obtenir de l’aide

​Commandes

​Informations sur le traitement des requêtes

​Aliases

​Raccourcis clavier

​Mode batch

​Utiliser le mode batch

​Insertion d’un fichier CSV dans un service ClickHouse distant

​Exemples d’insertion de données en ligne de commande

​Requêtes paramétrées

​Syntaxe de la requête

​Exemples

​Génération SQL assistée par IA

​Utilisation

​Exemple

​Configuration

​Bascule de secours via l’environnement

​Fichier de configuration

​Paramètres

​Fonctionnement

​Limitations

​Sécurité

​Chaîne de connexion

​Utilisation

​Remarques

​Exemples

​Format de l’identifiant de requête

​Fichiers de configuration

​Options des variables d’environnement

​Options en ligne de commande

​Options générales

​Options de connexion

​Options de requête

​Paramètres de requête

​Options de formatage

​Détails d’exécution

Installation

Exécuter

Se connecter à ClickHouse Cloud

Stocker des connexions dans un fichier de configuration

Mode interactif

Utilisation du mode interactif

Obtenir de l’aide

Commandes

Informations sur le traitement des requêtes

Aliases

Raccourcis clavier

Mode batch

Utiliser le mode batch

Insertion d’un fichier CSV dans un service ClickHouse distant

Exemples d’insertion de données en ligne de commande

Requêtes paramétrées

Syntaxe de la requête

Exemples

Génération SQL assistée par IA

Utilisation

Exemple

Configuration

Bascule de secours via l’environnement

Fichier de configuration

Paramètres

Fonctionnement

Limitations

Sécurité

Chaîne de connexion

Utilisation

Remarques

Exemples

Format de l’identifiant de requête

Fichiers de configuration

Options des variables d’environnement

Options en ligne de commande

Options générales

Options de connexion

Options de requête

Paramètres de requête

Options de formatage

Détails d’exécution