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

Веб UI доступен здесь: http://localhost:8123/play.

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

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

В скриптах проверки состояния используйте запрос 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: 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. Пример:

2. В параметрах URL 'user' и 'password' (Мы не рекомендуем использовать этот метод, так как параметр может быть зарегистрирован веб-прокси и кэширован в браузере). Пример:

3. Используя заголовки '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-заголовок с кодом 200, затем тело HTTP, и ошибка вставляется в тело как простой текст. Это поведение независимо от использованного формата, будь то Native, TSV или JSON; сообщение об ошибке всегда будет в середине потока ответа. Вы можете смягчить эту проблему, включив wait_end_of_query=1 (Буфферизация ответов). В этом случае отправка заголовка HTTP задерживается до полного завершения запроса. Однако это не решает проблему полностью, так как результат все еще должен помещаться в http_response_buffer_size, и другие настройки, такие как send_progress_in_http_headers, могут помешать задержке заголовка. Единственный способ поймать все ошибки — проанализировать тело HTTP до его парсинга с использованием требуемого формата.

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

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

Пример

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

Параметры запроса анализируются из "кодуемого" формата. Это имеет некоторые преимущества, такие как возможность однозначного анализа null как \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 может содержать много правил. 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 — используется с любым типом, заголовок 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, затем запрашивает системную таблицу, чтобы проверить, были ли настройки успешно установлены.

примечание

Чтобы сохранить стандартные handlers, такие как 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.

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

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

Валидный JSON/XML ответ при исключении во время HTTP потоковой передачи

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

Примеры: