Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

clickhouse-local

View as MarkdownEdit this pageReport an issueSet up docs MCP

Quand utiliser clickhouse-local plutôt que ClickHouse

clickhouse-local est une version de ClickHouse facile à utiliser, idéale pour les développeurs qui ont besoin d’effectuer rapidement des traitements sur des fichiers locaux et distants avec SQL, sans devoir installer un serveur de base de données complet. Avec clickhouse-local, les développeurs peuvent exécuter des commandes SQL (en utilisant directement le dialecte SQL de ClickHouse) depuis la ligne de commande, ce qui constitue un moyen simple et efficace d’accéder aux fonctionnalités de ClickHouse sans avoir à effectuer une installation complète. L’un des principaux avantages de clickhouse-local est qu’il est déjà inclus lors de l’installation de clickhouse-client. Les développeurs peuvent donc commencer à utiliser clickhouse-local rapidement, sans passer par un processus d’installation complexe.

Bien que clickhouse-local soit un excellent outil pour le développement, les tests et le traitement de fichiers, il n’est pas adapté aux utilisateurs finaux ni aux applications. Dans ces cas, il est recommandé d’utiliser ClickHouse open-source. ClickHouse est une puissante base de données OLAP conçue pour prendre en charge des charges de travail analytiques à grande échelle. Elle permet de traiter rapidement et efficacement des requêtes complexes sur de grands jeux de données, ce qui en fait une solution idéale pour les environnements de production où les hautes performances sont essentielles. De plus, ClickHouse offre un large éventail de fonctionnalités telles que la réplication, le sharding et la haute disponibilité, indispensables pour passer à l’échelle, gérer de grands jeux de données et servir des applications. Si vous devez traiter des jeux de données plus volumineux ou servir des utilisateurs finaux ou des applications, nous vous recommandons d’utiliser ClickHouse open-source plutôt que clickhouse-local.

Veuillez consulter la documentation ci-dessous, qui présente des exemples de cas d’usage de clickhouse-local, comme interroger un fichier local ou lire un fichier Parquet dans S3.

Télécharger clickhouse-local

clickhouse-local s’exécute avec le même binaire clickhouse que celui utilisé pour le serveur ClickHouse et clickhouse-client. Le moyen le plus simple de télécharger la dernière version consiste à utiliser la commande suivante :

curl https://clickhouse.com/ | sh

Interroger des données dans un fichier avec SQL

Une utilisation courante de clickhouse-local consiste à exécuter des requêtes ad hoc sur des fichiers, sans avoir à insérer les données dans une table. clickhouse-local peut lire les données d'un fichier dans une table temporaire et exécuter votre SQL.

Si le fichier se trouve sur la même machine que clickhouse-local, vous pouvez simplement indiquer le fichier à charger. Le fichier reviews.tsv suivant contient un échantillon d'avis sur des produits Amazon :

./clickhouse local -q "SELECT * FROM 'reviews.tsv'"

Cette commande est un raccourci pour :

./clickhouse local -q "SELECT * FROM file('reviews.tsv')"

ClickHouse sait que le fichier utilise un format à valeurs séparées par des tabulations grâce à l’extension du nom de fichier. Si vous devez spécifier explicitement le format, ajoutez simplement l’un des nombreux formats d’entrée de ClickHouse :

./clickhouse local -q "SELECT * FROM file('reviews.tsv', 'TabSeparated')"

La fonction de table file crée une table, et vous pouvez utiliser DESCRIBE pour voir le schéma inféré :

./clickhouse local -q "DESCRIBE file('reviews.tsv')"

