ClickHouse/docs/ru/operations/utilities/clickhouse-local.md

slug	sidebar_position	sidebar_label
/ru/operations/utilities/clickhouse-local	60	clickhouse-local

clickhouse-local

Принимает на вход данные, которые можно представить в табличном виде и выполняет над ними операции, заданные на языке запросов ClickHouse.

clickhouse-local использует движок сервера ClickHouse, т.е. поддерживает все форматы данных и движки таблиц, с которыми работает ClickHouse, при этом для выполнения операций не требуется запущенный сервер.

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

:::danger Предупреждение Мы не рекомендуем подключать серверную конфигурацию к clickhouse-local, поскольку данные можно легко повредить неосторожными действиями. :::

Для временных данных по умолчанию создается специальный каталог.

Вызов программы

Основной формат вызова:

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

Ключи команды:

• -S, --structure — структура таблицы, в которую будут помещены входящие данные.
• --input-format — формат входящих данных. По умолчанию — TSV.
• -f, --file — путь к файлу с данными. По умолчанию — stdin.
• -q, --query — запросы на выполнение. Разделитель запросов — ;.
• --queries-file - путь к файлу с запросами для выполнения. Необходимо задать либо параметр query, либо queries-file.
• -N, --table — имя таблицы, в которую будут помещены входящие данные. По умолчанию - table.
• --format, --output-format — формат выходных данных. По умолчанию — TSV.
• -d, --database — база данных по умолчанию. Если не указано, используется значение _local.
• --stacktrace — вывод отладочной информации при исключениях.
• --echo — перед выполнением запрос выводится в консоль.
• --verbose — подробный вывод при выполнении запроса.
• --logger.console — логирование действий в консоль.
• --logger.log — логирование действий в файл с указанным именем.
• --logger.level — уровень логирования.
• --ignore-error — не прекращать обработку если запрос выдал ошибку.
• -c, --config-file — путь к файлу конфигурации. По умолчанию clickhouse-local запускается с пустой конфигурацией. Конфигурационный файл имеет тот же формат, что и для сервера ClickHouse, и в нём можно использовать все конфигурационные параметры сервера. Обычно подключение конфигурации не требуется; если требуется установить отдельный параметр, то это можно сделать ключом с именем параметра.
• --no-system-tables — запуск без использования системных таблиц.
• --help — вывод справочной информации о clickhouse-local.
• -V, --version — вывод текущей версии и выход.

Примеры вызова

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

Объём оперативной памяти, занимаемой процессами, которые запустил пользователь (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 │
├──────────┼──────────┤
...

Запрос данных в файле с помощью 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')"

:::tip В имени файла разрешается использовать Шаблоны поиска.

Примеры:

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