Клиент 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. Выберите сервис, к которому хотите подключиться, и нажмите Подключиться:

Выберите Нативное, и данные будут показаны с примером команды 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 - ПОКАЗАТЬ БАЗЫ ДАННЫХ
• \d - ПОКАЗАТЬ ТАБЛИЦЫ
• \c <DATABASE> - ИСПОЛЬЗОВАТЬ БАЗУ ДАННЫХ
• . - повторить последний запрос

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

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

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

подсказка

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

iTerm2: Перейдите в Preferences -> Profile -> Keys -> Левый клавиша 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.

Следующие ключи разрешены для query_parameters:

• 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 с использованием электронной почты в качестве имени пользователя. Символ @ закодирован в процентном формате как %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 Token (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

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

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

--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 в не интерактивном режиме (для бенчмарков).