HTTP-интерфейс

HTTP интерфейс позволяет использовать ClickHouse на любой платформе, из любого языка программирования. У нас он используется для работы из Java и Perl, а также из shell-скриптов. В других отделах HTTP интерфейс используется из Perl, Python и Go. HTTP интерфейс более ограничен по сравнению с родным интерфейсом, но является более совместимым.

По умолчанию clickhouse-server слушает HTTP на порту 8123 (это можно изменить в конфиге). Если запросить GET / без параметров, то вернётся строка заданная с помощью настройки http_server_default_response. Значение по умолчанию «Ok.» (с переводом строки на конце).

Веб-интерфейс доступен по адресу: http://localhost:8123/play.

В скриптах проверки доступности вы можете использовать GET /ping без параметров. Если сервер доступен, всегда возвращается «Ok.» (с переводом строки на конце).

Запрос отправляется в виде URL параметра с именем query. Или как тело запроса при использовании метода POST. Или начало запроса в URL параметре query, а продолжение POST-ом (зачем это нужно, будет объяснено ниже). Размер URL ограничен 16KB, это следует учитывать при отправке больших запросов.

В случае успеха возвращается код ответа 200 и результат обработки запроса в теле ответа, в случае ошибки — код ответа 500 и текст с описанием ошибки в теле ответа.

При использовании метода GET выставляется настройка readonly. То есть, для запросов, модифицирующих данные, можно использовать только метод POST. Сам запрос при этом можно отправлять как в теле POST запроса, так и в параметре URL.

Примеры:

Как видно, curl немного неудобен тем, что надо URL-эскейпить пробелы. Хотя wget сам всё эскейпит, но его не рекомендуется использовать, так как он плохо работает по HTTP 1.1 при использовании keep-alive и Transfer-Encoding: chunked.

Если часть запроса отправляется в параметре, а часть POST запросом, то между этими двумя кусками данных ставится перевод строки. Пример (так работать не будет):

По умолчанию данные возвращаются в формате TabSeparated.

Можно указать любой другой формат с помощью секции FORMAT запроса.

Кроме того, вы можете использовать параметр URL-адреса default_format или заголовок X-ClickHouse-Format, чтобы указать формат по умолчанию, отличный от TabSeparated.

Возможность передавать данные с помощью POST нужна для запросов INSERT. В этом случае вы можете написать начало запроса в параметре URL, а вставляемые данные передать POST запросом. Вставляемыми данными может быть, например, tab-separated дамп, полученный из MySQL. Таким образом, запрос INSERT заменяет LOAD DATA LOCAL INFILE из MySQL.

Примеры

Создаём таблицу:

Используем привычный запрос INSERT для вставки данных:

Данные можно отправить отдельно от запроса:

Можно указать любой формат для данных. Формат Values - то же, что используется при записи INSERT INTO t VALUES:

Можно вставить данные из tab-separated дампа, указав соответствующий формат:

Прочитаем содержимое таблицы. Данные выводятся в произвольном порядке из-за параллельной обработки запроса:

Удаляем таблицу.

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

Сжатие

Сжатие можно использовать для уменьшения трафика по сети при передаче большого количества данных, а также для создания сразу сжатых дампов.

Вы можете использовать внутренний формат сжатия Clickhouse при передаче данных. Формат сжатых данных нестандартный, и вам придётся использовать для работы с ним специальную программу clickhouse-compressor. Она устанавливается вместе с пакетом clickhouse-client. Для повышения эффективности вставки данных можно отключить проверку контрольной суммы на стороне сервера с помощью настройки http_native_compression_disable_checksumming_on_decompress.

Если вы указали compress=1 в URL, то сервер сжимает данные, которые он отправляет. Если вы указали decompress=1 в URL, сервер распаковывает те данные, которые вы передаёте методом POST.

Также можно использовать сжатие HTTP. ClickHouse поддерживает следующие методы сжатия:

• gzip
• br
• deflate
• xz

Для отправки сжатого запроса POST добавьте заголовок Content-Encoding: compression_method. Чтобы ClickHouse сжимал ответ, разрешите сжатие настройкой enable_http_compression и добавьте заголовок Accept-Encoding: compression_method. Уровень сжатия данных для всех методов сжатия можно задать с помощью настройки http_zlib_compression_level.

