Перейти к основному содержанию
Перейти к основному содержанию

clickhouse-local

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

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

Хотя clickhouse-local — отличный инструмент для разработки и тестирования, а также для обработки файлов, он не подходит для обслуживания конечных пользователей или приложений. В таких сценариях рекомендуется использовать open‑source ClickHouse. ClickHouse — это мощная OLAP-база данных, предназначенная для работы с крупномасштабными аналитическими нагрузками. Она обеспечивает быстрое и эффективное выполнение сложных запросов по большим наборам данных, что делает её идеальной для производственных сред, где критична высокая производительность. Кроме того, ClickHouse предлагает широкий набор функций, таких как репликация, шардинг и высокая доступность, которые необходимы для масштабирования при работе с большими объёмами данных и обслуживания приложений. Если вам нужно обрабатывать большие наборы данных или обслуживать конечных пользователей либо приложения, мы рекомендуем использовать open‑source ClickHouse вместо clickhouse-local.

Ознакомьтесь с документацией ниже, где приведены примеры сценариев использования clickhouse-local, таких как запрос к локальному файлу или чтение parquet-файла в S3.

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

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

curl https://clickhouse.com/ | sh
Примечание

Скачанный вами бинарный файл может запускать самые разные инструменты и утилиты ClickHouse. Если вы хотите запустить ClickHouse как сервер базы данных, ознакомьтесь с разделом Quick Start.

Запрос данных из файла с помощью 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 определяет, что файл имеет табличный формат с разделителем табуляцией, по его расширению. Если вам нужно явно задать формат, просто укажите один из многочисленных форматов ввода ClickHouse:

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

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

./clickhouse local -q "DESCRIBE file('reviews.tsv')"
Совет

Можно использовать глоб-шаблоны в именах файлов (см. glob substitutions).

Примеры:

./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 млн строк:

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, запустите сервер 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 может быть указан несколько раз, например, --queries-file queries1.sql --queries-file queries2.sql. Не может использоваться одновременно с --query.
  • --multiquery, -n – если указана, после опции --query можно перечислить несколько запросов, разделённых точкой с запятой. Для удобства также можно опустить --query и передать запросы непосредственно после --multiquery.
  • -N, --table — имя таблицы, в которую помещаются выходные данные, по умолчанию table.
  • -f, --format, --output-format — выходной формат, по умолчанию TSV.
  • -d, --database — база данных по умолчанию _local.
  • --stacktrace — выводить отладочную информацию в случае исключения.
  • --echo — печатать запрос перед выполнением.
  • --verbose — более подробная информация о выполнении запроса.
  • --logger.console — вывод логов в консоль.
  • --logger.log — имя файла лога.
  • --logger.level — уровень логирования.
  • --ignore-error — не останавливать обработку, если запрос завершился ошибкой.
  • -c, --config-file — путь к конфигурационному файлу в том же формате, что и для сервера ClickHouse; по умолчанию конфигурация пустая.
  • --no-system-tables — не подключать системные таблицы.
  • --help — справка по аргументам для clickhouse-local.
  • -V, --version — вывести информацию о версии и завершить работу.

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

Примеры​

$ echo -e "1,2\n3,4" | clickhouse-local --structure "a Int64, b Int64" \
    --input-format "CSV" --query "SELECT * FROM table"
Прочитано 2 строки, 32,00 Б за 0,000 сек., 5182 строк/сек., 80,97 КиБ/сек.
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;"
Прочитано 2 строки, 32,00 Б за 0,000 сек., 4987 строк/сек., 77,93 КиБ/сек.
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

Теперь выведем объём памяти, потребляемый каждым пользователем 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"

Результат:

Прочитано 186 строк, 4,15 КиБ за 0,035 сек., 5302 строк/сек., 118,34 КиБ/сек.
┏━━━━━━━━━━┳━━━━━━━━━━┓
┃ user     ┃ memTotal ┃
┡━━━━━━━━━━╇━━━━━━━━━━┩
│ bayonet  │    113.5 │
├──────────┼──────────┤
│ root     │      8.8 │
├──────────┼──────────┤
...

Дополнительные материалы​