Клиент ClickHouse

ClickHouse предоставляет родной клиент командной строки для выполнения SQL-запросов непосредственно к серверу ClickHouse. Он поддерживает как интерактивный режим (для выполнения запросов в реальном времени), так и пакетный режим (для сценариев и автоматизации). Результаты запросов могут отображаться в терминале или экспортироваться в файл, с поддержкой всех выходных форматов ClickHouse, таких как Pretty, CSV, JSON и других.

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

Установка

Чтобы скачать ClickHouse, выполните:

Чтобы также установить его, выполните:

Смотрите Установка ClickHouse для получения дополнительных вариантов установки.

Разные версии клиента и сервера совместимы друг с другом, но некоторые функции могут не быть доступны в старых клиентах. Мы рекомендуем использовать одну и ту же версию для клиента и сервера.

Запуск

примечание

Если вы только скачали, но не установили ClickHouse, используйте ./clickhouse client вместо clickhouse-client.

Чтобы подключиться к серверу ClickHouse, выполните:

Укажите дополнительные параметры подключения по мере необходимости:

--port <port> - Порт, на котором сервер ClickHouse принимает соединения. Порт по умолчанию - 9440 (TLS) и 9000 (без TLS). Обратите внимание, что клиент ClickHouse использует родной протокол, а не HTTP(S).

-s [ --secure ] - Использовать ли TLS (обычно автоматически определяемый).

-u [ --user ] <username> - Пользователь базы данных, под которым следует подключиться. По умолчанию подключается как пользователь default.

--password <password> - Пароль пользователя базы данных. Вы также можете указать пароль для соединения в файле конфигурации. Если вы не укажете пароль, клиент попросит ввести его.

-c [ --config ] <path-to-file> - Местоположение файла конфигурации для клиента ClickHouse, если он не находится в одном из мест по умолчанию. Смотрите Файлы конфигурации.

--connection <name> - Имя предварительно заданных параметров подключения из файла конфигурации.

Для получения полного списка опций командной строки смотрите Опции командной строки.

Подключение к ClickHouse Cloud

Детали вашего сервиса ClickHouse Cloud доступны в консоли ClickHouse Cloud. Выберите сервис, к которому хотите подключиться, и нажмите Подключиться:

Выберите Native, и детали будут показаны с примером команды clickhouse-client:

Хранение подключений в файле конфигурации

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

Формат выглядит следующим образом:

Смотрите раздел о файлах конфигурации для получения дополнительной информации.

примечание

Чтобы сосредоточиться на синтаксисе запроса, в остальных примерах пропущены детали подключения (--host, --port и т.д.). Не забудьте добавить их при использовании команд.

Пакетный режим

Вместо использования клиента ClickHouse интерактивно, вы можете запустить его в пакетном режиме.

Вы можете указать одиночный запрос следующим образом:

Вы также можете использовать опцию командной строки --query:

Вы можете предоставить запрос через stdin:

Вставка данных:

Когда указана --query, любой ввод добавляется к запросу после перевода строки.

Вставка CSV-файла в удалённый сервис ClickHouse

Этот пример вставляет файл образца данных CSV, cell_towers.csv, в существующую таблицу cell_towers в базе данных default:

Больше примеров вставки данных

Заметки

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

В пакетном режиме формат данных по умолчанию формат - TabSeparated. Вы можете установить формат в аргументе FORMAT запроса.

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

Вы можете запустить клиент с параметром -m, --multiline. Чтобы ввести многострочный запрос, введите обратный слэш \ перед переводом строки. После нажатия Enter вы будете приглашены ввести следующую строку запроса. Чтобы выполнить запрос, закончите его точкой с запятой и нажмите Enter.

Клиент ClickHouse основан на replxx (аналогично readline), поэтому он использует знакомые сочетания клавиш и сохраняет историю. История записывается в ~/.clickhouse-client-history по умолчанию.

Чтобы выйти из клиента, нажмите Ctrl+D или введите одно из следующих вместо запроса: exit, quit, logout, exit;, quit;, logout;, q, Q, :q.