Примечание

Некоторые HTTP-клиенты могут по умолчанию распаковывать данные (gzip и deflate) с сервера в фоновом режиме и вы можете получить распакованные данные, даже если правильно используете настройки сжатия.

Примеры

База данных по умолчанию

Вы можете использовать параметр URL database или заголовок X-ClickHouse-Database, чтобы указать БД по умолчанию.

По умолчанию используется БД, которая прописана в настройках сервера, как БД по умолчанию. По умолчанию, это - БД default. Также вы всегда можете указать БД через точку перед именем таблицы.

Имя пользователя и пароль могут быть указаны в одном из трёх вариантов:

1. С использованием HTTP Basic Authentication. Пример:

1. В параметрах URL user и password. Пример:

1. С использованием заголовков ‘X-ClickHouse-User’ и ‘X-ClickHouse-Key’. Пример:

Если пользователь не задан,то используется default. Если пароль не задан, то используется пустой пароль. Также в параметрах URL вы можете указать любые настройки, которые будут использованы для обработки одного запроса, или целые профили настроек. Пример:http://localhost:8123/?profile=web&max_rows_to_read=1000000000&query=SELECT+1

Подробнее смотрите в разделе Настройки.

Об остальных параметрах смотри раздел «SET».

Аналогично можно использовать ClickHouse-сессии в HTTP-протоколе. Для этого необходимо добавить к запросу GET параметр session_id. В качестве идентификатора сессии можно использовать произвольную строку. По умолчанию через 60 секунд бездействия сессия будет прервана. Можно изменить этот таймаут, изменяя настройку default_session_timeout в конфигурации сервера, или добавив к запросу GET параметр session_timeout. Статус сессии можно проверить с помощью параметра session_check=1. В рамках одной сессии одновременно может исполняться только один запрос.

Прогресс выполнения запроса можно отслеживать с помощью заголовков ответа X-ClickHouse-Progress. Для этого включите send_progress_in_http_headers. Пример последовательности заголовков:

Возможные поля заголовка:

• read_rows — количество прочитанных строк.
• read_bytes — объём прочитанных данных в байтах.
• total_rows_to_read — общее количество строк для чтения.
• written_rows — количество записанных строк.
• written_bytes — объём записанных данных в байтах.

Запущенные запросы не останавливаются автоматически при разрыве HTTP соединения. Парсинг и форматирование данных производится на стороне сервера и использование сети может быть неэффективным. Может быть передан необязательный параметр query_id - идентификатор запроса, произвольная строка. Подробнее смотрите раздел «Настройки, replace_running_query».

Может быть передан необязательный параметр quota_key - ключ квоты, произвольная строка. Подробнее смотрите раздел «Квоты».

HTTP интерфейс позволяет передать внешние данные (внешние временные таблицы) для использования запроса. Подробнее смотрите раздел «Внешние данные для обработки запроса»

Буферизация ответа

Существует возможность включить буферизацию ответа на стороне сервера. Для этого предусмотрены параметры URL buffer_size и wait_end_of_query.

buffer_size определяет количество байт результата которые будут буферизованы в памяти сервера. Если тело результата больше этого порога, то буфер будет переписан в HTTP канал, а оставшиеся данные будут отправляться в HTTP-канал напрямую.

Чтобы гарантировать буферизацию всего ответа, необходимо выставить wait_end_of_query=1. В этом случае данные, не поместившиеся в памяти, будут буферизованы во временном файле сервера.

Пример:

Буферизация позволяет избежать ситуации, когда код ответа и HTTP-заголовки были отправлены клиенту, после чего возникла ошибка выполнения запроса. В такой ситуации сообщение об ошибке записывается в конце тела ответа, и на стороне клиента ошибка может быть обнаружена только на этапе парсинга.

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

Можно создать запрос с параметрами и передать для них значения из соответствующих параметров HTTP-запроса. Дополнительную информацию смотрите в Запросы с параметрами для консольного клиента.

Пример

Предопределенный HTTP интерфейс

