REST Endpoint

REST Endpoint #

REST endpoint 允许用户通过 REST API 连接 SQL Gateway。

Overview of SQL Processing #

Open Session #

当客户端连接到 SQL Gateway 时,SQL Gateway 会创建一个 Session,存储客户端和 SQL Gateway 交互期间的用户相关信息。 创建 Session 后,SQL Gateway 会返回 SessionHandle 标识,用于后续的交互。

Submit SQL #

注册 Session 后,客户端能够提交 SQL 到 SQL Gateway。提交 SQL 后,SQL 会被转换成 Operation,并且返回 OperationHandle 标识,用于用户后续获取结果。 Operation 有它的生命周期,客户端可以取消正在执行的 Operation,或者关闭 Operation 并释放它使用的资源。

Fetch Results #

客户端可以通过 OperationHandleOperation 获取结果。当一个 Operation 已经就绪,SQL Gateway 将返回一个包含对应 schema 和 URI 的批式数据, URI 可以被用来获取下一个批式数据。当所有结果已经获取完成,SQL Gateway 会将结果中的 resultType 设置为 EOS,并且将获取下一个批式数据的 URI 设置为 null。

SQL Gateway Interactions

Endpoint Options #

Key Default Type Description
sql-gateway.endpoint.rest.address
(none) String 客户端通过该地址连接到 SQL Gateway 服务。
sql-gateway.endpoint.rest.bind-address
(none) String SQL Gateway 服务绑定的地址。
sql-gateway.endpoint.rest.bind-port
"8083" String SQL Gateway 服务绑定的端口号。接受端口列表 (“50100,50101”)或端口区间(“50100-50200”),也可以两种方式混用。为了避免同一台机器上运行多个 SQL Gateway 服务引起的端口冲突,建议设置为端口区间。
sql-gateway.endpoint.rest.port
8083 Integer 客户端连接的端口号。如果 bind-port 没有被指定,SQL Gateway 服务将会绑定这个端口。

REST API #

OpenAPI 规范如下,默认版本是 v2。

Version Description
Open API v1 specification 允许用户提交 SQL 语句到 Gateway 并执行。
Open API v2 specification 支持 SQL 客户端连接到 Gateway。
OpenAPI 规范目前仍处于实验阶段。

API reference #

/api_versions
Verb: GET Response code: 200 OK
Get the current available versions for the Rest Endpoint. The client can choose one of the return version as the protocol for later communicate.
/info
Verb: GET Response code: 200 OK
Get meta data for this cluster.
/sessions
Verb: POST Response code: 200 OK
Opens a new session with specific properties. Specific properties can be given for current session which will override the default properties of gateway.
/sessions/:session_handle
Verb: DELETE Response code: 200 OK
Closes the specific session.
Path parameters
  • session_handle - The SessionHandle that identifies a session.
/sessions/:session_handle
Verb: GET Response code: 200 OK
Get the session configuration.
Path parameters
  • session_handle - The SessionHandle that identifies a session.
/sessions/:session_handle/complete-statement
Verb: GET Response code: 200 OK
Get the completion hints for the given statement at the given position.
Path parameters
  • session_handle - The SessionHandle that identifies a session.
/sessions/:session_handle/configure-session
Verb: POST Response code: 200 OK
Configures the session with the statement which could be: CREATE TABLE, DROP TABLE, ALTER TABLE, CREATE DATABASE, DROP DATABASE, ALTER DATABASE, CREATE FUNCTION, DROP FUNCTION, ALTER FUNCTION, CREATE CATALOG, DROP CATALOG, USE CATALOG, USE [CATALOG.]DATABASE, CREATE VIEW, DROP VIEW, LOAD MODULE, UNLOAD MODULE, USE MODULE, ADD JAR.
Path parameters
  • session_handle - The SessionHandle that identifies a session.
/sessions/:session_handle/heartbeat
Verb: POST Response code: 200 OK
Trigger heartbeat to tell the server that the client is active, and to keep the session alive as long as configured timeout value.
Path parameters
  • session_handle - The SessionHandle that identifies a session.
