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

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.

:)

Клиенты и серверы различных версий совместимы, однако если клиент старее сервера, то некоторые новые функции могут быть недоступны. Мы рекомендуем использовать одинаковые версии клиента и сервера. При подключении клиента к более новому серверу 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)}"

Также возможно устанавливать значения параметров, находясь внутри интерактивной сессии:

$ clickhouse-client -nq "
  SET param_parName='[1, 2]';
  SELECT {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 — запрос для выполнения, при использовании в неинтерактивном режиме. Допускается указание --query несколько раз (--query "SELECT 1;" --query "SELECT 2;"...).
• --queries-file - путь к файлу с запросами для выполнения. Необходимо указать только одну из опций: query или queries-file.
• --database, -d — выбрать текущую БД. Без указания значение берется из настроек сервера (по умолчанию — БД ‘default’).
• --multiline, -m — если указано — разрешить многострочные запросы, не отправлять запрос по нажатию Enter.
• --multiquery, -n — Если указано, то после опции --query могут быть перечислены несколько запросов, разделенных точкой с запятой. Для удобства можно также опустить --query и передавать запросы непосредственно после --multiquery.
• --format, -f — использовать указанный формат по умолчанию для вывода результата.
• --vertical, -E — если указано, использовать по умолчанию формат Vertical для вывода результата. То же самое, что –format=Vertical. В этом формате каждое значение выводится на отдельной строке, что удобно для отображения широких таблиц.
• --time, -t — если указано, в неинтерактивном режиме вывести время выполнения запроса в поток ‘stderr’.
• --stacktrace — если указано, в случае исключения, выводить также его стек-трейс.
• --config-file — имя конфигурационного файла.
• --secure — если указано, будет использован безопасный канал.
• --history_file - путь к файлу с историей команд.
• --param_<name> — значение параметра для запроса с параметрами.
• --jwt – авторизация с использованием JSON Web Token. Доступно только в ClickHouse Cloud.

Вместо параметров --host, --port, --user и --password клиент ClickHouse также поддерживает строки подключения (смотри следующий раздел).

Строка подключения

clickhouse-client также поддерживает подключение к серверу clickhouse с помощью строки подключения, аналогичной MongoDB, PostgreSQL, MySQL. Она имеет следующий синтаксис:

clickhouse:[//[user[:password]@][hosts_and_ports]][/database][?query_parameters]

Где

• user - (необязательно) - это имя пользователя,
• password - (необязательно) - Пароль пользователя. Если символ : укаказан, и пароль пуст, то клиент запросит ввести пользователя пароль.
• hosts_and_ports - (необязательно) - список хостов и необязательных портов. host[:port] [, host:[port]], ...,
• database - (необязательно) - это имя базы данных,
• query_parameters - (опционально) список пар ключ-значение param1=value1[,&param2=value2], .... Для некоторых параметров значение не требуется. Имена и значения параметров чувствительны к регистру.

Если user не указан, будут использоваться имя пользователя default. Если host не указан, будет использован хост localhost. Если port не указан, будет использоваться порт 9000. Если база данных не указана, будет использоваться база данных default.

Если имя пользователя, пароль или база данных были указаны в строке подключения, их нельзя указать с помощью --user, --password или --database (и наоборот).

Параметр host может быть либо именем хоста, либо IP-адресом. Для указания IPv6-адреса поместите его в квадратные скобки:

clickhouse://[2001:db8::1234]

URI позволяет подключаться к нескольким хостам. Строки подключения могут содержать несколько хостов. ClickHouse-client будет пытаться подключиться к этим хостам по порядку (т.е. слева направо). После установления соединения попытки подключения к оставшимся хостам не предпринимаются.

Строка подключения должна быть указана в первом аргументе clickhouse-client. Строка подключения может комбинироваться с другими параметрами командной строки кроме --host/-h и --port.

Для компонента query_parameter разрешены следующие ключи:

• secure или сокращенно s - без значения. Если параметр указан, то соединение с сервером будет осуществляться по защищенному каналу (TLS). См. secure в command-line-options.

Кодирование URI

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

Примеры

Подключиться к localhost через порт 9000 и выполнить запрос SELECT 1

clickhouse-client clickhouse://localhost:9000 --query "SELECT 1"

Подключиться к localhost, используя пользователя john с паролем secret, хост 127.0.0.1 и порт 9000

``bash clickhouse-client clickhouse://john:secret@127.0.0.1:9000

Подключиться к localhost, используя пользователя по умолчанию, хост с IPV6 адресом `[::1]` и порт `9000`.

``` bash
clickhouse-client clickhouse://[::1]:9000

Подключиться к localhost через порт 9000 в многострочном режиме.

clickhouse-client clickhouse://localhost:9000 '-m'

Подключиться к localhost через порт 9000 с пользователем default.

clickhouse-client clickhouse://default@localhost:9000

# Эквивалетно:
clickhouse-client clickhouse://localhost:9000 --user default

Подключиться к localhost через порт 9000 с базой данных my_database

clickhouse-client clickhouse://localhost:9000/my_database

# Эквивалетно:
clickhouse-client clickhouse://localhost:9000 --database my_database

Подключиться к localhost через порт 9000 с базой данных my_database, указанной в строке подключения, используя безопасным соединением при помощи короткого варианта параметра URI 's'.

clickhouse-client clickhouse://localhost/my_database?s

# Эквивалетно:
clickhouse-client clickhouse://localhost/my_database -s

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

clickhouse-client clickhouse:

Подключиться к хосту по умолчанию через порт по умолчанию, используя имя пользователя my_user без пароля.

clickhouse-client clickhouse://my_user@

# Использование пустого пароля между : и @ означает, что пользователь должен ввести пароль перед началом соединения.
clickhouse-client clickhouse://my_user:@

Подключиться к localhost, используя электронную почту, как имя пользователя. Символ @ закодирован как %40.

clickhouse-client clickhouse://some_user%40some_mail.com@localhost:9000

Подключится к одному из хостов: 192.168.1.15, 192.168.1.25.

clickhouse-client clickhouse://192.168.1.15,192.168.1.25 

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

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