REST Endpoint #

The REST endpoint allows user to connect to SQL Gateway with REST API.

Overview of SQL Processing #

Open Session #

When the client connects to the SQL Gateway, the SQL Gateway creates a Session as the context to store the users-specified information during the interactions between the client and SQL Gateway. After the creation of the Session, the SQL Gateway server returns an identifier named SessionHandle for later interactions.

Submit SQL #

After the registration of the Session, the client can submit the SQL to the SQL Gateway server. When submitting the SQL, the SQL is translated to an Operation and an identifier named OperationHandle is returned for fetch results later. The Operation has its lifecycle, the client is able to cancel the execution of the Operation or close the Operation to release the resources used by the Operation.

Fetch Results #

With the OperationHandle, the client can fetch the results from the Operation. If the Operation is ready, the SQL Gateway will return a batch of the data with the corresponding schema and a URI that is used to fetch the next batch of the data. When all results have been fetched, the SQL Gateway will fill the resultType in the response with value EOS and the URI to the next batch of the data is null.

Endpoint Options #

Key	Default	Type	Description
sql-gateway.endpoint.rest.address	(none)	String	The address that should be used by clients to connect to the sql gateway server.
sql-gateway.endpoint.rest.bind-address	(none)	String	The address that the sql gateway server binds itself.
sql-gateway.endpoint.rest.bind-port	"8083"	String	The port that the sql gateway server binds itself. Accepts a list of ports (“50100,50101”), ranges (“50100-50200”) or a combination of both. It is recommended to set a range of ports to avoid collisions when multiple sql gateway servers are running on the same machine.
sql-gateway.endpoint.rest.port	8083	Integer	The port that the client connects to. If bind-port has not been specified, then the sql gateway server will bind to this port.

REST API #

The available OpenAPI specification is as follows. The default version is v3.

Version	Description
Open API v1 specification	Allow users to submit statements to the gateway and execute.
Open API v2 specification	Supports SQL Client to connect to the gateway.
Open API v3 specification	Supports Materialized Table refresh operation.

The OpenAPI specification is still experimental.

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 #

Currently, REST endpoint supports to serialize the RowData with query parameter rowFormat. REST endpoint uses JSON format to serialize the Table Objects. Please refer JSON format to the mappings.

REST endpoint also supports to serialize the RowData with PLAIN_TEXT format that automatically cast all columns to the 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 #