При обработке запроса клиент отображает:

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

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

Клиент ClickHouse позволяет передавать внешние данные (внешние временные таблицы) для выполнения запросов. Для получения дополнительной информации смотрите раздел Внешние данные для обработки запросов.

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

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

Также можно установить параметры из интерактивной сессии:

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

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

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

Примеры

Псевдонимы

• \l - SHOW DATABASES
• \d - SHOW TABLES
• \c <DATABASE> - USE DATABASE
• . - повторить последний запрос

Сочетания клавиш

• Alt (Option) + Shift + e - открыть редактор с текущим запросом. Можно указать редактор в переменной окружения EDITOR. По умолчанию используется vim.
• Alt (Option) + # - закомментировать строку.
• Ctrl + r - нечеткий поиск в истории.

Полный список всех доступных сочетаний клавиш доступен на replxx.

подсказка

Чтобы настроить правильную работу мета-клавиши (Option) на MacOS:

iTerm2: Перейдите в Настройки -> Профиль -> Клавиши -> Левая клавиша Option и нажмите Esc+

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

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

Компоненты

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

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

Компонент хоста может быть как именем хоста, так и адресом IPv4 или IPv6. Адреса IPv6 должны быть в квадратных скобках:

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

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

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

• secure или сокращенно s. Если указано, клиент подключится к серверу через защищенное соединение (TLS). Смотрите --secure в опциях командной строки.

Кодирование по процентам

Не-US ASCII, пробелы и специальные символы в user, password, hosts, database и query parameters должны быть закодированы по процентам.

Примеры

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

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

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

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

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

Подключение к localhost на порту 9000 и по умолчанию к базе данных my_database.

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

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

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

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

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

Формат идентификатора запроса

В интерактивном режиме клиент ClickHouse показывает идентификатор запроса для каждого запроса. По умолчанию идентификатор форматируется следующим образом:

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

Пример

С приведенной выше конфигурацией идентификатор запроса будет показан в следующем формате:

Файлы конфигурации

Клиент ClickHouse использует первый существующий файл из следующих:

• Файл, определенный с помощью параметра -c [ -C, --config, --config-file ].
• ./clickhouse-client.[xml|yaml|yml]
• ~/.clickhouse-client/config.[xml|yaml|yml]
• /etc/clickhouse-client/config.[xml|yaml|yml]

Смотрите пример файла конфигурации в репозитории ClickHouse: clickhouse-client.xml

Пример XML-синтаксиса:

Та же конфигурация в формате YAML:

Опции командной строки

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

Общие параметры

-c [ -C, --config, --config-file ] <path-to-file>

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

--help

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

--history_file <path-to-file>

Путь к файлу, содержащему историю команд.

--history_max_entries

Максимальное количество записей в файле истории.

Значение по умолчанию: 1000000 (1 миллион)

--prompt <prompt>

Укажите пользовательский приглашение.

Значение по умолчанию: Имя сервера display_name.

--verbose

Увеличить уровень детализации вывода.

-V [ --version ]

Вывести версию и выйти.

Параметры подключения

--connection <name>

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

-d [ --database ] <database>

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

Значение по умолчанию: текущая база данных из настроек сервера (default по умолчанию).

-h [ --host ] <host>

Имя хоста сервера ClickHouse, к которому необходимо подключиться. Может быть именем хоста или адресом IPv4 или IPv6. Несколько хостов могут быть переданы через несколько аргументов.

Значение по умолчанию: localhost

--jwt <value>

Использовать токен JSON Web (JWT) для аутентификации.

Аутентификация JWT сервера доступна только в ClickHouse Cloud.

--no-warnings

Отключить отображение предупреждений из system.warnings при подключении клиента к серверу.

--password <password>

Пароль пользователя базы данных. Вы также можете указать пароль для соединения в файле конфигурации. Если вы не укажете пароль, клиент запросит его.

--port <port>

Порт, на котором сервер принимает соединения. Порты по умолчанию - 9440 (TLS) и 9000 (без TLS).

Примечание: клиент использует родной протокол, а не HTTP(S).

Значение по умолчанию: 9440, если указано --secure, иначе 9000. Всегда по умолчанию 9440, если имя хоста оканчивается на .clickhouse.cloud.

-s [ --secure ]

Использовать ли TLS.

Включается автоматически при подключении к порту 9440 (порта по умолчанию для безопасности) или ClickHouse Cloud.

Вам может понадобиться настроить свои сертификаты CA в файле конфигурации. Доступные настройки конфигурации такие же, как для конфигурации TLS на стороне сервера.

--ssh-key-file <path-to-file>

Файл, содержащий закрытый ключ SSH для аутентификации на сервере.

--ssh-key-passphrase <value>

Пароль к закрытому ключу SSH, указанному в --ssh-key-file.

-u [ --user ] <username>

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

Значение по умолчанию: default

Вместо опций --host, --port, --user и --password клиент также поддерживает строки подключения.

Параметры запроса

--param_<name>=<value>

Значение замены для параметра запроса с параметрами.

-q [ --query ] <query>

Запрос, который необходимо выполнить в пакетном режиме. Можно указывать несколько раз (--query "SELECT 1" --query "SELECT 2") или один раз с несколькими запросами, разделенными точкой с запятой (--query "SELECT 1; SELECT 2;"). В последнем случае, запросы INSERT с форматами, отличными от VALUES, должны быть разделены пустыми строками.

Одиночный запрос также можно указать без параметра:

Нельзя использовать вместе с --queries-file.

--queries-file <path-to-file>

Путь к файлу, содержащему запросы. --queries-file можно указывать несколько раз, например, --queries-file queries1.sql --queries-file queries2.sql.

Нельзя использовать вместе с --query.

-m [ --multiline ]

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

Настройки запроса

Настройки запроса можно указывать как опции командной строки в клиенте, например:

Смотрите Настройки для списка настроек.

Опции форматирования

-f [ --format ] <format>

Используйте указанный формат для вывода результата.

Смотрите Форматы для входных и выходных данных для списка поддерживаемых форматов.

Значение по умолчанию: TabSeparated

--pager <command>

Перенаправить весь вывод в эту команду. Обычно это less (например, less -S для отображения широких наборов данных) или аналогичное.

-E [ --vertical ]

Используйте Вертикальный формат для вывода результата. Это одно и то же, что –-format Vertical. В этом формате каждое значение выводится на отдельной строке, что полезно при отображении широких таблиц.

Подробности выполнения

--enable-progress-table-toggle

Включить переключение таблицы прогресса нажатием управляющей клавиши (Space). Применимо только в интерактивном режиме с включенным выводом таблицы прогресса.

Значение по умолчанию: включено

--hardware-utilization

Вывод информации об использовании аппаратных средств в индикаторе выполнения.

--memory-usage

Если указано, выводите использование памяти в stderr в неинтерактивном режиме.

Возможные значения:

• none - не выводить использование памяти
• default - выводить количество байтов
• readable - выводить использование памяти в удобочитаемом формате

--print-profile-events

Выводите пакеты ProfileEvents.

--progress

Выводите прогресс выполнения запроса.

Возможные значения:

• tty|on|1|true|yes - вывод в терминал в интерактивном режиме
• err - вывод в stderr в неинтерактивном режиме
• off|0|false|no - отключает вывод прогресса

Значение по умолчанию: tty в интерактивном режиме, off в неинтерактивном (пакетном) режиме.

--progress-table

Выводите таблицу прогресса с изменяющимися метриками во время выполнения запроса.

Возможные значения:

• tty|on|1|true|yes - вывод в терминал в интерактивном режиме
• err - вывод в stderr в неинтерактивном режиме
• off|0|false|no - отключает вывод таблицы прогресса

Значение по умолчанию: tty в интерактивном режиме, off в неинтерактивном (пакетном) режиме.

--stacktrace

Выводите трассировки стека исключений.

-t [ --time ]

Выводите время выполнения запроса в stderr в неинтерактивном режиме (для бенчмарков).