clickhouse-local - ClickHouse Documentation

Когда использовать clickhouse-local, а когда ClickHouse

clickhouse-local — это простая в использовании версия ClickHouse, которая идеально подходит разработчикам, которым нужно быстро обрабатывать локальные и удалённые файлы с помощью SQL без установки полноценного сервера базы данных. С clickhouse-local разработчики могут выполнять SQL-команды (напрямую используя ClickHouse SQL) из командной строки, что даёт простой и эффективный способ получить доступ к возможностям ClickHouse без полной установки ClickHouse. Одно из главных преимуществ clickhouse-local в том, что он уже входит в состав clickhouse-client. Это означает, что разработчики могут быстро начать работу с clickhouse-local без сложной установки. Хотя clickhouse-local — отличный инструмент для разработки, тестирования и обработки файлов, он не подходит для обслуживания конечных пользователей или приложений. В таких случаях рекомендуется использовать ClickHouse с открытым исходным кодом. ClickHouse — это мощная OLAP-база данных, предназначенная для работы с крупномасштабными аналитическими рабочими нагрузками. Она обеспечивает быструю и эффективную обработку сложных запросов на больших наборах данных, что делает её идеальным выбором для production-сред, где критически важна высокая производительность. Кроме того, ClickHouse предлагает широкий набор возможностей, таких как репликация, шардирование и Высокая доступность, которые необходимы для масштабирования при работе с большими наборами данных и обслуживании приложений. Если вам нужно работать с более крупными наборами данных или обслуживать конечных пользователей либо приложения, мы рекомендуем использовать ClickHouse с открытым исходным кодом вместо clickhouse-local. Ознакомьтесь с документацией ниже, где приведены примеры использования clickhouse-local, например запросы к локальному файлу или чтение файла Parquet в S3.

Скачайте clickhouse-local

clickhouse-local использует тот же бинарный файл clickhouse, что и сервер ClickHouse и clickhouse-client. Проще всего скачать последнюю версию с помощью следующей команды:

curl https://clickhouse.com/ | sh

Загруженный вами бинарный файл может запускать самые разные инструменты и утилиты ClickHouse. Если вы хотите использовать ClickHouse как сервер базы данных, ознакомьтесь с руководством Быстрый старт.

Выполнение SQL-запросов к данным в файле

clickhouse-local часто используют для выполнения разовых запросов к файлам, когда данные не нужно вставлять в таблицу. clickhouse-local может считывать данные из файла во временную таблицу и выполнять ваши SQL-запросы. Если файл находится на той же машине, что и clickhouse-local, можно просто указать файл для загрузки. Следующий файл reviews.tsv содержит выборку отзывов на товары Amazon:

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

Эта команда — сокращённый вариант:

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

ClickHouse определяет по расширению имени файла, что в нём используется формат с табуляцией в качестве разделителя. Если вам нужно явно указать format, просто добавьте один из многих входных форматов в ClickHouse:

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

Табличная функция file создаёт таблицу, и с помощью DESCRIBE можно посмотреть автоматически определённую схему:

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

В имени файла можно использовать глоб-шаблоны (см. глоб-подстановки).Примеры:

./clickhouse local -q "SELECT * FROM 'reviews*.jsonl'"
./clickhouse local -q "SELECT * FROM 'review_?.csv'"
./clickhouse local -q "SELECT * FROM 'review_{1..3}.csv'"

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)

Найдём товар с самым высоким рейтингом:

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

Monopoly Junior Board Game    5

Запрос данных из файла Parquet в AWS S3

Если у вас есть файл в S3, используйте clickhouse-local и табличную функцию s3, чтобы выполнить запрос к файлу напрямую (без вставки данных в таблицу ClickHouse). У нас есть файл house_0.parquet в публичном бакете, содержащий цены на дома, проданные в Соединённом Королевстве. Давайте посмотрим, сколько в нём строк:

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

Файл содержит 2,7 млн строк:

Всегда полезно посмотреть, какую схему ClickHouse выводит на основе файла:

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

Давайте посмотрим, какие районы самые дорогие:

./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    ██████████████▋

Когда будете готовы загрузить свои файлы в ClickHouse, запустите сервер ClickHouse и вставьте результаты табличных функций file и s3 в таблицу MergeTree. Подробнее см. в разделе Быстрый старт.

Преобразование форматов

Для преобразования данных из одного формата в другой можно использовать clickhouse-local. Пример:

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

Форматы автоматически определяются по расширениям файлов:

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

Для краткости это можно записать с помощью аргумента --copy:

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

Использование

По умолчанию clickhouse-local имеет доступ к данным сервер ClickHouse на том же хосте и не зависит от конфигурации сервера. Он также поддерживает загрузку конфигурации сервера с помощью аргумента --config-file. Для временных данных по умолчанию создается уникальный временный каталог. Базовое использование (Linux):

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

Базовое использование (Mac):

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

clickhouse-local также поддерживается в Windows через WSL2.

Аргументы:

