HTTP-интерфейс
HTTP-интерфейс позволяет использовать ADQM на любой платформе и из любого языка программирования.
По умолчанию
Clickhouse-server слушает HTTP через порт 8123 (это можно изменить в конфиге). Если запросить GET / без параметров, то вернётся строка, заданная с помощью настройки http_server_default_response. Значение по умолчанию «Ok.» (с переводом строки на конце).Пример$ curl 'http://localhost:8123/' Ok.
Веб-интерфейс доступен по адресу:
http://localhost:8123/play.В скриптах проверки доступности можно использовать
GET /ping без параметров. Если сервер доступен, всегда возвращается «Ok.» (с переводом строки на конце).Пример$ curl 'http://localhost:8123/ping' Ok.
Возмжные способы отправки запроса:
- в виде URL-параметра с именем
query; - как тело запроса при использовании метода
POST; - как начало запроса в URL-параметре
query, а продолжениеPOST-запросом.
Размер URL ограничен 16KB, это следует учитывать при отправке больших запросов.
В случае успеха возвращается код ответа
200 и результат обработки запроса в теле ответа, в случае ошибки — код ответа 500 и текст с описанием ошибки в теле ответа.При использовании метода
GET выставляется настройка readonly. То есть, для запросов, модифицирующих данные, можно использовать только метод POST. Сам запрос при этом можно отправлять как в теле POST-запроса, так и в параметре URL.Примеры$ curl 'http://localhost:8123/?query=SELECT%201' 1 $ wget -nv -O- 'http://localhost:8123/?query=SELECT 1' 1 $ echo -ne 'GET /?query=SELECT%201 HTTP/1.0\r\n\r\n' | nc localhost 8123 HTTP/1.0 200 OK Date: Wed, 27 Nov 2019 10:30:18 GMT Connection: Close Content-Type: text/tab-separated-values; charset=UTF-8 X-Clickhouse-Server-Display-Name: Clickhouse.ru-central1.internal X-Clickhouse-Query-Id: 5abe861c-239c-467f-b955-8a201abb8b7f X-Clickhouse-Summary: {"read_rows":"0","read_bytes":"0","written_rows":"0","written_bytes":"0","total_rows_to_read":"0"}
Можно указать любой другой формат с помощью секции запроса
FORMAT.Чтобы указать формат по умолчанию, отличный от
TabSeparated, можно использовать параметр URL-адреса default_format или заголовок X-Clickhouse-Format.Пример$ echo 'SELECT 1 FORMAT Pretty' | curl 'http://localhost:8123/?' --data-binary @-
Возможность передавать данные с помощью
POST нужна для запросов INSERT. В этом случае можно написать начало запроса в параметре URL, а вставляемые данные передать POST-запросом. Вставляемыми данными может быть, например, tab-separated дамп, полученный из MySQL. Таким образом, запрос INSERT заменяет LOAD DATA LOCAL INFILE из MySQL.Создание таблицы:
$ echo 'CREATE TABLE t (a UInt8) ENGINE = Memory' | curl 'http://localhost:8123/' --data-binary @-
Вставка данных (запрос
INSERT):$ echo 'INSERT INTO t VALUES (1),(2),(3)' | curl 'http://localhost:8123/' --data-binary @-
Отправка данных (отдельно от запроса):
$ echo '(4),(5),(6)' | curl 'http://localhost:8123/query=INSERT%20INTO%20t%20VALUES' --data-binary @-
Можно указать любой формат для данных. Формат
Values - то же, что используется при записи INSERT INTO t VALUES:$ echo '(7),(8),(9)' | curl 'http://localhost:8123/?query=INSERT%20INTO%20t%20FORMAT%20Values' --data-binary @-
Можно вставить данные из
tab-separated дампа, указав соответствующий формат:$ echo -ne '10\n11\n12\n' | curl 'http://localhost:8123/?query=INSERT%20INTO%20t%20FORMAT%20TabSeparated' --data-binary @-
Чтение содержимого таблиц (данные выводятся в произвольном порядке из-за параллельной обработки запроса):
$ curl 'http://localhost:8123/?query=SELECT%20a%20FROM%20t'
Удаление таблицы:
$ echo 'DROP TABLE t' | curl 'http://localhost:8123/' --data-binary @-
Для запросов, которые не возвращают таблицу с данными, в случае успеха выдаётся пустое тело ответа.