Client ClickHouse

Documentation de l’interface du client en ligne de commande de ClickHouse

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). 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;

​

Informations sur le traitement des requêtes

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

1. 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.
2. La requête mise en forme après l’analyse, à des fins de débogage.
3. Le résultat dans le format spécifié.
4. 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
• \c <DATABASE> - USE DATABASE
• . - répéter la dernière requête

​

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 :

1. Explorer automatiquement le schéma de votre base de données
2. Générer une requête SQL adaptée en fonction des tables et des colonnes détectées
3. 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 :

1. Vérifie d’abord la variable d’environnement OPENAI_API_KEY
2. Si elle n’est pas trouvée, vérifie la variable d’environnement ANTHROPIC_API_KEY
3. 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

<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 d’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 */}
        <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>

YAML

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 d’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: 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 (par défaut : 0.0)
• 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 :

1. 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

2. 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

3. 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

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

YAML

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.
-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. 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.	-
--ssh-key-passphrase <value>	Phrase secrète de la clé privée SSH spécifiée dans --ssh-key-file.	-
--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’ID de la requête avant son exécution. Accepte une valeur booléenne facultative.	true en mode interactif, false en mode non interactif (batch)
--highlight [ --hilite ] <bool>	Active ou désactive la coloration syntaxique de l’invite de commande et des requêtes affiché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).	-