Les données ne doivent pas nécessairement être locales : vous pouvez utiliser une URL à la place d’un nom de fichier, et son schéma sélectionne le moteur de table correspondant (http:// et https:// sont lus comme la fonction url, s3:// comme la fonction s3, file:// comme la fonction file) :

./clickhouse local -q "SELECT * FROM 'https://datasets-documentation.s3.eu-west-3.amazonaws.com/aapl_stock.csv' LIMIT 3"
./clickhouse local -q "SELECT count() FROM 's3://clickhouse-public-datasets/hits_compatible/athena_partitioned/hits_1.parquet'"
marketplace    Nullable(String)
customer_id    Nullable(Int64)
review_id    Nullable(String)
product_id    Nullable(String)
product_parent    Nullable(Int64)
product_title    Nullable(String)
product_category    Nullable(String)
star_rating    Nullable(Int64)
helpful_votes    Nullable(Int64)
total_votes    Nullable(Int64)
vine    Nullable(String)
verified_purchase    Nullable(String)
review_headline    Nullable(String)
review_body    Nullable(String)
review_date    Nullable(Date)

Trouvons le produit le mieux noté :

./clickhouse local -q "SELECT
    argMax(product_title,star_rating),
    max(star_rating)
FROM file('reviews.tsv')"
Monopoly Junior Board Game    5

Interroger les données d’un fichier Parquet dans AWS S3

Si vous avez un fichier dans S3, utilisez clickhouse-local et la fonction de table s3 pour interroger directement le fichier (sans insérer les données dans une table ClickHouse). Nous avons un fichier nommé house_0.parquet dans un bucket public qui contient les prix des biens immobiliers vendus au Royaume-Uni. Voyons combien de lignes il contient :

./clickhouse local -q "
SELECT count()
FROM s3('https://datasets-documentation.s3.eu-west-3.amazonaws.com/house_parquet/house_0.parquet')"

Le fichier contient 2,7 M de lignes :

2772030

Il est toujours utile de voir le schéma inféré que ClickHouse déduit du fichier :

./clickhouse local -q "DESCRIBE s3('https://datasets-documentation.s3.eu-west-3.amazonaws.com/house_parquet/house_0.parquet')"
price    Nullable(Int64)
date    Nullable(UInt16)
postcode1    Nullable(String)
postcode2    Nullable(String)
type    Nullable(String)
is_new    Nullable(UInt8)
duration    Nullable(String)
addr1    Nullable(String)
addr2    Nullable(String)
street    Nullable(String)
locality    Nullable(String)
town    Nullable(String)
district    Nullable(String)
county    Nullable(String)

Voyons quels sont les quartiers les plus chers :

./clickhouse local -q "
SELECT
    town,
    district,
    count() AS c,
    round(avg(price)) AS price,
    bar(price, 0, 5000000, 100)
FROM s3('https://datasets-documentation.s3.eu-west-3.amazonaws.com/house_parquet/house_0.parquet')
GROUP BY
    town,
    district
HAVING c >= 100
ORDER BY price DESC
LIMIT 10"
LONDON    CITY OF LONDON    886    2271305    █████████████████████████████████████████████▍
LEATHERHEAD    ELMBRIDGE    206    1176680    ███████████████████████▌
LONDON    CITY OF WESTMINSTER    12577    1108221    ██████████████████████▏
LONDON    KENSINGTON AND CHELSEA    8728    1094496    █████████████████████▉
HYTHE    FOLKESTONE AND HYTHE    130    1023980    ████████████████████▍
CHALFONT ST GILES    CHILTERN    113    835754    ████████████████▋
AMERSHAM    BUCKINGHAMSHIRE    113    799596    ███████████████▉
VIRGINIA WATER    RUNNYMEDE    356    789301    ███████████████▊
BARNET    ENFIELD    282    740514    ██████████████▊
NORTHWOOD    THREE RIVERS    184    731609    ██████████████▋

Conversion de formats

Vous pouvez utiliser clickhouse-local pour convertir des données d’un format à un autre. Exemple :

$ clickhouse-local --input-format JSONLines --output-format CSV --query "SELECT * FROM table" < data.json > data.csv

Les formats sont détectés automatiquement à partir des extensions de fichier :

$ clickhouse-local --query "SELECT * FROM table" < data.json > data.csv

Pour aller plus vite, vous pouvez l’écrire avec l’argument --copy :

$ clickhouse-local --copy < data.json > data.csv

Utilisation

Par défaut, clickhouse-local a accès aux données d’un serveur ClickHouse situé sur le même hôte et ne dépend pas de la configuration du serveur. Il prend également en charge le chargement de la configuration du serveur à l’aide de l’argument --config-file. Pour les données temporaires, un répertoire temporaire de données unique est créé par défaut.

Utilisation de base (Linux) :

$ clickhouse-local --structure "table_structure" --input-format "format_of_incoming_data" --query "query"

Utilisation de base (Mac) :

$ ./clickhouse local --structure "table_structure" --input-format "format_of_incoming_data" --query "query"

Arguments :

  • -S, --structure — structure de table des données d'entrée.
  • --input-format — format d'entrée, TSV par défaut.
  • -F, --file — chemin des données, stdin par défaut.
  • -q, --query — requêtes à exécuter, avec ; comme délimiteur. --query peut être spécifié plusieurs fois, par ex. --query "SELECT 1" --query "SELECT 2". Ne peut pas être utilisé simultanément avec --queries-file.
  • --queries-file - chemin du fichier contenant les requêtes à exécuter. --queries-file peut être spécifié plusieurs fois, par ex. --query queries1.sql --query queries2.sql. Ne peut pas être utilisé simultanément avec --query.
  • --multiquery, -n – Si cette option est spécifiée, plusieurs requêtes séparées par des points-virgules peuvent être indiquées après l'option --query. Pour plus de commodité, il est également possible d'omettre --query et de passer les requêtes directement après --multiquery.
  • -N, --table — nom de la table dans laquelle placer les données de sortie, table par défaut.
  • -f, --format, --output-format — format de sortie, TSV par défaut.
  • -d, --database — base de données par défaut, _local par défaut.
  • --stacktrace — indique s'il faut afficher les informations de débogage en cas d'exception.
  • --echo [ <bool> ] — affiche chaque requête avant son exécution. Accepte une valeur booléenne facultative. Activé par défaut en mode interactif et désactivé en mode batch. Remarque : comme --echo accepte désormais une valeur facultative, une requête positionnelle placée immédiatement après un --echo seul est interprétée comme sa valeur ; utilisez plutôt --echo --query "...", --echo -q "...", --echo=false ou stdin redirigé.
  • --echo-formatted [ <bool> ] — formate les requêtes affichées en écho. Accepte une valeur booléenne facultative. Activé par défaut en mode interactif et désactivé en mode batch.
  • --echo-query-id [ <bool> ] — affiche le query_id avant exécution. Accepte une valeur booléenne facultative. Activé par défaut en mode interactif et désactivé en mode batch.
  • --echo-query-separator <string> — affiche ce séparateur avant la requête affichée en écho et formatée (nécessite --echo-formatted), ce qui permet de distinguer plus facilement la requête saisie de sa version réaffichée après reformatage. Vide par défaut (désactivé).
  • --highlight, --hilite <bool> — active ou désactive la coloration syntaxique de l'invite de commande et des requêtes affichées en écho. Activée par défaut. La coloration n'est appliquée que lors de l'écriture dans un terminal.
  • --hints <bool> — affiche, pendant la saisie, des indications d'autocomplétion (texte « fantôme » intégré) pour la suggestion la plus pertinente lorsque le curseur se trouve à la fin de la saisie. Naviguez parmi 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 qu'elle a été explicitement sélectionnée 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 ; --disable_suggestion les désactive donc. 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. Activé par défaut.
  • --verbose — affiche plus de détails sur l'exécution des requêtes.
  • --logger.console — journalise dans la console.
  • --logger.log — nom du fichier de log.
  • --logger.level — niveau de log.
  • --ignore-error — ne pas arrêter le traitement si une requête a échoué.
  • -c, --config-file — chemin vers le fichier de configuration, au même format que pour serveur ClickHouse ; par défaut, la configuration est vide.
  • --no-system-tables — ne pas attacher les tables système.
  • --help — référence des arguments de clickhouse-local.
  • -V, --version — affiche les informations de version puis quitte.

Il existe également des arguments pour chaque variable de configuration de ClickHouse, plus couramment utilisés à la place de --config-file.

Commandes

Commande LS

Liste tous les fichiers du répertoire de travail courant accessibles à clickhouse-local.

Vous pouvez l’exécuter en mode interactif comme ceci :

Querysql
ClickHouse local version 26.3.1.1.

:) ls

