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 规范如下，默认版本是 v3。

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

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.
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/materialized-tables/:identifier/refresh
Verb: `POST`	Response 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.
Request { "type" : "object", "id" : "urn:jsonschema:org:apache:flink:table:gateway:rest:message:materializedtable:RefreshMaterializedTableRequestBody", "properties" : { "dynamicOptions" : { "type" : "object", "additionalProperties" : { "type" : "string" } }, "executionConfig" : { "type" : "object", "additionalProperties" : { "type" : "string" } }, "isPeriodic" : { "type" : "boolean" }, "periodic" : { "type" : "boolean" }, "scheduleTime" : { "type" : "string" }, "staticPartitions" : { "type" : "object", "additionalProperties" : { "type" : "string" } } } }
Response `{ "type" : "object", "id" : "urn:jsonschema:org:apache:flink:table:gateway:rest:message:materializedtable:RefreshMaterializedTableResponseBody", "properties" : { "operationHandle" : { "type" : "string" } } }`

/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 token that identifies which batch of data to fetch.
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" } } }`

/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 token that identifies which batch of data to fetch.
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" } } }`

/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 token that identifies which batch of data to fetch.
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。

REST Endpoint #

Overview of SQL Processing #

Open Session #

Submit SQL #

Fetch Results #

Endpoint Options #

sql-gateway.endpoint.rest.address

sql-gateway.endpoint.rest.bind-address

sql-gateway.endpoint.rest.bind-port

sql-gateway.endpoint.rest.port

REST API #

API reference #

/api_versions

/info

/sessions

/sessions/:session_handle

/sessions/:session_handle

/sessions/:session_handle/complete-statement

/sessions/:session_handle/configure-session

/sessions/:session_handle/heartbeat

/sessions/:session_handle/materialized-tables/:identifier/refresh

/sessions/:session_handle/operations/:operation_handle/cancel

/sessions/:session_handle/operations/:operation_handle/close

/sessions/:session_handle/operations/:operation_handle/result/:token

/sessions/:session_handle/operations/:operation_handle/status

/sessions/:session_handle/statements

/api_versions

/info

/sessions

/sessions/:session_handle

/sessions/:session_handle

/sessions/:session_handle/complete-statement

/sessions/:session_handle/configure-session

/sessions/:session_handle/heartbeat

/sessions/:session_handle/operations/:operation_handle/cancel

/sessions/:session_handle/operations/:operation_handle/close

/sessions/:session_handle/operations/:operation_handle/result/:token

/sessions/:session_handle/operations/:operation_handle/status

/sessions/:session_handle/statements

/api_versions

/info

/sessions

/sessions/:session_handle

/sessions/:session_handle

/sessions/:session_handle/heartbeat

/sessions/:session_handle/operations/:operation_handle/cancel

/sessions/:session_handle/operations/:operation_handle/close

/sessions/:session_handle/operations/:operation_handle/result/:token

/sessions/:session_handle/operations/:operation_handle/status

/sessions/:session_handle/statements

Data Type Mapping #