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

HTTP SQL API

Selena v3.2.0 представляет 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Имя каталога. В версии v3.2.0 вы можете использовать этот API для запроса только внутренних таблиц Selena, что означает, что <catalog_name> может быть установлен только как default_catalog. Начиная с версии 1.5.0, вы можете использовать этот API для запроса таблиц в external catalogs.
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-StarRocks-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"