Перейти к основному содержимому
Версия: 2.0.x

HTTP SQL API

Selena v1.5.2 представляет HTTP SQL API для выполнения различных типов запросов с использованием HTTP. В настоящее время этот API поддерживает операторы SELECT, SHOW, EXPLAIN и KILL.

Синтаксис с использованием команды curl:

curl -X POST 'http://<fe_ip>:<fe_http_port>/api/v1/catalogs/<catalog_name>/databases/<database_name>/sql' \
   -u '<username>:<password>'  -d '{"query": "<sql_query>;", "sessionVariables":{"<var_name>":<var_value>}}' \
   --header "Content-Type: application/json"

Сообщение запроса​

Строка запроса​

POST 'http://<fe_ip>:<fe_http_port>/api/v1/catalogs/<catalog_name>/databases/<database_name>/sql'
ПолеОписание
fe_ipIP-адрес FE узла.
fe_http_portHTTP порт FE.
catalog_nameИмя каталога. В v1.5.2 вы можете использовать этот API для запросов только к внутренним таблицам Selena, что означает, что <catalog_name> может быть установлен только в default_catalog. Начиная с v1.5.2, вы можете использовать этот API для запросов к таблицам во внешних каталогах.
database_nameИмя базы данных. Если в строке запроса не указано имя базы данных, а в SQL-запросе используется имя таблицы, вы должны добавить к имени таблицы префикс с именем базы данных, например, database_name.table_name.

  • Запрос данных из разных баз данных в указанном каталоге. Если в SQL-запросе используется таблица, вы должны добавить к имени таблицы префикс с именем базы данных.

    POST /api/v1/catalogs/<catalog_name>/sql

  • Запрос данных из указанного каталога и базы данных.

    POST /api/v1/catalogs/<catalog_name>/databases/<database_name>/sql

Метод аутентификации​

Authorization: Basic <credentials>

Используется базовая аутентификация, то есть введите имя пользователя и пароль для credentials (-u '<username>:<password>'). Если для имени пользователя не установлен пароль, вы можете передать только <username>: и оставить пароль пустым. Например, если используется учетная запись root, вы можете ввести -u 'root:'.

Тело запроса​

-d '{"query": "<sql_query>;", "sessionVariables":{"<var_name>":<var_value>}}'
ПолеОписание
querySQL-запрос в формате STRING. Поддерживаются только операторы SELECT, SHOW, EXPLAIN и KILL. Вы можете выполнить только один SQL-запрос для одного HTTP-запроса.
sessionVariablesПеременная сеанса, которую вы хотите установить для запроса, в формате JSON. Это поле необязательное. По умолчанию пустое. Переменная сеанса, которую вы устанавливаете, действует для того же соединения и становится недействительной при закрытии соединения.

Заголовок запроса​

--header "Content-Type: application/json"

Этот заголовок указывает, что тело запроса является JSON-строкой.

Ответное сообщение​

Код состояния​

  • 200: HTTP-запрос успешен, и сервер работает нормально до отправки данных клиенту.
  • 4xx: Ошибка HTTP-запроса, которая указывает на ошибку клиента.
  • 500 Internal Server Error: HTTP-запрос успешен, но сервер сталкивается с ошибкой до отправки данных клиенту.
  • 503: HTTP-запрос успешен, но FE не может предоставить сервис.

Заголовок ответа​

content-type указывает формат тела ответа. Используется JSON с разделителями новой строки, что означает, что тело ответа состоит из нескольких JSON-объектов, разделенных \n.

Описание
content-typeФормат - JSON с разделителями новой строки, по умолчанию "application/x-ndjson charset=UTF-8".
X-Selena-Query-IdID запроса.

Тело ответа​

Сбой до отправки запроса​

Запрос завершается с ошибкой на стороне клиента или сервер сталкивается с ошибкой до возврата данных клиенту. Тело ответа имеет следующий формат, где msg - это информация об ошибке.

{
   "status":"FAILED",
   "msg":"xxx"
}

Сбой после отправки запроса​

Часть результата возвращается, и код состояния HTTP равен 200. Отправка данных приостанавливается, соединение закрывается, и ошибка регистрируется.

Успешное выполнение​

Каждая строка в ответном сообщении является JSON-объектом. JSON-объекты разделены \n.

  • Для оператора SELECT возвращаются следующие JSON-объекты.
ОбъектОписание
connectionIdID соединения. Вы можете отменить запрос, который ожидается долгое время, вызвав KILL <connectionId>.
metaПредставляет столбец. Ключ - meta, а значение - JSON-массив, где каждый объект в массиве представляет столбец.
dataСтрока данных, где ключ - data, а значение - JSON-массив, который содержит строку данных.
statisticsСтатистическая информация о запросе.
  • Для оператора SHOW возвращаются meta, data и statistics.
  • Для оператора EXPLAIN возвращается объект explain для отображения подробного плана выполнения запроса.

В следующем примере используется \n в качестве разделителя. Selena передает данные в режиме HTTP chunked. Каждый раз, когда FE получает порцию данных, он передает эту порцию данных клиенту. Клиент может анализировать данные построчно, что устраняет необходимость кэширования данных и необходимость ожидания всех данных, снижая потребление памяти для клиента.

{"connectionId": 7}\n
{"meta": [
    {
      "name": "stock_symbol",
      "type": "varchar"
    },
    {
      "name": "closing_price",
      "type": "decimal64(8, 2)"
    },
    {
      "name": "closing_date",
      "type": "datetime"
    }
  ]}\n
{"data": ["JDR", 12.86, "2014-10-02 00:00:00"]}\n
{"data": ["JDR",14.8, "2014-10-10 00:00:00"]}\n
...
{"statistics": {"scanRows": 0,"scanBytes": 0,"returnRows": 9}}

Примеры​

Выполнение SELECT-запроса​

  • Запрос данных из внутренней таблицы Selena (catalog_name - это default_catalog).

    curl -X POST 'http://127.0.0.1:8030/api/v1/catalogs/default_catalog/databases/test/sql' -u 'root:' -d '{"query": "select * from agg;"}' --header "Content-Type: application/json"

    Результат:

    {"connectionId":49}
    {"meta":[{"name":"no","type":"int(11)"},{"name":"k","type":"decimal64(10, 2)"},{"name":"v","type":"decimal64(10, 2)"}]}
    {"data":[1,"10.00",null]}
    {"data":[2,"10.00","11.00"]}
    {"data":[2,"20.00","22.00"]}
    {"data":[2,"25.00",null]}
    {"data":[2,"30.00","35.00"]}
    {"statistics":{"scanRows":0,"scanBytes":0,"returnRows":5}}

  • Запрос данных из таблицы Iceberg.

    curl -X POST 'http://172.26.93.145:8030/api/v1/catalogs/iceberg_catalog/databases/ywb/sql' -u 'root:' -d '{"query": "select * from iceberg_analyze;"}' --header "Content-Type: application/json"

    Результат:

    {"connectionId":13}
    {"meta":[{"name":"k1","type":"int(11)"},{"name":"k2","type":"int(11)"}]}
    {"data":[1,2]}
    {"data":[1,1]}
    {"statistics":{"scanRows":0,"scanBytes":0,"returnRows":2}}

Отмена запроса​

Чтобы отменить запрос, который выполняется неожиданно долго, вы можете закрыть соединение. Selena отменит этот запрос, когда обнаружит, что соединение закрыто.

Вы также можете вызвать KILL connectionId для отмены этого запроса. Например:

curl -X POST 'http://127.0.0.1:8030/api/v1/catalogs/default_catalog/databases/test/sql' -u 'root:' -d '{"query": "kill 17;"}' --header "Content-Type: application/json"

Вы можете получить connectionId из тела ответа или вызвав SHOW PROCESSLIST. Например:

curl -X POST 'http://127.0.0.1:8030/api/v1/catalogs/default_catalog/databases/test/sql' -u 'root:' -d '{"query": "show processlist;"}' --header "Content-Type: application/json"

Выполнение запроса с переменной сеанса, установленной для этого запроса​

curl -X POST 'http://127.0.0.1:8030/api/v1/catalogs/default_catalog/databases/test/sql' -u 'root:'  -d '{"query": "SHOW VARIABLES;", "sessionVariables":{"broadcast_row_limit":14000000}}'  --header "Content-Type: application/json"