-S, --structure — структура таблицы для входных данных.
--input-format — входной формат, по умолчанию TSV.
-F, --file — путь к данным, по умолчанию stdin.
-q, --query — запросы для выполнения, где ; используется как разделитель. --query можно указать несколько раз, например: --query "SELECT 1" --query "SELECT 2". Нельзя использовать одновременно с --queries-file.
--queries-file - путь к файлу с запросами для выполнения. --queries-file можно указать несколько раз, например: --query queries1.sql --query queries2.sql. Нельзя использовать одновременно с --query.
--multiquery, -n – Если указан, после параметра --query можно перечислить несколько запросов, разделённых точкой с запятой. Для удобства также можно не указывать --query и передать запросы сразу после --multiquery.
-N, --table — имя таблицы, в которую помещаются выходные данные, по умолчанию table.
-f, --format, --output-format — выходной формат, по умолчанию TSV.
-d, --database — база данных по умолчанию, _local.
--stacktrace — выводить ли отладочную информацию в случае исключения.
--echo [ <bool> ] — выводить каждый запрос перед выполнением. Принимает необязательное булево значение. По умолчанию включен в interactive mode и отключен в batch mode. Note: поскольку --echo теперь принимает необязательное значение, позиционный запрос, указанный сразу после --echo без значения, будет воспринят как его значение; вместо этого используйте --echo --query "...", --echo -q "...", --echo=false или перенаправленный stdin.
--echo-formatted [ <bool> ] — форматировать выводимые запросы. Принимает необязательное булево значение. По умолчанию включен в interactive mode и отключен в batch mode.
--echo-query-id [ <bool> ] — выводить query_id перед выполнением. Принимает необязательное булево значение. По умолчанию включен в interactive mode и отключен в batch mode.
--highlight, --hilite <bool> — включать или отключать подсветку синтаксиса в командной строке и для выводимых запросов. По умолчанию включена. Подсветка применяется только при выводе в терминал.
--verbose — более подробная информация о выполнении запроса.
--logger.console — выводить Log в консоль.
--logger.log — имя файла журнала.
--logger.level — уровень логирования.
--ignore-error — не останавливать обработку, если запрос завершился ошибкой.
-c, --config-file — путь к файлу конфигурации в том же формате, что и для сервера ClickHouse; по умолчанию конфигурация пуста.
--no-system-tables — не подключать системные таблицы.
--help — справка по аргументам для clickhouse-local.
-V, --version — вывести информацию о версии и выйти.

Кроме того, для каждой переменной конфигурации ClickHouse есть аргументы, которые чаще используются вместо --config-file.

Команды

Команда LS

Выводит список всех файлов в текущем рабочем каталоге, доступных для clickhouse-local. Её можно запустить в интерактивном режиме так:

Query

ClickHouse local version 26.3.1.1.

:) ls

SELECT _file AS file
FROM file('*', 'One')
ORDER BY file ASC

Response

┌─file────────┐
│ file1.csv   │
│ file2.json  │
│ file3.xml   │
└─────────────┘

Вы также можете выполнить это в виде запроса, используя аргумент -q:

./clickhouse-local -q ls

Response

file1.csv
file2.json
file3.xml

Команда CLEAR

Очищает экран терминала (аналогично команде clear в Linux или Ctrl+L во многих терминалах). Это действие выполняется на стороне клиента: оно не отправляется в SQL-движок. В clickhouse-local метакоманда распознаётся в интерактивном режиме, а также при вводе через -q и --queries-file (тот же клиентский путь, что и у -q, по той же логике, что и у ls), поэтому одиночный clear не вызывает ошибку UNKNOWN_IDENTIFIER. Для удалённого clickhouse-client --queries-file ничего не изменилось: содержимое файла по-прежнему выполняется только как SQL (без текстовых метакоманд). В clickhouse-client она распознаётся только в интерактивном режиме. При использовании -q или файлов с запросами clear по-прежнему разбирается как SQL, поэтому в автоматизации сохраняется прежнее поведение с ошибкой, а опечатки не превращаются в тихий no-op. Поддерживаемые формы: clear, CLEAR, /clear (необязательный завершающий ; игнорируется). Если стандартный вывод не является терминалом (например, при передаче вывода по конвейеру), метакоманда при распознавании принимается, но управляющие последовательности не выводятся. С clickhouse-local и -q:

./clickhouse-local -q clear

Примеры

Query

$ 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

Предыдущий пример аналогичен следующему:

Query

$ 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

Вам не обязательно использовать stdin или аргумент --file; можно открыть любое количество файлов с помощью табличной функции file:

Query

$ 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

Теперь давайте выведем пользователя memory для каждого Unix-пользователя:

Query

$ 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"

Response

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 │
├──────────┼──────────┤
...

​Когда использовать clickhouse-local, а когда ClickHouse

​Скачайте clickhouse-local

​Выполнение SQL-запросов к данным в файле

​Запрос данных из файла Parquet в AWS S3

​Преобразование форматов

​Использование

​Команды

​Команда LS

​Команда CLEAR

​Примеры

​Материалы по теме

Когда использовать clickhouse-local, а когда ClickHouse

Скачайте clickhouse-local

Выполнение SQL-запросов к данным в файле

Запрос данных из файла Parquet в AWS S3

Преобразование форматов

Использование

Команды

Команда LS

Команда CLEAR

Примеры

Материалы по теме