ClickHouse поддерживает определенные запросы через HTTP-интерфейс. Например, вы можете записать данные в таблицу следующим образом:

ClickHouse также поддерживает предопределенный HTTP-интерфейс, который может помочь вам легче интегрироваться со сторонними инструментами, такими как Prometheus exporter.

Пример:

• Прежде всего, добавьте раздел в конфигурационный файл сервера:

• Теперь вы можете напрямую запросить URL-адрес для получения данных в формате Prometheus:

Как вы можете видеть из примера, http_handlers настраивается в файле config.xml и может содержать несколько правил. ClickHouse будет сопоставлять полученные HTTP-запросы с предопределенным типом в правиле, и первое совпадение запустит обработчик. Затем ClickHouse выполнит соответствующий предопределенный запрос.

В настоящий момент с помощью rule можно настроить method, headers, url, handler:

• method отвечает за соответствие метода HTTP-запроса. method соответствует методу method протокола HTTP. Это необязательная настройка. Если она не определена в файле конфигурации, она не соответствует методу HTTP-запроса.

• url отвечает за соответствие URL HTTP-запроса. Она совместима с регулярными выражениями RE2. Это необязательная настройка. Если она не определена в файле конфигурации, она не соответствует URL-адресу HTTP-запроса.

• headers отвечают за соответствие заголовка HTTP-запроса. Она совместим с регулярными выражениями RE2. Это необязательная настройка. Если она не определен в файле конфигурации, она не соответствует заголовку HTTP-запроса.

• handler содержит основную часть обработчика. Сейчас handler может настраивать type, status, content_type, response_content, query, query_param_name. type на данный момент поддерживает три типа: predefined_query_handler, dynamic_query_handler, static.

  • query — используется с типом predefined_query_handler, выполняет запрос при вызове обработчика.

  • query_param_name — используется с типом dynamic_query_handler, извлекает и выполняет значение, соответствующее значению query_param_name в параметрах HTTP-запроса.

  • status — используется с типом static, возвращает код состояния ответа.

  • content_type — используется со всеми типами, возвращает content-type.

  • http_response_headers — используется со всеми типами чтобы добавить кастомные хедеры в ответ. Может использоваться в том числе для задания хедера Content-Type вместо content_type.

  • response_content — используется с типомstatic, содержимое ответа, отправленное клиенту, при использовании префикса ‘file://’ or ‘config://’, находит содержимое из файла или конфигурации, отправленного клиенту.

Далее приведены методы настройки для различных типов.

predefined_query_handler

predefined_query_handler поддерживает настройки Settings и query_params значений. Вы можете настроить запрос в типе predefined_query_handler.

Значение query — это предопределенный запрос predefined_query_handler, который выполняется ClickHouse при совпадении HTTP-запроса и возврате результата запроса. Это обязательная настройка.

В следующем примере определяются настройки max_threads и max_final_threads, а затем запрашивается системная таблица, чтобы проверить, были ли эти параметры успешно установлены.

Предупреждение

Чтобы сохранить стандартные handlers такие как query, play, ping, используйте правило <defaults/>.

Пример:

Предупреждение

В одном predefined_query_handler поддерживается только один запрос.

dynamic_query_handler

В dynamic_query_handler, запрос пишется в виде параметров HTTP-запроса. Разница в том, что в predefined_query_handler, запрос записывается в конфигурационный файл. Вы можете настроить query_param_name в dynamic_query_handler.

ClickHouse извлекает и выполняет значение, соответствующее значению query_param_name URL-адресе HTTP-запроса. Значение по умолчанию query_param_name — это /query . Это необязательная настройка. Если в файле конфигурации нет определения, параметр не передается.

Чтобы поэкспериментировать с этой функциональностью, в примере определяются значения max_threads и max_final_threads и запрашивается, успешно ли были установлены настройки.

Пример:

static

static может возвращать content_type, status и response_content. response_content может возвращать конкретное содержимое.

Пример:

Возвращает сообщение.

http_response_headers так же может использоваться для определения Content-Type вместо content_type.

Находит содержимое настроек отправленных клиенту.

Находит содержимое файла, отправленного клиенту.