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。
我的书签
添加书签
移除书签
