ClickHouse/docs/ru/interfaces/cli.md

toc_priority	toc_title
17	Клиент командной строки

Клиент командной строки

ClickHouse предоставляет собственный клиент командной строки: clickhouse-client. Клиент поддерживает запуск с аргументами командной строки и с конфигурационными файлами. Подробнее читайте в разделе Конфигурирование.

Клиент устанавливается пакетом clickhouse-client и запускается командой clickhouse-client.

$ clickhouse-client
ClickHouse client version 20.13.1.5273 (official build).
Connecting to localhost:9000 as user default.
Connected to ClickHouse server version 20.13.1 revision 54442.

:)

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

ClickHouse client version is older than ClickHouse server. It may lack support for new features.

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

Клиент может быть использован в интерактивном и не интерактивном (batch) режиме. Чтобы использовать batch режим, укажите параметр query, или отправьте данные в stdin (проверяется, что stdin - не терминал), или и то, и другое. Аналогично HTTP интерфейсу, при использовании одновременно параметра query и отправке данных в stdin, запрос составляется из конкатенации параметра query, перевода строки, и данных в stdin. Это удобно для больших INSERT запросов.

Примеры использования клиента для вставки данных:

$ echo -ne "1, 'some text', '2016-08-14 00:00:00'\n2, 'some more text', '2016-08-14 00:00:01'" | clickhouse-client --database=test --query="INSERT INTO test FORMAT CSV";

$ cat <<_EOF | clickhouse-client --database=test --query="INSERT INTO test FORMAT CSV";
3, 'some text', '2016-08-14 00:00:00'
4, 'some more text', '2016-08-14 00:00:01'
_EOF

$ cat file.csv | clickhouse-client --database=test --query="INSERT INTO test FORMAT CSV";

В batch режиме в качестве формата данных по умолчанию используется формат TabSeparated. Формат может быть указан в секции FORMAT запроса.

По умолчанию, в batch режиме вы можете выполнить только один запрос. Чтобы выполнить несколько запросов из «скрипта», используйте параметр –multiquery. Это работает для всех запросов кроме INSERT. Результаты запросов выводятся подряд без дополнительных разделителей. Также, при необходимости выполнить много запросов, вы можете запускать clickhouse-client на каждый запрос. Заметим, что запуск программы clickhouse-client может занимать десятки миллисекунд.

В интерактивном режиме, вы получите командную строку, в которую можно вводить запросы.

Если не указано multiline (по умолчанию): Чтобы выполнить запрос, нажмите Enter. Точка с запятой на конце запроса не обязательна. Чтобы ввести запрос, состоящий из нескольких строк, перед переводом строки, введите символ обратного слеша: \ - тогда после нажатия Enter, вам предложат ввести следующую строку запроса.

Если указано multiline (многострочный режим): Чтобы выполнить запрос, завершите его точкой с запятой и нажмите Enter. Если в конце введённой строки не было точки с запятой, то вам предложат ввести следующую строчку запроса.

Исполняется только один запрос, поэтому всё, что введено после точки с запятой, игнорируется.

Вместо или после точки с запятой может быть указано \G. Это обозначает использование формата Vertical. В этом формате каждое значение выводится на отдельной строке, что удобно для широких таблиц. Столь необычная функциональность добавлена для совместимости с MySQL CLI.

Командная строка сделана на основе readline (и history) (или libedit, или без какой-либо библиотеки, в зависимости от сборки) - то есть, в ней работают привычные сочетания клавиш, а также присутствует история. История пишется в ~/.clickhouse-client-history.

По умолчанию, в качестве формата, используется формат PrettyCompact (красивые таблички). Вы можете изменить формат с помощью секции FORMAT запроса, или с помощью указания \G на конце запроса, с помощью аргумента командной строки --format или --vertical, или с помощью конфигурационного файла клиента.

Чтобы выйти из клиента, нажмите Ctrl+D, или наберите вместо запроса одно из: «exit», «quit», «logout», «учше», «йгше», «дщпщге», «exit;», «quit;», «logout;», «учшеж», «йгшеж», «дщпщгеж», «q», «й», «q», «Q», «:q», «й», «Й», «Жй»

При выполнении запроса, клиент показывает:

1. Прогресс выполнение запроса, который обновляется не чаще, чем 10 раз в секунду (по умолчанию). При быстрых запросах, прогресс может не успеть отобразиться.
2. Отформатированный запрос после его парсинга - для отладки.
3. Результат в заданном формате.
4. Количество строк результата, прошедшее время, а также среднюю скорость выполнения запроса.

Вы можете прервать длинный запрос, нажав Ctrl+C. При этом вам всё равно придётся чуть-чуть подождать, пока сервер остановит запрос. На некоторых стадиях выполнения, запрос невозможно прервать. Если вы не дождётесь и нажмёте Ctrl+C второй раз, то клиент будет завершён.

Клиент командной строки позволяет передать внешние данные (внешние временные таблицы) для использования запроса. Подробнее смотрите раздел «Внешние данные для обработки запроса»

Запросы с параметрами

Вы можете создать запрос с параметрами и передавать в них значения из приложения. Это позволяет избежать форматирования запросов на стороне клиента, если известно, какие из параметров запроса динамически меняются. Например:

clickhouse-client --param_parName="[1, 2]"  -q "SELECT * FROM table WHERE a = {parName:Array(UInt16)}"

Cинтаксис запроса

Отформатируйте запрос обычным способом. Представьте значения, которые вы хотите передать из параметров приложения в запрос в следующем формате:

{<name>:<data type>}

• name — идентификатор подстановки. В консольном клиенте его следует использовать как часть имени параметра --param_<name> = value.
• data type — тип данных значения. Например, структура данных (integer, ('string', integer)) может иметь тип данных Tuple(UInt8, Tuple(String, UInt8)) (целочисленный тип может быть и другим). В качестве параметра можно передать название столбца, таблицы и базы данных, в этом случае используется тип данныхIdentifier .

Пример

$ clickhouse-client --param_tuple_in_tuple="(10, ('dt', 10))" -q "SELECT * FROM table WHERE val = {tuple_in_tuple:Tuple(UInt8, Tuple(String, UInt8))}"
$ clickhouse-client --param_tbl="numbers" --param_db="system" --param_col="number" --query "SELECT {col:Identifier} FROM {db:Identifier}.{tbl:Identifier} LIMIT 10"

Конфигурирование

В clickhouse-client можно передавать различные параметры (все параметры имеют значения по умолчанию) с помощью:

• Командной строки.

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

• Конфигурационных файлов.

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

Параметры командной строки

• --host, -h — имя сервера, по умолчанию — ‘localhost’. Вы можете использовать как имя, так и IPv4 или IPv6 адрес.
• --port — порт для подключения, по умолчанию — 9000. Обратите внимание: для HTTP-интерфейса и нативного интерфейса используются разные порты.
• --user, -u — имя пользователя, по умолчанию — ‘default’.
• --password — пароль, по умолчанию — пустая строка.
• --query, -q — запрос для выполнения, при использовании в неинтерактивном режиме.
• --queries-file, -qf - путь к файлу с запросами для выполнения. Необходимо указать только одну из опций: query или queries-file.
• --database, -d — выбрать текущую БД. Без указания значение берется из настроек сервера (по умолчанию — БД ‘default’).
• --multiline, -m — если указано — разрешить многострочные запросы, не отправлять запрос по нажатию Enter.
• --multiquery, -n — если указано — разрешить выполнять несколько запросов, разделённых точкой с запятой.
• --format, -f — использовать указанный формат по умолчанию для вывода результата.
• --vertical, -E — если указано, использовать по умолчанию формат Vertical для вывода результата. То же самое, что –format=Vertical. В этом формате каждое значение выводится на отдельной строке, что удобно для отображения широких таблиц.
• --time, -t — если указано, в неинтерактивном режиме вывести время выполнения запроса в поток ‘stderr’.
• --stacktrace — если указано, в случае исключения, выводить также его стек-трейс.
• --config-file — имя конфигурационного файла.
• --secure — если указано, будет использован безопасный канал.
• --history_file - путь к файлу с историей команд.
• --param_<name> — значение параметра для запроса с параметрами.

Начиная с версии 20.5, в clickhouse-client есть автоматическая подсветка синтаксиса (включена всегда).

Конфигурационные файлы

clickhouse—client использует первый существующий файл из:

• Определенного параметром --config-file.
• ./clickhouse-client.xml
• ~/.clickhouse-client/config.xml
• /etc/clickhouse-client/config.xml

Пример конфигурационного файла:

<config>
    <user>username</user>
    <password>password</password>
    <secure>False</secure>
</config>