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

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

REST API

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

VersionDescription
Open API v1 specification允许用户提交 SQL 语句到 Gateway 并执行。
Open API v2 specification支持 SQL 客户端连接到 Gateway。
Open API v3 specification支持 Materialized Table 刷新操作。

OpenAPI 规范目前仍处于实验阶段。

API reference

v3

/api_versions
Verb: GETResponse 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: GETResponse code: 200 OK
Get meta data for this cluster.
/sessions
Verb: POSTResponse 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: DELETEResponse code: 200 OK
Closes the specific session.
Path parameters
  • session_handle - The SessionHandle that identifies a session.
/sessions/:session_handle
Verb: GETResponse code: 200 OK
Get the session configuration.
Path parameters
  • session_handle - The SessionHandle that identifies a session.
/sessions/:session_handle/complete-statement
Verb: GETResponse 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: POSTResponse 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: POSTResponse 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/materialized-tables/:identifier/refresh
Verb: POSTResponse code: 200 OK
Refresh materialized table
Path parameters
  • session_handle - The SessionHandle that identifies a session.
  • identifier - The fully qualified string that identifies a materialized table.
/sessions/:session_handle/operations/:operation_handle/cancel
Verb: POSTResponse 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: DELETEResponse 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: GETResponse 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 token that identifies which batch of data to fetch.
Query parameters
  • rowFormat (mandatory): The row format to serialize the RowData.
/sessions/:session_handle/operations/:operation_handle/status
Verb: GETResponse 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: POSTResponse code: 200 OK
Execute a statement.
Path parameters
  • session_handle - The SessionHandle that identifies a session.

v2

/api_versions
Verb: GETResponse 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: GETResponse code: 200 OK
Get meta data for this cluster.
/sessions
Verb: POSTResponse 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: DELETEResponse code: 200 OK
Closes the specific session.
Path parameters
  • session_handle - The SessionHandle that identifies a session.
/sessions/:session_handle
Verb: GETResponse code: 200 OK
Get the session configuration.
Path parameters
  • session_handle - The SessionHandle that identifies a session.
/sessions/:session_handle/complete-statement
Verb: GETResponse 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: POSTResponse 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: POSTResponse 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: POSTResponse 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: DELETEResponse 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: GETResponse 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 token that identifies which batch of data to fetch.
Query parameters
  • rowFormat (mandatory): The row format to serialize the RowData.
/sessions/:session_handle/operations/:operation_handle/status
Verb: GETResponse 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: POSTResponse code: 200 OK
Execute a statement.
Path parameters
  • session_handle - The SessionHandle that identifies a session.

v1

/api_versions
Verb: GETResponse 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: GETResponse code: 200 OK
Get meta data for this cluster.
/sessions
Verb: POSTResponse 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: DELETEResponse code: 200 OK
Closes the specific session.
Path parameters
  • session_handle - The SessionHandle that identifies a session.
/sessions/:session_handle
Verb: GETResponse code: 200 OK
Get the session configuration.
Path parameters
  • session_handle - The SessionHandle that identifies a session.
/sessions/:session_handle/heartbeat
Verb: POSTResponse 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: POSTResponse 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: DELETEResponse 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: GETResponse 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 token that identifies which batch of data to fetch.
/sessions/:session_handle/operations/:operation_handle/status
Verb: GETResponse 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: POSTResponse 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