HTTP Handler

Databend HTTP Handler 是一个 REST API ，用于向服务器发送需要执行的查询语句，并接收返回给客户端的结果。

HTTP Handler 由 databend-query 提供，通过 --http_handler_host 和 --http_handler_port (默认值为 8000) 指定主机和端口。

HTTP 方法

概览

该 HTTP Handler 通过具有长轮询的页面中返回结果。

使用 QueryRequest 类型的 JSON 将查询 POST 到 /v1/query，其中包含要执行的 SQL，返回结果是 QueryResponse 类型的 JSON。
对 QueryResponse 中的字段作进一步处理：
1. 通过 GET next_uri 返回查询结果的下一页（也是 QueryResponse 类型的 JSON ）。以相同的方式处继续处理，直到 next_uri 为 null。
2. （可选）通过 GET kill_uri 终止查询。返回空正文。
3. （可选）对 stats_uri 进行 GET 获取一次统计信息（无需长轮询），返回带有空 data 字段的 QueryResponse。

简单示例

curl -u root: --request POST '127.0.0.1:8001/v1/query/' --header 'Content-Type: application/json' --data-raw '{"sql": "SELECT avg(number) FROM numbers(100000000)"}'

SQL 将使用默认会话和分页设置运行：

使用新的一次性会话对 default 数据库进行查询。
每个请求在返回之前最多等待1秒钟。

更多高级配置，请参考本页其他内容。

返回的 JSON（格式化）类似这样：

{
  "id": "3cd25ab7-c3a4-42ce-9e02-e1b354d91f06",
  "session_id": "8d3a737d-2f6c-4df7-ba44-6dfc818255ce",
  "session": {},
  "schema": {
    "fields": [
      {
        "name": "avg(number)",
        "default_expr": null,
        "data_type": {
          "type": "Float64Type"
        }
      }
    ],
    "metadata": {}
  },
  "data": [
    [
      "49999999.5"
    ]
  ],
  "state": "Succeeded",
  "error": null,
  "stats": {
    "scan_progress": {
      "rows": 100000000,
      "bytes": 800000000
    },
    "write_progress": {
      "rows": 0,
      "bytes": 0
    },
    "result_progress": {
      "rows": 0,
      "bytes": 0 
    },
    "running_time_ms": 466.85395800000003
  },
  "stats_uri": "/v1/query/3cd25ab7-c3a4-42ce-9e02-e1b354d91f06",
  "next_uri": null
  "affect": null
}

查询请求

QueryRequest

字段	类型	必填	描述
sql	string	是	要执行的 SQL 语句
session_id	string	否	仅在重新使用服务器端会话时使用
session	SessionState	否
pagination	Pagination	否	此 POST 请求全局唯一的 query_id

SessionState

字段	type	必填	默认	描述
database	string	否	"default"	设置当前数据库
keep_server_session_secs	int	否	0	最后一个查询完成后保留会话的时长（单位：秒）
settings	map(string, string)	否	0

OldSession

字段	类型	必填	默认	描述
id	string	否		QueryResponse.session_id 中的 session_id

Pagination：每个 HTTP 请求返回的关键条件（在所有剩余结果准备好返回之前）

字段	类型	必填	默认	描述
wait_time_secs	u32	否	1	长轮询时间

查询响应

QueryResponse：

字段	类型	描述
state	string	可选值：Running、Failed、Succeeded
error	QueryError	SQL 解析或执行错误
id	string	此 POST 请求全局唯一的 query_id
data	array	数组中的每个元素代表返回结果中的一行
schema	Schema	返回结果的 Schema
affect	Affect	某些查询影响
session_id	String
session	SessionState

Schema:

字段	类型	描述
fields	array	字段排序顺序
metadata	object	包含额外 Meta 数据的键值对映射

Field:

字段	类型
name	string
data_type	string
nullable	bool

Stats:

字段	类型	描述
running_time_ms	float	内部执行查询所耗时间（单位：毫秒）
scan_progress	QueryProgress	查询扫描进度

Progress:

字段	类型
read_rows	int
read_bytes	int

Error:

字段	类型	描述
stats	int	Databend 内部的错误代码
message	string	错误消息
backtrace	string

Affect:

字段	类型	描述
type	string	ChangeSetting/UseDB
...		其他字段根据类型不同而变化

响应状态代码

不同类型的错误状态代码：

代码	错误
200	SQL 无效或查询失败，详细信息在 JSON 的 `error` 字段中
404	找不到 query_id 或 page
400	请求格式非法

当状态码不是200时，出错原因可在响应体的字符串中找到。

数据格式

.data 中的所有字段值都以字符串表示，客户端需要借助 schema 字段中的信息来解释这些值。

会话支持 (可选)

客户端可以在 session 字段中配置会话。

{
  "sql": "select 1", 
  "session": {
    "db": "db2",
    "settings": {
      "max_threads": "1"
    }
  } 
}

所有设置的值都应该是字符串。

默认情况下，每个请求在服务器内有自己的会话。在 SQL 执行完成后，甚至在客户端获取结果数据之前，会话应该立即摧毁。执行 set 和 use 这种更改上下文的 SQL 语句需要会话支持。有两个选择：

服务器端会话

对于启动会话的第一个 QueryRequest：将 QueryRequest.session.keep_server_session_secs 设置为一个正整数，例如10。记住返回的 QueryResponse.session_id。

{
  "sql": "...;", 
  "session": {
    "keep_server_session_secs": 100
  } 
}

对于以下使用会话的 QueryRequest：使用 QueryResponse.session_id 作为 QueryRequest.session.id。

{
  "sql": "...;", 
  "session_id": "<QueryResponse.session_id>"
}

客户端会话

Handler 将在 affect 字段中返回有关更改设置或当前数据库的信息，客户端可以记住这些更改并将它们放在后面请求的会话字段中。

客户端会话响应将包含 session 字段，该字段包括请求中的 session 字段和以及应用到它的 affect。 session 字段只用在 next_url 中，且必须是在 state 字段值为 Succeeded 的情况下。

set 语句：

{
  "sql": "set max_threads=1;",
  "session": {
    "database": "db1",
    "settings": {
      "max_threads": "6"
    }
  }
}

{
  "affect": {
    "type": "ChangeSetting",
    "key": "max_threads",
    "value": "1",
    "is_global": false
  },
  "session": {
    "database": "db1",
    "settings": {
      "max_threads": "1"
    }
  }
}

use 语句：

{"sql": "use db2",
  "session": {
    "database": "db1",
    "settings": {
      "max_threads": "6"
    }
  }
}

{
  "affect": {
    "type": "UseDB",
    "name": "db2"
  },
  "session": {
    "database": "db2",
    "settings": {
      "max_threads": "1"
    }
  }
}

HTTP 方法​

概览​

简单示例​

查询请求​

查询响应​

响应状态代码​

数据格式​

会话支持 (可选)​

服务器端会话​

客户端会话​