Перейти к основному содержимому
Перейти к основному содержимому

HTTP Интерфейс

HTTP интерфейс позволяет вам использовать ClickHouse на любой платформе с любого языка программирования в форме REST API. HTTP интерфейс более ограничен по сравнению с нативным интерфейсом, но он имеет лучшую поддержку языков.

По умолчанию clickhouse-server слушает HTTP на порту 8123 (это можно изменить в конфигурации). HTTPS также может быть включен с портом 8443 по умолчанию.

Если вы выполните запрос GET / без параметров, он вернет код ответа 200 и строку, определенную в http_server_default_response с значением по умолчанию "Ok." (с переводом строки в конце)

Также см.: особенности кодов ответа HTTP.

Иногда команда curl недоступна на операционных системах пользователей. На Ubuntu или Debian выполните sudo apt install curl. Пожалуйста, обратитесь к этой документации для установки перед выполнением примеров.

Веб-интерфейс можно открыть здесь: http://localhost:8123/play.

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

Веб-интерфейс разработан для профессионалов, таких как вы.

В скриптах проверки состояния используйте запрос GET /ping. Этот обработчик всегда возвращает "Ok." (с переводом строки в конце). Доступно с версии 18.12.13. Также см. /replicas_status, чтобы проверить задержку реплики.

Отправьте запрос как параметр URL 'query' или в качестве POST. Или отправьте начало запроса в параметре 'query', а остальную часть в POST (мы объясним позже, почему это необходимо). Размер URL по умолчанию ограничен 1 МиБ, это можно изменить с помощью настройки http_max_uri_size.

Если запрос выполнен успешно, вы получите код ответа 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 для передачи данных для вставки. Данные для вставки могут быть, например, дамп в формате табуляции из MySQL. Таким образом, запрос INSERT заменяет LOAD DATA LOCAL INFILE из MySQL.

Примеры

Создание таблицы:

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

Данные могут быть отправлены отдельно от запроса:

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

Чтобы вставить данные из дампа с табуляцией, укажите соответствующий формат:

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

Удаление таблицы.

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

Сжатие​

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

Вы можете использовать внутренний формат сжатия 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
  • zstd
  • lz4
  • bz2
  • snappy

Чтобы отправить сжатый POST запрос, добавьте заголовок запроса Content-Encoding: метод_сжатия. Чтобы ClickHouse сжжал ответ, включите сжатие с помощью настройки enable_http_compression и добавьте заголовок Accept-Encoding: метод_сжатия к запросу. Вы можете настроить уровень сжатия данных в настройке 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 протоколе​

Вы также можете использовать сессии 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. Также могут быть использованы настройки http_response_buffer_size и http_wait_end_of_query.

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

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

Пример:

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

Установка роли с помощью параметров запроса​

Это новая функция, добавленная в ClickHouse 24.4.

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

Что приведет к ошибке:

Чтобы обойти это ограничение, вы можете использовать параметр запроса role вместо этого:

Это будет эквивалентно выполнению SET ROLE my_role перед оператором.

Кроме того, возможно указать несколько параметров запроса role:

В этом случае ?role=my_role&role=my_other_role работает аналогично выполнению SET ROLE my_role, my_other_role перед оператором.

Особенности кодов ответа HTTP​

Из-за ограничений протокола HTTP код ответа HTTP 200 не гарантирует, что запрос был успешен.

Вот пример:

Причина этого поведения связана с природой протокола HTTP. HTTP заголовок отправляется первым с кодом HTTP 200, а затем идет тело HTTP, и ошибка вставляется в тело как простой текст. Это поведение независимо от используемого формата, будь то Native, TSV или JSON; сообщение об ошибке всегда будет находиться посередине потока ответа. Вы можете смягчить эту проблему, включив wait_end_of_query=1 (Буферизация ответа). В этом случае отправка заголовка HTTP задерживается до полного разрешения запроса. Однако это не полностью решает проблему, так как результат все еще должен вписываться в http_response_buffer_size, и другие настройки, такие как send_progress_in_http_headers, могут помешать задержке заголовка. Единственный способ поймать все ошибки — анализировать тело HTTP перед его парсингом с использованием требуемого формата.

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

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

Пример​

Табуляция в URL параметрах​

Параметры запроса разбираются в "закодированном" формате. Это имеет некоторые преимущества, такие как возможность однозначно разбирать нулевые значения как \N. Это означает, что символ табуляции должен быть закодирован как \t (или \ и табуляция). Например, следующее содержит фактическую табуляцию между abc и 123, и входная строка делится на два значения:

Однако, если вы пытаетесь закодировать фактическую табуляцию, используя %09 в параметре URL, она не будет правильно разобрана:

Если вы используете параметры URL, вам нужно закодировать \t как %5C%09. Например:

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

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

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

Пример:

  • Прежде всего, добавьте этот раздел в файл конфигурации сервера:
  • Теперь вы можете напрямую запрашивать URL для получения данных в формате Prometheus:

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

Теперь rule может настраивать method, headers, url, handler:

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

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

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

  • handler содержит основную часть обработки. Теперь handler может настраивать type, status, content_type, http_response_headers, 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 — используется с любым типом, тип контента ответа.

    • http_response_headers — используется с любым типом, отображение заголовков ответа. Может использоваться для установки типа контента.

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

Следующие методы конфигурации для разных type.

predefined_query_handler​

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

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

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

примечание

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

Пример:

примечание

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

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.

Найдите контент из конфигурации, отправляемой клиенту.

Найдите контент из файла, отправляемый клиенту.

Valid JSON/XML response on exception during HTTP streaming​

Во время выполнения запроса через HTTP может произойти исключение, когда часть данных уже была отправлена. Обычно исключение отправляется клиенту в чистом текстовом виде, даже если был использован какой-либо конкретный формат данных для вывода, и вывод может стать недействительным с точки зрения указанного формата данных. Чтобы этого избежать, вы можете использовать настройку http_write_exception_in_output_format (включена по умолчанию), которая укажет ClickHouse записать исключение в указанном формате (в настоящее время поддерживается для форматов XML и JSON*).

Примеры: