Клиент 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 в конце запроса. В этом формате каждое значение выводится на отдельной строке, что удобно для широких таблиц.

В пакетном режиме формат данных format по умолчанию - 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 -> Left Option key и нажмите 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, используя 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 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

Включите переключение таблицы прогресса, нажав клавишу управления (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 в неинтерактивном режиме (для бенчмарков).