版本: 最新版本-3.5

HTTP SQL API

StarRocks 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_ip	FE 节点的 IP 地址。
fe_http_port	FE HTTP 端口。
catalog_name	Catalog 的名称。在 v3.2.0 中，您只能使用此 API 查询 StarRocks 内部表，这意味着 `<catalog_name>` 只能设置为 `default_catalog`。自 v3.2.1 起，您可以使用此 API 查询外部 Catalog 中的表。
database_name	数据库名称。如果在请求行中未指定数据库名称，并且 SQL 查询中使用了表名，则必须在表名前加上数据库名称，例如 `database_name.table_name`。

在指定的 Catalog 中跨数据库查询数据。如果在 SQL 查询中使用了表，则必须在表名前加上数据库名称。
```
POST /api/v1/catalogs/<catalog_name>/sql
```

从指定的 Catalog 和数据库查询数据。

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>}}'

字段	描述
query	SQL 查询，STRING 格式。仅支持 SELECT、SHOW、EXPLAIN 和 KILL 语句。对于一个 HTTP 请求，您只能运行一个 SQL 查询。
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-Id	查询 ID。

响应体

请求发送前失败

请求在客户端失败或服务器在向客户端返回数据之前遇到错误。响应体的格式如下，其中 msg 是错误信息。

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

请求发送后失败

返回部分结果，并且 HTTP 状态代码为 200。数据发送暂停，连接关闭，并记录错误。

成功

响应消息中的每一行都是一个 JSON 对象。JSON 对象由 \n 分隔。

对于 SELECT 语句，将返回以下 JSON 对象。

对象	描述
`connectionId`	连接 ID。您可以通过调用 KILL `<connectionId>` 取消长时间挂起的查询。
`meta`	表示列。键是 `meta`，值是一个 JSON 数组，其中数组中的每个对象表示一列。
`data`	数据行，其中键是 `data`，值是一个 JSON 数组，其中包含一行数据。
`statistics`	查询的统计信息。

对于 SHOW 语句，将返回 meta、data 和 statistics。
对于 EXPLAIN 语句，将返回一个 explain 对象以显示查询的详细执行计划。

以下示例使用 \n 作为分隔符。StarRocks 使用 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 查询

从 StarRocks 内部表 (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}}

取消查询

要取消运行时间过长的查询，您可以关闭连接。当 StarRocks 检测到连接已关闭时，将取消此查询。

您也可以调用 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"

您可以从响应体或通过调用 SHOW PROCESSLIST 获取 connectionId。例如

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"

请求消息​

请求行​

认证方法​

请求体​

请求头​

响应消息​

状态码​

响应头​

响应体​

请求发送前失败​

请求发送后失败​

成功​

示例​

运行 SELECT 查询​

取消查询​

运行带有为此查询设置的会话变量的查询​

您觉得这篇文档怎么样？