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

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 МiБ, это можно изменить с помощью параметра http_max_uri_size.

Если запрос успешен, вы получите код ответа 200 и результат в теле ответа. Если произошла ошибка, вы получите код ответа 500 и текст описания ошибки в теле ответа.

При использовании метода GET устанавливается 'readonly'. Другими словами, для запросов, которые изменяют данные, можно использовать только метод POST. Вы можете отправить сам запрос как в теле POST, так и в URL параметре.

Примеры:

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

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

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

Вы можете использовать SQL оператор 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. Пример:
  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 параметрах​

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

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

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

Valid JSON/XML response on exception during HTTP streaming​

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

Примеры: