mirror of
https://github.com/ClickHouse/ClickHouse.git
synced 2024-10-04 07:30:52 +00:00
169 lines
10 KiB
ReStructuredText
169 lines
10 KiB
ReStructuredText
|
HTTP-интерфейс
|
|||
|
|
==============
|
|||
|
|
|
|||
|
|
HTTP интерфейс позволяет использовать ClickHouse на любой платформе, из любого языка программирования. У нас он используется для работы из Java и Perl, а также из shell-скриптов. В других отделах, HTTP интерфейс используется из Perl, Python и Go. HTTP интерфейс более ограничен по сравнению с родным интерфейсом, но является более совместимым.
|
|||
|
|
|
|||
|
|
По умолчанию, clickhouse-server слушает HTTP на порту 8123 (это можно изменить в конфиге).
|
|||
|
|
Если запросить GET / без параметров, то вернётся строка "Ok." (с переводом строки на конце). Это может быть использовано в скриптах проверки живости.
|
|||
|
|
::
|
|||
|
|
$ curl 'http://localhost:8123/'
|
|||
|
|
Ok.
|
|||
|
|
|
|||
|
|
Запрос отправляется в виде параметра URL query. Или POST-ом. Или начало запроса в параметре query, а продолжение POST-ом (зачем это нужно, будет объяснено ниже).
|
|||
|
|
В случае успеха, вам вернётся код ответа 200 и результат обработки запроса в теле ответа.
|
|||
|
|
В случае ошибки, вам вернётся код ответа 500 и текст с описанием ошибки в теле ответа.
|
|||
|
|
|
|||
|
|
При использовании метода GET, выставляется настройка readonly. То есть, для запросов, модифицирующие данные, можно использовать только метод POST. Сам запрос при этом можно отправлять как в теле POST-а, так и в параметре URL.
|
|||
|
|
|
|||
|
|
Примеры:
|
|||
|
|
::
|
|||
|
|
$ curl 'http://localhost:8123/?query=SELECT%201'
|
|||
|
|
1
|
|||
|
|
|
|||
|
|
$ wget -O- -q 'http://localhost:8123/?query=SELECT 1'
|
|||
|
|
1
|
|||
|
|
|
|||
|
|
$ GET '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
|
|||
|
|
Connection: Close
|
|||
|
|
Date: Fri, 16 Nov 2012 19:21:50 GMT
|
|||
|
|
|
|||
|
|
1
|
|||
|
|
|
|||
|
|
Как видно, curl немного неудобен тем, что надо URL-эскейпить пробелы.
|
|||
|
|
wget сам всё эскейпит, но его не рекомендуется использовать, так как он плохо работает по HTTP 1.1 при использовании keep-alive и Transfer-Encoding: chunked.
|
|||
|
|
::
|
|||
|
|
$ echo 'SELECT 1' | curl 'http://localhost:8123/' --data-binary @-
|
|||
|
|
1
|
|||
|
|
|
|||
|
|
$ echo 'SELECT 1' | curl 'http://localhost:8123/?query=' --data-binary @-
|
|||
|
|
1
|
|||
|
|
|
|||
|
|
$ echo '1' | curl 'http://localhost:8123/?query=SELECT' --data-binary @-
|
|||
|
|
1
|
|||
|
|
|
|||
|
|
Если часть запроса отправляется в параметре, а часть POST-ом, то между этими двумя кусками данных ставится перевод строки.
|
|||
|
|
Пример (так работать не будет):
|
|||
|
|
::
|
|||
|
|
$ echo 'ECT 1' | curl 'http://localhost:8123/?query=SEL' --data-binary @-
|
|||
|
|
Code: 59, e.displayText() = DB::Exception: Syntax error: failed at position 0: SEL
|
|||
|
|
ECT 1
|
|||
|
|
, expected One of: SHOW TABLES, SHOW DATABASES, SELECT, INSERT, CREATE, ATTACH, RENAME, DROP, DETACH, USE, SET, OPTIMIZE., e.what() = DB::Exception
|
|||
|
|
|
|||
|
|
По умолчанию, данные возвращаются в формате TabSeparated (подробнее смотри раздел "Форматы").
|
|||
|
|
Можно попросить любой другой формат - с помощью секции FORMAT запроса.
|
|||
|
|
::
|
|||
|
|
$ echo 'SELECT 1 FORMAT Pretty' | curl 'http://localhost:8123/?' --data-binary @-
|
|||
|
|
┏━━━┓
|
|||
|
|
┃ 1 ┃
|
|||
|
|
┡━━━┩
|
|||
|
|
│ 1 │
|
|||
|
|
└───┘
|
|||
|
|
|
|||
|
|
Возможность передавать данные POST-ом нужна для INSERT-запросов. В этом случае вы можете написать начало запроса в параметре URL, а вставляемые данные передать POST-ом. Вставляемыми данными может быть, например, tab-separated дамп, полученный из MySQL. Таким образом, запрос INSERT заменяет LOAD DATA LOCAL INFILE из MySQL.
|
|||
|
|
|
|||
|
|
Примеры:
|
|||
|
|
Создаём таблицу:
|
|||
|
|
::
|
|||
|
|
echo 'CREATE TABLE t (a UInt8) ENGINE = Memory' | POST 'http://localhost:8123/'
|
|||
|
|
|
|||
|
|
Используем привычный запрос INSERT для вставки данных:
|
|||
|
|
::
|
|||
|
|
echo 'INSERT INTO t VALUES (1),(2),(3)' | POST 'http://localhost:8123/'
|
|||
|
|
|
|||
|
|
Данные можно отправить отдельно от запроса:
|
|||
|
|
::
|
|||
|
|
echo '(4),(5),(6)' | POST 'http://localhost:8123/?query=INSERT INTO t VALUES'
|
|||
|
|
|
|||
|
|
Можно указать любой формат для данных. Формат Values - то же, что используется при записи INSERT INTO t VALUES:
|
|||
|
|
::
|
|||
|
|
echo '(7),(8),(9)' | POST 'http://localhost:8123/?query=INSERT INTO t FORMAT Values'
|
|||
|
|
|
|||
|
|
Можно вставить данные из tab-separated дампа, указав соответствующий формат:
|
|||
|
|
::
|
|||
|
|
echo -ne '10\n11\n12\n' | POST 'http://localhost:8123/?query=INSERT INTO t FORMAT TabSeparated'
|
|||
|
|
|
|||
|
|
Прочитаем содержимое таблицы. Данные выводятся в произвольном порядке из-за параллельной обработки запроса:
|
|||
|
|
::
|
|||
|
|
$ GET 'http://localhost:8123/?query=SELECT a FROM t'
|
|||
|
|
7
|
|||
|
|
8
|
|||
|
|
9
|
|||
|
|
10
|
|||
|
|
11
|
|||
|
|
12
|
|||
|
|
1
|
|||
|
|
2
|
|||
|
|
3
|
|||
|
|
4
|
|||
|
|
5
|
|||
|
|
6
|
|||
|
|
|
|||
|
|
Удаляем таблицу.
|
|||
|
|
::
|
|||
|
|
POST 'http://localhost:8123/?query=DROP TABLE t'
|
|||
|
|
|
|||
|
|
Для запросов, которые не возвращают таблицу с данными, в случае успеха, выдаётся пустое тело ответа.
|
|||
|
|
|
|||
|
|
Вы можете использовать сжатие при передаче данных. Формат сжатых данных нестандартный, и вам придётся использовать для работы с ним специальную программу compressor (`sudo apt-get install compressor-metrika-yandex`).
|
|||
|
|
|
|||
|
|
Если вы указали в URL compress=1, то сервер будет сжимать отправляемые вам данные.
|
|||
|
|
Если вы указали в URL decompress=1, то сервер будет разжимать те данные, которые вы передаёте ему POST-ом.
|
|||
|
|
|
|||
|
|
Это может быть использовано для уменьшения трафика по сети при передаче большого количества данных, а также для создания сразу сжатых дампов.
|
|||
|
|
|
|||
|
|
В параметре URL database может быть указана БД по умолчанию.
|
|||
|
|
::
|
|||
|
|
$ echo 'SELECT number FROM numbers LIMIT 10' | curl 'http://localhost:8123/?database=system' --data-binary @-
|
|||
|
|
0
|
|||
|
|
1
|
|||
|
|
2
|
|||
|
|
3
|
|||
|
|
4
|
|||
|
|
5
|
|||
|
|
6
|
|||
|
|
7
|
|||
|
|
8
|
|||
|
|
9
|
|||
|
|
|
|||
|
|
По умолчанию используется БД, которая прописана в настройках сервера, как БД по умолчанию. По умолчанию, это - БД default. Также вы всегда можете указать БД через точку перед именем таблицы.
|
|||
|
|
|
|||
|
|
Имя пользователя и пароль могут быть указаны в одном из двух вариантов:
|
|||
|
|
1. С использованием HTTP Basic Authentification. Пример:
|
|||
|
|
::
|
|||
|
|
echo 'SELECT 1' | curl 'http://user:password@localhost:8123/' -d @-
|
|||
|
|
|
|||
|
|
2. В параметрах URL user и password. Пример:
|
|||
|
|
::
|
|||
|
|
echo 'SELECT 1' | curl 'http://localhost:8123/?user=user&password=password' -d @-
|
|||
|
|
|
|||
|
|
Если имя пользователя не указано, то используется имя пользователя default. Если пароль не указан, то используется пустой пароль.
|
|||
|
|
Также в параметрах URL вы можете указать любые настроки, которые будут использованы для обработки одного запроса, или целые профили настроек. Пример:
|
|||
|
|
`http://localhost:8123/?profile=web&max_rows_to_read=1000000000&query=SELECT+1`
|
|||
|
|
|
|||
|
|
Подробнее см. раздел "Настройки".
|
|||
|
|
::
|
|||
|
|
$ echo 'SELECT number FROM system.numbers LIMIT 10' | curl 'http://localhost:8123/?' --data-binary @-
|
|||
|
|
0
|
|||
|
|
1
|
|||
|
|
2
|
|||
|
|
3
|
|||
|
|
4
|
|||
|
|
5
|
|||
|
|
6
|
|||
|
|
7
|
|||
|
|
8
|
|||
|
|
9
|
|||
|
|
|
|||
|
|
Об остальных параметрах смотри раздел "SET".
|
|||
|
|
|
|||
|
|
В отличие от родного интерфейса, HTTP интерфейс не поддерживает понятие сессии и настройки в пределах сессии, не позволяет (вернее, позволяет лишь в некоторых случаях) прервать выполнение запроса, не показывает прогресс выполнения запроса. Парсинг и форматирование данных производится на стороне сервера и использование сети может быть неэффективным.
|
|||
|
|
Может быть передан необязательный параметр query_id - идентификатор запроса, произвольная строка. Подробнее смотрите раздел "Настройки, replace_running_query".
|
|||
|
|
|
|||
|
|
Может быть передан необязательный параметр quota_key - ключ квоты, произвольная строка. Подробнее смотрите раздел "Квоты".
|
|||
|
|
|
|||
|
|
HTTP интерфейс позволяет передать внешние данные (внешние временные таблицы) для использования запроса. Подробнее смотрите раздел "Внешние данные для обработки запроса"
|