mirror of
https://github.com/ClickHouse/ClickHouse.git
synced 2024-09-20 08:40:50 +00:00
315 lines
24 KiB
Markdown
315 lines
24 KiB
Markdown
---
|
||
slug: /ru/interfaces/cli
|
||
sidebar_position: 17
|
||
sidebar_label: "Клиент командной строки"
|
||
---
|
||
|
||
# Клиент командной строки {#klient-komandnoi-stroki}
|
||
|
||
ClickHouse предоставляет собственный клиент командной строки: `clickhouse-client`. Клиент поддерживает запуск с аргументами командной строки и с конфигурационными файлами. Подробнее читайте в разделе [Конфигурирование](#interfaces_cli_configuration).
|
||
|
||
Клиент [устанавливается](../getting-started/index.md) пакетом `clickhouse-client` и запускается командой `clickhouse-client`.
|
||
|
||
``` bash
|
||
$ 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.
|
||
|
||
## Использование {#cli_usage}
|
||
|
||
Клиент может быть использован в интерактивном и не интерактивном (batch) режиме.
|
||
Чтобы использовать batch режим, укажите параметр query, или отправьте данные в stdin (проверяется, что stdin - не терминал), или и то, и другое.
|
||
Аналогично HTTP интерфейсу, при использовании одновременно параметра query и отправке данных в stdin, запрос составляется из конкатенации параметра query, перевода строки и данных в stdin. Это удобно для больших `INSERT` запросов.
|
||
|
||
Примеры использования клиента для вставки данных:
|
||
|
||
``` bash
|
||
$ 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 второй раз, то клиент будет завершён.
|
||
|
||
Клиент командной строки позволяет передать внешние данные (внешние временные таблицы) для выполнения запроса. Подробнее смотрите раздел «Внешние данные для обработки запроса».
|
||
|
||
### Запросы с параметрами {#cli-queries-with-parameters}
|
||
|
||
Вы можете создать запрос с параметрами и передавать в них значения из приложения. Это позволяет избежать форматирования запросов на стороне клиента, если известно, какие из параметров запроса динамически меняются. Например:
|
||
|
||
``` bash
|
||
clickhouse-client --param_parName="[1, 2]" -q "SELECT * FROM table WHERE a = {parName:Array(UInt16)}"
|
||
```
|
||
|
||
Также возможно устанавливать значения параметров, находясь внутри интерактивной сессии:
|
||
``` bash
|
||
$ clickhouse-client -nq "
|
||
SET param_parName='[1, 2]';
|
||
SELECT {parName:Array(UInt16)}"
|
||
```
|
||
|
||
#### Синтаксис запроса {#cli-queries-with-parameters-syntax}
|
||
|
||
Отформатируйте запрос обычным способом. Представьте значения, которые вы хотите передать из параметров приложения в запрос в следующем формате:
|
||
|
||
``` sql
|
||
{<name>:<data type>}
|
||
```
|
||
|
||
- `name` — идентификатор подстановки. В консольном клиенте его следует использовать как часть имени параметра `--param_<name> = value`.
|
||
- `data type` — [тип данных](../sql-reference/data-types/index.md) значения. Например, структура данных `(integer, ('string', integer))` может иметь тип данных `Tuple(UInt8, Tuple(String, UInt8))` ([целочисленный](../sql-reference/data-types/int-uint.md) тип может быть и другим). В качестве параметра можно передать название столбца, таблицы и базы данных, в этом случае используется тип данных`Identifier` .
|
||
|
||
#### Пример {#primer}
|
||
|
||
``` bash
|
||
$ 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"
|
||
```
|
||
|
||
## Конфигурирование {#interfaces_cli_configuration}
|
||
|
||
В `clickhouse-client` можно передавать различные параметры (все параметры имеют значения по умолчанию) с помощью:
|
||
|
||
- Командной строки.
|
||
|
||
Параметры командной строки переопределяют значения по умолчанию и параметры конфигурационных файлов.
|
||
|
||
- Конфигурационных файлов.
|
||
|
||
Параметры в конфигурационных файлах переопределяют значения по умолчанию.
|
||
|
||
### Параметры командной строки {#command-line-options}
|
||
|
||
- `--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](../interfaces/formats.md#vertical) для вывода результата. То же самое, что `–format=Vertical`. В этом формате каждое значение выводится на отдельной строке, что удобно для отображения широких таблиц.
|
||
- `--time, -t` — если указано, в неинтерактивном режиме вывести время выполнения запроса в поток ‘stderr’.
|
||
- `--stacktrace` — если указано, в случае исключения, выводить также его стек-трейс.
|
||
- `--config-file` — имя конфигурационного файла.
|
||
- `--secure` — если указано, будет использован безопасный канал.
|
||
- `--history_file` - путь к файлу с историей команд.
|
||
- `--param_<name>` — значение параметра для [запроса с параметрами](#cli-queries-with-parameters).
|
||
- `--jwt` – авторизация с использованием JSON Web Token. Доступно только в ClickHouse Cloud.
|
||
|
||
Вместо параметров `--host`, `--port`, `--user` и `--password` клиент ClickHouse также поддерживает строки подключения (смотри следующий раздел).
|
||
|
||
## Строка подключения {#connection_string}
|
||
|
||
clickhouse-client также поддерживает подключение к серверу clickhouse с помощью строки подключения, аналогичной [MongoDB](https://www.mongodb.com/docs/manual/reference/connection-string/), [PostgreSQL](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING), [MySQL](https://dev.mysql.com/doc/refman/8.0/en/connecting-using-uri-or-key-value-pairs.html#connecting-using-uri). Она имеет следующий синтаксис:
|
||
|
||
```text
|
||
clickhouse:[//[user[:password]@][hosts_and_ports]][/database][?query_parameters]
|
||
```
|
||
|
||
Где
|
||
|
||
- `user` - (необязательно) - это имя пользователя,
|
||
- `password` - (необязательно) - Пароль пользователя. Если символ `:` укаказан, и пароль пуст, то клиент запросит ввести пользователя пароль.
|
||
- `hosts_and_ports` - (необязательно) - список хостов и необязательных портов. `host[:port] [, host:[port]], ...`,
|
||
- `database` - (необязательно) - это имя базы данных,
|
||
- `query_parameters` - (опционально) список пар ключ-значение `param1=value1[,¶m2=value2], ...`. Для некоторых параметров значение не требуется. Имена и значения параметров чувствительны к регистру.
|
||
|
||
Если user не указан, будут использоваться имя пользователя `default`.
|
||
Если host не указан, будет использован хост `localhost`.
|
||
Если port не указан, будет использоваться порт `9000`.
|
||
Если база данных не указана, будет использоваться база данных `default`.
|
||
|
||
Если имя пользователя, пароль или база данных были указаны в строке подключения, их нельзя указать с помощью `--user`, `--password` или `--database` (и наоборот).
|
||
|
||
Параметр host может быть либо именем хоста, либо IP-адресом. Для указания IPv6-адреса поместите его в квадратные скобки:
|
||
|
||
```text
|
||
clickhouse://[2001:db8::1234]
|
||
```
|
||
|
||
URI позволяет подключаться к нескольким хостам. Строки подключения могут содержать несколько хостов. ClickHouse-client будет пытаться подключиться к этим хостам по порядку (т.е. слева направо). После установления соединения попытки подключения к оставшимся хостам не предпринимаются.
|
||
|
||
|
||
|
||
Строка подключения должна быть указана в первом аргументе clickhouse-client. Строка подключения может комбинироваться с другими [параметрами командной строки](#command-line-options) кроме `--host/-h` и `--port`.
|
||
|
||
Для компонента `query_parameter` разрешены следующие ключи:
|
||
|
||
- `secure` или сокращенно `s` - без значения. Если параметр указан, то соединение с сервером будет осуществляться по защищенному каналу (TLS). См. `secure` в [command-line-options](#command-line-options).
|
||
|
||
### Кодирование URI {#connection_string_uri_percent_encoding}
|
||
|
||
Не US ASCII и специальные символы в имени пользователя, пароле, хостах, базе данных и параметрах запроса должны быть [закодированы](https://ru.wikipedia.org/wiki/URL#%D0%9A%D0%BE%D0%B4%D0%B8%D1%80%D0%BE%D0%B2%D0%B0%D0%BD%D0%B8%D0%B5_URL).
|
||
|
||
### Примеры {#connection_string_examples}
|
||
|
||
Подключиться к localhost через порт 9000 и выполнить запрос `SELECT 1`
|
||
|
||
``` bash
|
||
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 в многострочном режиме.
|
||
|
||
``` bash
|
||
clickhouse-client clickhouse://localhost:9000 '-m'
|
||
```
|
||
|
||
Подключиться к localhost через порт 9000 с пользователем default.
|
||
|
||
``` bash
|
||
clickhouse-client clickhouse://default@localhost:9000
|
||
|
||
# Эквивалетно:
|
||
clickhouse-client clickhouse://localhost:9000 --user default
|
||
```
|
||
|
||
Подключиться к localhost через порт 9000 с базой данных `my_database`
|
||
|
||
``` bash
|
||
clickhouse-client clickhouse://localhost:9000/my_database
|
||
|
||
# Эквивалетно:
|
||
clickhouse-client clickhouse://localhost:9000 --database my_database
|
||
```
|
||
|
||
Подключиться к localhost через порт 9000 с базой данных `my_database`, указанной в строке подключения, используя безопасным соединением при помощи короткого варианта параметра URI 's'.
|
||
|
||
``` bash
|
||
clickhouse-client clickhouse://localhost/my_database?s
|
||
|
||
# Эквивалетно:
|
||
clickhouse-client clickhouse://localhost/my_database -s
|
||
```
|
||
|
||
Подключиться к хосту по умолчанию с использованием порта по умолчанию, пользователя по умолчанию, и базы данных по умолчанию.
|
||
|
||
``` bash
|
||
clickhouse-client clickhouse:
|
||
```
|
||
|
||
Подключиться к хосту по умолчанию через порт по умолчанию, используя имя пользователя `my_user` без пароля.
|
||
|
||
``` bash
|
||
clickhouse-client clickhouse://my_user@
|
||
|
||
# Использование пустого пароля между : и @ означает, что пользователь должен ввести пароль перед началом соединения.
|
||
clickhouse-client clickhouse://my_user:@
|
||
```
|
||
|
||
Подключиться к localhost, используя электронную почту, как имя пользователя. Символ `@` закодирован как `%40`.
|
||
|
||
``` bash
|
||
clickhouse-client clickhouse://some_user%40some_mail.com@localhost:9000
|
||
```
|
||
|
||
Подключится к одному из хостов: `192.168.1.15`, `192.168.1.25`.
|
||
|
||
``` bash
|
||
clickhouse-client clickhouse://192.168.1.15,192.168.1.25
|
||
```
|
||
|
||
### Конфигурационные файлы {#configuration_files}
|
||
|
||
`clickhouse—client` использует первый существующий файл из:
|
||
|
||
- Определенного параметром `--config-file`.
|
||
- `./clickhouse-client.xml`
|
||
- `~/.clickhouse-client/config.xml`
|
||
- `/etc/clickhouse-client/config.xml`
|
||
|
||
Пример конфигурационного файла:
|
||
|
||
``` xml
|
||
<config>
|
||
<user>username</user>
|
||
<password>password</password>
|
||
<secure>False</secure>
|
||
</config>
|
||
```
|
||
|
||
### Формат ID запроса {#query-id-format}
|
||
|
||
В интерактивном режиме `clickhouse-client` показывает ID для каждого запроса. По умолчанию ID выводится в таком виде:
|
||
|
||
```sql
|
||
Query id: 927f137d-00f1-4175-8914-0dd066365e96
|
||
```
|
||
|
||
Произвольный формат ID можно задать в конфигурационном файле внутри тега `query_id_formats`. ID подставляется вместо `{query_id}` в строке формата. В теге может быть перечислено несколько строк формата.
|
||
Эта возможность может быть полезна для генерации URL, с помощью которых выполняется профилирование запросов.
|
||
|
||
**Пример**
|
||
|
||
```xml
|
||
<config>
|
||
<query_id_formats>
|
||
<speedscope>http://speedscope-host/#profileURL=qp%3Fid%3D{query_id}</speedscope>
|
||
</query_id_formats>
|
||
</config>
|
||
```
|
||
|
||
Если применить приведённую выше конфигурацию, то ID запроса будет выводиться в следующем виде:
|
||
|
||
``` text
|
||
speedscope:http://speedscope-host/#profileURL=qp%3Fid%3Dc8ecc783-e753-4b38-97f1-42cddfb98b7d
|
||
```
|