SELECT _file AS file
FROM file('*', 'One')
ORDER BY file ASC
Responsetext
┌─file────────┐
│ file1.csv   │
│ file2.json  │
│ file3.xml   │
└─────────────┘

Vous pouvez également l’exécuter comme une requête à l’aide de l’argument -q :

./clickhouse-local -q ls
Responsetext
file1.csv
file2.json
file3.xml

Commande CLEAR

Efface l’écran du terminal (comme la commande clear sous Linux ou Ctrl+L dans de nombreux terminaux). Il s’agit d’une action côté client : elle n’est pas envoyée au moteur SQL.

Dans clickhouse-local, la méta-commande est reconnue en mode interactif ainsi que pour les entrées -q et --queries-file (même cheminement côté client que -q, même idée que ls), de sorte qu’un clear seul ne produit pas d’erreur UNKNOWN_IDENTIFIER. En revanche, pour clickhouse-client --queries-file à distance, rien ne change : le contenu du fichier est exécuté uniquement comme du SQL (sans méta-commandes au niveau du texte).

Dans clickhouse-client, elle est reconnue uniquement en mode interactif. Avec -q ou des fichiers de requêtes, clear est toujours analysé comme du SQL, de sorte que l’automatisation conserve le comportement d’erreur précédent au lieu de transformer des fautes de frappe en no-op silencieux.

Formes prises en charge : clear, CLEAR, /clear (un ; final facultatif est ignoré). Si la sortie standard n’est pas un terminal (par exemple, en redirigeant la sortie), la méta-commande est acceptée lorsqu’elle est reconnue, mais n’émet pas de séquences de contrôle.

Avec clickhouse-local et -q :

./clickhouse-local -q clear

Exemples

Querybash
$ echo -e "1,2\n3,4" | clickhouse-local --structure "a Int64, b Int64" \
    --input-format "CSV" --query "SELECT * FROM table"
Read 2 rows, 32.00 B in 0.000 sec., 5182 rows/sec., 80.97 KiB/sec.
1   2
3   4

L’exemple précédent est le même que :

Querybash
$ echo -e "1,2\n3,4" | clickhouse-local -n --query "
    CREATE TABLE table (a Int64, b Int64) ENGINE = File(CSV, stdin);
    SELECT a, b FROM table;
    DROP TABLE table;"
Read 2 rows, 32.00 B in 0.000 sec., 4987 rows/sec., 77.93 KiB/sec.
1   2
3   4

Vous n'avez pas besoin d'utiliser stdin ni l'argument --file, et vous pouvez ouvrir autant de fichiers que vous le souhaitez à l'aide de la fonction de table file :

Querybash
$ echo 1 | tee 1.tsv
1

$ echo 2 | tee 2.tsv
2

$ clickhouse-local --query "
    select * from file('1.tsv', TSV, 'a int') t1
    cross join file('2.tsv', TSV, 'b int') t2"
1    2

Maintenant, affichons l’utilisateur Memory pour chaque utilisateur Unix :

Querybash
$ ps aux | tail -n +2 | awk '{ printf("%s\t%s\n", $1, $4) }' \
    | clickhouse-local --structure "user String, mem Float64" \
        --query "SELECT user, round(sum(mem), 2) as memTotal
            FROM table GROUP BY user ORDER BY memTotal DESC FORMAT Pretty"
Responsetext
Read 186 rows, 4.15 KiB in 0.035 sec., 5302 rows/sec., 118.34 KiB/sec.
┏━━━━━━━━━━┳━━━━━━━━━━┓
┃ user     ┃ memTotal ┃
┡━━━━━━━━━━╇━━━━━━━━━━┩
│ bayonet  │    113.5 │
├──────────┼──────────┤
│ root     │      8.8 │
├──────────┼──────────┤
...

Démarrer les écouteurs TCP et HTTP

clickhouse-local peut être utilisé comme un serveur léger qui accepte les connexions TCP (protocole natif) et HTTP. C'est utile si vous souhaitez permettre à d'autres outils ou applications ClickHouse d'accéder aux bases de données et aux tables d'une instance clickhouse-local active. Notez que chaque connexion entrante dispose de sa propre session : les tables temporaires et les paramètres de session de la session interactive clickhouse-local ne sont pas visibles depuis les connexions externes.

Utilisez SYSTEM START LISTEN pour ouvrir un écouteur et SYSTEM STOP LISTEN pour le fermer :

clickhouse-local \
    --listen_host 127.0.0.1 \
    --tcp_port 9000 \
    --http_port 8123 \
    --query "
        SYSTEM START LISTEN TCP;
        SYSTEM START LISTEN HTTP;
        SELECT * FROM url('http://127.0.0.1:8123/?query=SELECT+42', LineAsString);
        SYSTEM STOP LISTEN TCP;
        SYSTEM STOP LISTEN HTTP;
    "

Les options --listen_host, --tcp_port et --http_port configurent l’adresse de liaison et les ports. Les ports par défaut sont 9000 pour TCP et 8123 pour HTTP.

L’écouteur HTTP répond aux requêtes préliminaires CORS avec les mêmes en-têtes permissifs que la configuration clickhouse-server par défaut, de sorte qu’une application web peut l’interroger depuis le navigateur sans configuration supplémentaire, y compris l’interface web ouverte depuis une URL file://, dont l’origine est null. Pour restreindre cela, définissez votre propre section http_options_response dans un fichier de configuration transmis avec --config-file ; elle remplace entièrement les valeurs par défaut.

Contenus associés

Navigation