This documentation is for an unreleased version of Apache Flink. We recommend you use the latest stable version .
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
#
客户端可以通过 OperationHandle 从 Operation 获取结果。当一个 Operation 已经就绪，SQL Gateway 将返回一个包含对应 schema 和 URI 的批式数据，
URI 可以被用来获取下一个批式数据。当所有结果已经获取完成，SQL Gateway 会将结果中的 resultType 设置为 EOS，并且将获取下一个批式数据的 URI 设置为 null。
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。
OpenAPI 规范目前仍处于实验阶段。
API reference
#
v2
/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.
Request
{}
Response
{
"type" : "object",
"id" : "urn:jsonschema:org:apache:flink:table:gateway:rest:message:util:GetApiVersionResponseBody",
"properties" : {
"versions" : {
"type" : "array",
"items" : {
"type" : "string"
}
}
}
}
/info
Verb: GET
Response code: 200 OK
Get meta data for this cluster.
Request
{}
Response
{
"type" : "object",
"id" : "urn:jsonschema:org:apache:flink:table:gateway:rest:message:util:GetInfoResponseBody",
"properties" : {
"productName" : {
"type" : "string"
},
"version" : {
"type" : "string"
}
}
}
/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.
Request
{
"type" : "object",
"id" : "urn:jsonschema:org:apache:flink:table:gateway:rest:message:session:OpenSessionRequestBody",
"properties" : {
"properties" : {
"type" : "object",
"additionalProperties" : {
"type" : "string"
}
},
"sessionName" : {
"type" : "string"
}
}
}
Response
{
"type" : "object",
"id" : "urn:jsonschema:org:apache:flink:table:gateway:rest:message:session:OpenSessionResponseBody",
"properties" : {
"sessionHandle" : {
"type" : "string"
}
}
}
/sessions/:session_handle
Verb: DELETE
Response code: 200 OK
Closes the specific session.
Path parameters
session_handle - The SessionHandle that identifies a session.
Request
{}
Response
{
"type" : "object",
"id" : "urn:jsonschema:org:apache:flink:table:gateway:rest:message:session:CloseSessionResponseBody",
"properties" : {
"status" : {
"type" : "string"
}
}
}
/sessions/:session_handle
Verb: GET
Response code: 200 OK
Get the session configuration.
Path parameters
session_handle - The SessionHandle that identifies a session.
Request
{}
Response
{
"type" : "object",
"id" : "urn:jsonschema:org:apache:flink:table:gateway:rest:message:session:GetSessionConfigResponseBody",
"properties" : {
"properties" : {
"type" : "object",
"additionalProperties" : {
"type" : "string"
}
}
}
}
/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.
Request
{
"type" : "object",
"id" : "urn:jsonschema:org:apache:flink:table:gateway:rest:message:statement:CompleteStatementRequestBody",
"properties" : {
"position" : {
"type" : "integer"
},
"statement" : {
"type" : "string"
}
}
}
Response
{
"type" : "object",
"id" : "urn:jsonschema:org:apache:flink:table:gateway:rest:message:statement:CompleteStatementResponseBody",
"properties" : {
"candidates" : {
"type" : "array",
"items" : {
"type" : "string"
}
}
}
}
/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.
Request
{
"type" : "object",
"id" : "urn:jsonschema:org:apache:flink:table:gateway:rest:message:session:ConfigureSessionRequestBody",
"properties" : {
"executionTimeout" : {
"type" : "integer"
},
"statement" : {
"type" : "string"
}
}
}
Response
{}
/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.
Request
{}
Response
{}
/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.
Request
{}
Response
{
"type" : "object",
"id" : "urn:jsonschema:org:apache:flink:table:gateway:rest:message:operation:OperationStatusResponseBody",
"properties" : {
"status" : {
"type" : "string"
}
}
}
/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.
Request
{}
Response
{
"type" : "object",
"id" : "urn:jsonschema:org:apache:flink:table:gateway:rest:message:operation:OperationStatusResponseBody",
"properties" : {
"status" : {
"type" : "string"
}
}
}
/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.
Request
{}
Response
{
"type" : "any"
}
/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.
Request
{}
Response
{
"type" : "object",
"id" : "urn:jsonschema:org:apache:flink:table:gateway:rest:message:operation:OperationStatusResponseBody",
"properties" : {
"status" : {
"type" : "string"
}
}
}
/sessions/:session_handle/statements
Verb: POST
Response code: 200 OK
Execute a statement.
Path parameters
session_handle - The SessionHandle that identifies a session.
Request
{
"type" : "object",
"id" : "urn:jsonschema:org:apache:flink:table:gateway:rest:message:statement:ExecuteStatementRequestBody",
"properties" : {
"executionConfig" : {
"type" : "object",
"additionalProperties" : {
"type" : "string"
}
},
"executionTimeout" : {
"type" : "integer"
},
"statement" : {
"type" : "string"
}
}
}
Response
{
"type" : "object",
"id" : "urn:jsonschema:org:apache:flink:table:gateway:rest:message:statement:ExecuteStatementResponseBody",
"properties" : {
"operationHandle" : {
"type" : "string"
}
}
}
v1
/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.
Request
{}
Response
{
"type" : "object",
"id" : "urn:jsonschema:org:apache:flink:table:gateway:rest:message:util:GetApiVersionResponseBody",
"properties" : {
"versions" : {
"type" : "array",
"items" : {
"type" : "string"
}
}
}
}
/info
Verb: GET
Response code: 200 OK
Get meta data for this cluster.
Request
{}
Response
{
"type" : "object",
"id" : "urn:jsonschema:org:apache:flink:table:gateway:rest:message:util:GetInfoResponseBody",
"properties" : {
"productName" : {
"type" : "string"
},
"version" : {
"type" : "string"
}
}
}
/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.
Request
{
"type" : "object",
"id" : "urn:jsonschema:org:apache:flink:table:gateway:rest:message:session:OpenSessionRequestBody",
"properties" : {
"properties" : {
"type" : "object",
"additionalProperties" : {
"type" : "string"
}
},
"sessionName" : {
"type" : "string"
}
}
}
Response
{
"type" : "object",
"id" : "urn:jsonschema:org:apache:flink:table:gateway:rest:message:session:OpenSessionResponseBody",
"properties" : {
"sessionHandle" : {
"type" : "string"
}
}
}
/sessions/:session_handle
Verb: DELETE
Response code: 200 OK
Closes the specific session.
Path parameters
session_handle - The SessionHandle that identifies a session.
Request
{}
Response
{
"type" : "object",
"id" : "urn:jsonschema:org:apache:flink:table:gateway:rest:message:session:CloseSessionResponseBody",
"properties" : {
"status" : {
"type" : "string"
}
}
}
/sessions/:session_handle
Verb: GET
Response code: 200 OK
Get the session configuration.
Path parameters
session_handle - The SessionHandle that identifies a session.
Request
{}
Response
{
"type" : "object",
"id" : "urn:jsonschema:org:apache:flink:table:gateway:rest:message:session:GetSessionConfigResponseBody",
"properties" : {
"properties" : {
"type" : "object",
"additionalProperties" : {
"type" : "string"
}
}
}
}
/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.
Request
{}
Response
{}
/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.
Request
{}
Response
{
"type" : "object",
"id" : "urn:jsonschema:org:apache:flink:table:gateway:rest:message:operation:OperationStatusResponseBody",
"properties" : {
"status" : {
"type" : "string"
}
}
}
/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.
Request
{}
Response
{
"type" : "object",
"id" : "urn:jsonschema:org:apache:flink:table:gateway:rest:message:operation:OperationStatusResponseBody",
"properties" : {
"status" : {
"type" : "string"
}
}
}
/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.
Request
{}
Response
{
"type" : "any"
}
/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.
Request
{}
Response
{
"type" : "object",
"id" : "urn:jsonschema:org:apache:flink:table:gateway:rest:message:operation:OperationStatusResponseBody",
"properties" : {
"status" : {
"type" : "string"
}
}
}
/sessions/:session_handle/statements
Verb: POST
Response code: 200 OK
Execute a statement.
Path parameters
session_handle - The SessionHandle that identifies a session.
Request
{
"type" : "object",
"id" : "urn:jsonschema:org:apache:flink:table:gateway:rest:message:statement:ExecuteStatementRequestBody",
"properties" : {
"executionConfig" : {
"type" : "object",
"additionalProperties" : {
"type" : "string"
}
},
"executionTimeout" : {
"type" : "integer"
},
"statement" : {
"type" : "string"
}
}
}
Response
{
"type" : "object",
"id" : "urn:jsonschema:org:apache:flink:table:gateway:rest:message:statement:ExecuteStatementResponseBody",
"properties" : {
"operationHandle" : {
"type" : "string"
}
}
}
Data Type Mapping
#
目前 REST endpoint 支持使用查询参数 rowFormat 序列化 RowData。REST endpoint 使用 JSON 序列化 Table 对象。
请参考 JSON format 查看类型映射关系。
REST endpoint 也支持 PLAIN_TEXT 序列化 RowData，将所有列自动转换成 String。
