clickhouse-local

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, что и сервер ClickHouse и clickhouse-client. Проще всего скачать последнюю версию с помощью следующей команды:

curl https://clickhouse.com/ | sh

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')"

Данные не обязательно должны быть локальными: вместо имени файла можно использовать URL, а схема URL выбирает соответствующий движок таблицы (http:// и https:// считываются как функция url, s3:// — как функция s3, file:// — как функция 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)

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

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

Monopoly Junior Board Game    5

Если у вас есть файл в 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 млн строк:

2772030

Всегда полезно посмотреть, какую схему 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-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"

Аргументы:

• -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> ] — выводить каждый запрос перед выполнением. Принимает необязательное булево значение. По умолчанию включен в интерактивный режим и отключен в batch mode. Note: поскольку --echo теперь принимает необязательное значение, позиционный запрос, указанный сразу после --echo без значения, будет воспринят как его значение; вместо этого используйте --echo --query "...", --echo -q "...", --echo=false или перенаправленный stdin.
• --echo-formatted [ <bool> ] — форматировать выводимые запросы. Принимает необязательное булево значение. По умолчанию включен в интерактивный режим и отключен в batch mode.
• --echo-query-id [ <bool> ] — выводить query_id перед выполнением. Принимает необязательное булево значение. По умолчанию включен в интерактивный режим и отключен в batch mode.
• --echo-query-separator <string> — выводить этот разделитель перед форматированным выводимым запросом (требуется --echo-formatted), чтобы было проще отличить введённый запрос от его переформатированного вывода. По умолчанию пустой (отключено).
• --highlight, --hilite <bool> — включать или отключать подсветку синтаксиса в командной строке и для выводимых запросов. По умолчанию включена. Подсветка применяется только при выводе в терминал.
• --hints <bool> — показывать подсказки автодополнения по мере ввода (встроенный "призрачный" текст) для наиболее подходящего варианта, когда курсор находится в конце строки ввода. Перемещаться по подсказкам можно с помощью Up/Down (или Ctrl-Up/Ctrl-Down); принять встроенную подсказку — с помощью Tab или Right; Enter принимает подсказку только после того, как она была явно выбрана, в противном случае выполняет запрос; Tab также открывает классический список вариантов. Требует --highlight (подсказкам нужен цвет). Подсказкам предложений также нужен механизм предложений, поэтому --disable_suggestion отключает их; /-команды клиента представляют собой статический список и остаются доступными в подсказках, пока включены --hints и --highlight. Tab дополняет /-команды, даже если подсказки отключены. По умолчанию включено.
• --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.

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

Её можно запустить в интерактивном режиме так:

ClickHouse local version 26.3.1.1.

:) ls

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

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

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

./clickhouse-local -q ls

file1.csv
file2.json
file3.xml

Очищает экран терминала (аналогично команде 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

$ 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

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

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

$ 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-пользователя:

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

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 можно превратить в легковесный сервер, принимающий TCP-соединения (собственный протокол) и HTTP-соединения. Это полезно, если вы хотите предоставить другим инструментам или приложениям ClickHouse доступ к базам данных и таблицам запущенного экземпляра clickhouse-local. Обратите внимание: для каждого входящего соединения создается собственный сеанс, поэтому временные таблицы и настройки уровня сеанса интерактивного сеанса clickhouse-local не видны внешним соединениям.

Используйте SYSTEM START LISTEN, чтобы открыть слушатель, и SYSTEM STOP LISTEN, чтобы закрыть его:

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

Параметры --listen_host, --tcp_port и --http_port задают адрес привязки и порты. По умолчанию используются порты 9000 для TCP и 8123 для HTTP.

HTTP-слушатель отвечает на CORS preflight-запросы теми же разрешающими заголовками, что и конфигурация clickhouse-server по умолчанию, поэтому веб-приложение может выполнять к нему запросы из браузера без дополнительной настройки, в том числе веб-интерфейс, открытый по URL file://, источник которого — null. Чтобы ограничить это, определите собственный раздел http_options_response в файле конфигурации, переданном с помощью --config-file; он полностью заменит значения по умолчанию.

• Извлечение, преобразование и запрос данных в локальных файлах с помощью clickhouse-local
• Загрузка данных в ClickHouse — часть 1
• Исследование огромных реальных наборов данных: более 100 лет метеонаблюдений в ClickHouse
• Блог: Извлечение, преобразование и запрос данных в локальных файлах с помощью clickhouse-local