HTTP Интерфейс

Предварительные требования

Для примеров в этой статье вам потребуется:

• работающий экземпляр сервера ClickHouse
• установленный curl. На Ubuntu или Debian выполните команду sudo apt install curl или ознакомьтесь с этой документацией для инструкций по установке.

Обзор

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

По умолчанию clickhouse-server прослушивает следующие порты:

• порт 8123 для HTTP
• порт 8443 для HTTPS может быть включён

Если вы выполните запрос GET / без параметров, будет возвращён код ответа 200 вместе со строкой "Ok.":

"Ok." — это значение по умолчанию, определённое в http_server_default_response и его можно изменить при необходимости.

Также см.: Коды ответов HTTP. Замечания.

Веб-интерфейс пользователя

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

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

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

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

Запросы через HTTP/HTTPS

Чтобы выполнять запросы через HTTP/HTTPS есть три варианта:

• отправить запрос как URL параметр 'query'
• используйте метод POST.
• Отправьте начало запроса в параметре 'query', а остальную часть с помощью POST

примечание

Размер URL по умолчанию ограничен 1 Миб, это можно изменить с помощью настройки http_max_uri_size.

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

Запросы с использованием GET являются 'только для чтения'. Это означает, что для запросов, которые модифицируют данные, вы можете использовать только метод POST. Вы можете отправить сам запрос либо в теле POST, либо в параметре URL. Рассмотрим несколько примеров.

В приведённом ниже примере используется curl для отправки запроса SELECT 1. Обратите внимание на использование кодирования URL для пробелов: %20.

В этом примере используется wget с параметрами -nv (негромкий) и -O-, чтобы вывести результат в терминал. В этом случае не обязательно использовать кодирование URL для пробела:

В этом примере мы передаём сырой HTTP запрос в netcat:

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

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

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

Клаузула FORMAT используется в запросе для запроса любого другого формата. Например:

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

Запросы INSERT через HTTP/HTTPS

Метод 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), и вы можете получить распакованные данные, даже если используете настройки сжатия правильно.

Примеры

Чтобы отправить сжатые данные на сервер:

Чтобы получить сжатый архив данных от сервера:

Чтобы получить сжатые данные от сервера, используя gunzip для получения распакованных данных:

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

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

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

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

1. Используя HTTP Basic аутентификацию.

Например:

2. В URL параметрах user и password

осторожно

Мы не рекомендуем использовать этот метод, так как параметр может быть зарегистрирован веб-прокси и кэширован в браузере.

Например:

3. Используя заголовки 'X-ClickHouse-User' и 'X-ClickHouse-Key'

Например:

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

Например:

Для получения дополнительной информации см.:

• Настройки
• SET

Использование сессий ClickHouse в HTTP протоколе

Вы также можете использовать сессии ClickHouse в HTTP протоколе. Для этого нужно добавить параметр session_id в запрос GET. Вы можете использовать любую строку в качестве идентификатора сессии.

По умолчанию сессия завершается через 60 секунд бездействия. Чтобы изменить этот тайм-аут (в секундах), измените настройку default_session_timeout в конфигурации сервера или добавьте параметр 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 параметрах

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

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

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

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

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

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

Прежде всего, добавьте этот раздел в файл конфигурации вашего сервера.

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

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

Параметры конфигурации для http_handlers работают следующим образом.

rule может настраивать следующие параметры:

• method
• headers
• url
• handler

Каждый из них обсуждается ниже:

• method отвечает за сопоставление части метода HTTP запроса. method полностью соответствует определению method в протоколе HTTP. Это необязательная настройка. Если она не определена в конфигурационном файле, она не соответствует metоду 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, затем запрашивает системную таблицу, чтобы проверить, были ли эти настройки установлены успешно.

примечание

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

Например:

примечание

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

dynamic_query_handler

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

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

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

Пример:

static

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

Например, чтобы вернуть сообщение "Say Hi!":

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

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

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

Valid JSON/XML response on exception during HTTP streaming

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

Примеры: