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

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

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

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

Формат ID запроса

В интерактивном режиме clickhouse-client показывает ID для каждого запроса. По умолчанию ID выводится в таком виде:

Query id: 927f137d-00f1-4175-8914-0dd066365e96

Произвольный формат ID можно задать в конфигурационном файле внутри тега query_id_formats. ID подставляется вместо {query_id} в строке формата. В теге может быть перечислено несколько строк формата. Эта возможность может быть полезна для генерации URL, с помощью которых выполняется профилирование запросов.

Пример

<config>
  <query_id_formats>
    <speedscope>http://speedscope-host/#profileURL=qp%3Fid%3D{query_id}</speedscope>
  </query_id_formats>
</config>

Если применить приведённую выше конфигурацию, то ID запроса будет выводиться в следующем виде:

speedscope:http://speedscope-host/#profileURL=qp%3Fid%3Dc8ecc783-e753-4b38-97f1-42cddfb98b7d