> ## Documentation Index > Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt > Use this file to discover all available pages before exploring further. > Руководство по использованию clickhouse-local для обработки данных без запуска сервера # clickhouse-local
## Когда использовать clickhouse-local, а когда ClickHouse
`clickhouse-local` — это простая в использовании версия ClickHouse, которая идеально подходит разработчикам, которым нужно быстро обрабатывать локальные и удалённые файлы с помощью SQL без установки полноценного сервера базы данных. С `clickhouse-local` разработчики могут выполнять SQL-команды (напрямую используя [ClickHouse SQL](/docs/ru/reference/home)) из командной строки, что даёт простой и эффективный способ получить доступ к возможностям ClickHouse без полной установки ClickHouse. Одно из главных преимуществ `clickhouse-local` в том, что он уже входит в состав [clickhouse-client](/docs/ru/concepts/features/tools-and-utilities/clickhouse-local). Это означает, что разработчики могут быстро начать работу с `clickhouse-local` без сложной установки. Хотя `clickhouse-local` — отличный инструмент для разработки, тестирования и обработки файлов, он не подходит для обслуживания конечных пользователей или приложений. В таких случаях рекомендуется использовать [ClickHouse](/docs/ru/get-started/setup/install) с открытым исходным кодом. ClickHouse — это мощная OLAP-база данных, предназначенная для работы с крупномасштабными аналитическими рабочими нагрузками. Она обеспечивает быструю и эффективную обработку сложных запросов на больших наборах данных, что делает её идеальным выбором для production-сред, где критически важна высокая производительность. Кроме того, ClickHouse предлагает широкий набор возможностей, таких как репликация, шардирование и Высокая доступность, которые необходимы для масштабирования при работе с большими наборами данных и обслуживании приложений. Если вам нужно работать с более крупными наборами данных или обслуживать конечных пользователей либо приложения, мы рекомендуем использовать ClickHouse с открытым исходным кодом вместо `clickhouse-local`. Ознакомьтесь с документацией ниже, где приведены примеры использования `clickhouse-local`, например [запросы к локальному файлу](#query_data_in_file) или [чтение файла Parquet в S3](#query-data-in-a-parquet-file-in-aws-s3).
## Скачайте clickhouse-local
`clickhouse-local` использует тот же бинарный файл `clickhouse`, что и сервер ClickHouse и `clickhouse-client`. Проще всего скачать последнюю версию с помощью следующей команды: ```bash theme={null} curl https://clickhouse.com/ | sh ``` Загруженный вами бинарный файл может запускать самые разные инструменты и утилиты ClickHouse. Если вы хотите использовать ClickHouse как сервер базы данных, ознакомьтесь с руководством [Быстрый старт](/docs/ru/get-started/setup/install).
## Выполнение SQL-запросов к данным в файле
`clickhouse-local` часто используют для выполнения разовых запросов к файлам, когда данные не нужно вставлять в таблицу. `clickhouse-local` может считывать данные из файла во временную таблицу и выполнять ваши SQL-запросы. Если файл находится на той же машине, что и `clickhouse-local`, можно просто указать файл для загрузки. Следующий файл `reviews.tsv` содержит выборку отзывов на товары Amazon: ```bash theme={null} ./clickhouse local -q "SELECT * FROM 'reviews.tsv'" ``` Эта команда — сокращённый вариант: ```bash theme={null} ./clickhouse local -q "SELECT * FROM file('reviews.tsv')" ``` ClickHouse определяет по расширению имени файла, что в нём используется формат с табуляцией в качестве разделителя. Если вам нужно явно указать format, просто добавьте один из [многих входных форматов в ClickHouse](/docs/ru/reference/formats/index): ```bash theme={null} ./clickhouse local -q "SELECT * FROM file('reviews.tsv', 'TabSeparated')" ``` Табличная функция `file` создаёт таблицу, и с помощью `DESCRIBE` можно посмотреть автоматически определённую схему: ```bash theme={null} ./clickhouse local -q "DESCRIBE file('reviews.tsv')" ``` В имени файла можно использовать глоб-шаблоны (см. [глоб-подстановки](/docs/ru/reference/functions/table-functions/file#globs-in-path)). Примеры: ```bash theme={null} ./clickhouse local -q "SELECT * FROM 'reviews*.jsonl'" ./clickhouse local -q "SELECT * FROM 'review_?.csv'" ./clickhouse local -q "SELECT * FROM 'review_{1..3}.csv'" ``` ```response theme={null} 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) ``` Найдём товар с самым высоким рейтингом: ```bash theme={null} ./clickhouse local -q "SELECT argMax(product_title,star_rating), max(star_rating) FROM file('reviews.tsv')" ``` ```response theme={null} Monopoly Junior Board Game 5 ```
## Запрос данных из файла Parquet в AWS S3
Если у вас есть файл в S3, используйте `clickhouse-local` и табличную функцию `s3`, чтобы выполнить запрос к файлу напрямую (без вставки данных в таблицу ClickHouse). У нас есть файл `house_0.parquet` в публичном бакете, содержащий цены на дома, проданные в Соединённом Королевстве. Давайте посмотрим, сколько в нём строк: ```bash theme={null} ./clickhouse local -q " SELECT count() FROM s3('https://datasets-documentation.s3.eu-west-3.amazonaws.com/house_parquet/house_0.parquet')" ``` Файл содержит 2,7 млн строк: ```response theme={null} 2772030 ``` Всегда полезно посмотреть, какую схему ClickHouse выводит на основе файла: ```bash theme={null} ./clickhouse local -q "DESCRIBE s3('https://datasets-documentation.s3.eu-west-3.amazonaws.com/house_parquet/house_0.parquet')" ``` ```response theme={null} 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) ``` Давайте посмотрим, какие районы самые дорогие: ```bash theme={null} ./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" ``` ```response theme={null} 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`. Подробнее см. в разделе [Быстрый старт](/docs/ru/get-started/setup/install).
## Преобразование форматов
Для преобразования данных из одного формата в другой можно использовать `clickhouse-local`. Пример: ```bash theme={null} $ clickhouse-local --input-format JSONLines --output-format CSV --query "SELECT * FROM table" < data.json > data.csv ``` Форматы автоматически определяются по расширениям файлов: ```bash theme={null} $ clickhouse-local --query "SELECT * FROM table" < data.json > data.csv ``` Для краткости это можно записать с помощью аргумента `--copy`: ```bash theme={null} $ clickhouse-local --copy < data.json > data.csv ```
## Использование
По умолчанию `clickhouse-local` имеет доступ к данным сервер ClickHouse на том же хосте и не зависит от конфигурации сервера. Он также поддерживает загрузку конфигурации сервера с помощью аргумента `--config-file`. Для временных данных по умолчанию создается уникальный временный каталог. Базовое использование (Linux): ```bash theme={null} $ clickhouse-local --structure "table_structure" --input-format "format_of_incoming_data" --query "query" ``` Базовое использование (Mac): ```bash theme={null} $ ./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 [ ]` — выводить каждый запрос перед выполнением. Принимает необязательное булево значение. По умолчанию включен в интерактивный режим и отключен в batch mode. Note: поскольку `--echo` теперь принимает необязательное значение, позиционный запрос, указанный сразу после `--echo` без значения, будет воспринят как его значение; вместо этого используйте `--echo --query "..."`, `--echo -q "..."`, `--echo=false` или перенаправленный `stdin`. * `--echo-formatted [ ]` — форматировать выводимые запросы. Принимает необязательное булево значение. По умолчанию включен в интерактивный режим и отключен в batch mode. * `--echo-query-id [ ]` — выводить `query_id` перед выполнением. Принимает необязательное булево значение. По умолчанию включен в интерактивный режим и отключен в batch mode. * `--echo-query-separator ` — выводить этот разделитель перед форматированным выводимым запросом (требуется `--echo-formatted`), чтобы было проще отличить введённый запрос от его переформатированного вывода. По умолчанию пустой (отключено). * `--highlight`, `--hilite` `` — включать или отключать подсветку синтаксиса в командной строке и для выводимых запросов. По умолчанию включена. Подсветка применяется только при выводе в терминал. * `--hints ` — показывать подсказки автодополнения по мере ввода (встроенный "призрачный" текст) для наиболее подходящего варианта, когда курсор находится в конце строки ввода. Перемещаться по подсказкам можно с помощью Up/Down (или Ctrl-Up/Ctrl-Down); принять встроенную подсказку — с помощью Tab или Right; `Enter` принимает подсказку только после того, как она была явно выбрана, в противном случае выполняет запрос; `Tab` также открывает классический список вариантов. Требует `--highlight` (подсказкам нужен цвет) и механизма предложений (поэтому `--disable_suggestion` тоже их отключает). По умолчанию включено. * `--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. Её можно запустить в интерактивном режиме так: ```sql title="Query" theme={null} ClickHouse local version 26.3.1.1. :) ls SELECT _file AS file FROM file('*', 'One') ORDER BY file ASC ``` ```text title="Response" theme={null} ┌─file────────┐ │ file1.csv │ │ file2.json │ │ file3.xml │ └─────────────┘ ``` Вы также можете выполнить это в виде запроса, используя аргумент `-q`: ```sh theme={null} ./clickhouse-local -q ls ``` ```text title="Response" theme={null} 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`: ```sh theme={null} ./clickhouse-local -q clear ```
## Примеры
```bash title="Query" theme={null} $ 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 ``` Предыдущий пример аналогичен следующему: ```bash title="Query" theme={null} $ 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`](/docs/ru/reference/functions/table-functions/file): ```bash title="Query" theme={null} $ 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-пользователя: ```bash title="Query" theme={null} $ 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" ``` ```text title="Response" theme={null} 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 │ ├──────────┼──────────┤ ... ```
## Запуск TCP- и HTTP-слушателей
`clickhouse-local` можно превратить в легковесный сервер, принимающий TCP-соединения (собственный протокол) и HTTP-соединения. Это полезно, если вы хотите предоставить другим инструментам или приложениям ClickHouse доступ к базам данных и таблицам запущенного экземпляра `clickhouse-local`. Обратите внимание: для каждого входящего соединения создается собственный сеанс, поэтому временные таблицы и настройки уровня сеанса интерактивного сеанса `clickhouse-local` не видны внешним соединениям. Используйте `SYSTEM START LISTEN`, чтобы открыть слушатель, и `SYSTEM STOP LISTEN`, чтобы закрыть его: ```bash theme={null} 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. **Безопасность** По умолчанию `clickhouse-local` запускается с временной конфигурацией пользователей, поэтому любой открытый им порт прослушивания не требует аутентификации. Используйте привязку к loopback-адресу (`127.0.0.1` или `::1`), если только вы явно не настроили пользователей и управление доступом, указав в параметре `users_config` пользовательский файл `users.xml` (например, через `--config-file`). Если включить прослушивание на адресе, отличном от loopback, без аутентификации, данные локального экземпляра будут доступны любому, кто сможет подключиться к выбранному порту.
## Материалы по теме
* [Извлечение, преобразование и запрос данных в локальных файлах с помощью clickhouse-local](https://clickhouse.com/blog/extracting-converting-querying-local-files-with-sql-clickhouse-local) * [Загрузка данных в ClickHouse — часть 1](https://clickhouse.com/blog/getting-data-into-clickhouse-part-1) * [Исследование огромных реальных наборов данных: более 100 лет метеонаблюдений в ClickHouse](https://clickhouse.com/blog/real-world-data-noaa-climate-data) * Блог: [Извлечение, преобразование и запрос данных в локальных файлах с помощью clickhouse-local](https://clickhouse.com/blog/extracting-converting-querying-local-files-with-sql-clickhouse-local)