/sessions/:session_handle/operations/:operation_handle/cancel
Verb: POST Response code: 200 OK
Cancel the operation.
Path parameters
  • session_handle - The SessionHandle that identifies a session.
  • operation_handle - The OperationHandle that identifies a operation.
/sessions/:session_handle/operations/:operation_handle/close
Verb: DELETE Response code: 200 OK
Close the operation.
Path parameters
  • session_handle - The SessionHandle that identifies a session.
  • operation_handle - The OperationHandle that identifies a operation.
/sessions/:session_handle/operations/:operation_handle/result/:token
Verb: GET Response code: 200 OK
Fetch results of Operation.
Path parameters
  • session_handle - The SessionHandle that identifies a session.
  • operation_handle - The OperationHandle that identifies a operation.
  • token - The OperationHandle that identifies a operation.
Query parameters
  • rowFormat (mandatory): The row format to serialize the RowData.
/sessions/:session_handle/operations/:operation_handle/status
Verb: GET Response code: 200 OK
Get the status of operation.
Path parameters
  • session_handle - The SessionHandle that identifies a session.
  • operation_handle - The OperationHandle that identifies a operation.
/sessions/:session_handle/statements
Verb: POST Response code: 200 OK
Execute a statement.
Path parameters
  • session_handle - The SessionHandle that identifies a session.
/api_versions
Verb: GET Response code: 200 OK
Get the current available versions for the Rest Endpoint. The client can choose one of the return version as the protocol for later communicate.
/info
Verb: GET Response code: 200 OK
Get meta data for this cluster.
/sessions
Verb: POST Response code: 200 OK
Opens a new session with specific properties. Specific properties can be given for current session which will override the default properties of gateway.
/sessions/:session_handle
Verb: DELETE Response code: 200 OK
Closes the specific session.
Path parameters
  • session_handle - The SessionHandle that identifies a session.
/sessions/:session_handle
Verb: GET Response code: 200 OK
Get the session configuration.
Path parameters
  • session_handle - The SessionHandle that identifies a session.
/sessions/:session_handle/heartbeat
Verb: POST Response code: 200 OK
Trigger heartbeat to tell the server that the client is active, and to keep the session alive as long as configured timeout value.
Path parameters
  • session_handle - The SessionHandle that identifies a session.
/sessions/:session_handle/operations/:operation_handle/cancel
Verb: POST Response code: 200 OK
Cancel the operation.
Path parameters
  • session_handle - The SessionHandle that identifies a session.
  • operation_handle - The OperationHandle that identifies a operation.
/sessions/:session_handle/operations/:operation_handle/close
Verb: DELETE Response code: 200 OK
Close the operation.
Path parameters
  • session_handle - The SessionHandle that identifies a session.
  • operation_handle - The OperationHandle that identifies a operation.
/sessions/:session_handle/operations/:operation_handle/result/:token
Verb: GET Response code: 200 OK
Fetch results of Operation.
Path parameters
  • session_handle - The SessionHandle that identifies a session.
  • operation_handle - The OperationHandle that identifies a operation.
  • token - The OperationHandle that identifies a operation.
/sessions/:session_handle/operations/:operation_handle/status
Verb: GET Response code: 200 OK
Get the status of operation.
Path parameters
  • session_handle - The SessionHandle that identifies a session.
  • operation_handle - The OperationHandle that identifies a operation.
/sessions/:session_handle/statements
Verb: POST Response code: 200 OK
Execute a statement.
Path parameters
  • session_handle - The SessionHandle that identifies a session.

Data Type Mapping #

目前 REST endpoint 支持使用查询参数 rowFormat 序列化 RowData。REST endpoint 使用 JSON 序列化 Table 对象。 请参考 JSON format 查看类型映射关系。

REST endpoint 也支持 PLAIN_TEXT 序列化 RowData,将所有列自动转换成 String

Back to top