org.apache.flink.table.gateway.api

Interface SqlGatewayService

@PublicEvolving
public interface SqlGatewayService

A service of SQL gateway is responsible for handling requests from the endpoints.

Method Summary

Modifier and Type	Method and Description
void	cancelOperation(SessionHandle sessionHandle, OperationHandle operationHandle) Cancel the operation when it is not in terminal status.
void	closeOperation(SessionHandle sessionHandle, OperationHandle operationHandle) Close the operation and release all used resource by the operation.
void	closeSession(SessionHandle sessionHandle) Close the Session.
List<String>	completeStatement(SessionHandle sessionHandle, String statement, int position) Returns a list of completion hints for the given statement at the given position.
void	configureSession(SessionHandle sessionHandle, String statement, long executionTimeoutMs) Using the statement to initialize the Session.
OperationHandle	executeStatement(SessionHandle sessionHandle, String statement, long executionTimeoutMs, org.apache.flink.configuration.Configuration executionConfig) Execute the submitted statement.
ResultSet	fetchResults(SessionHandle sessionHandle, OperationHandle operationHandle, FetchOrientation orientation, int maxRows) Fetch the results from the operation.
ResultSet	fetchResults(SessionHandle sessionHandle, OperationHandle operationHandle, long token, int maxRows) Fetch the results from the operation.
String	getCurrentCatalog(SessionHandle sessionHandle) Return current catalog name.
org.apache.flink.table.functions.FunctionDefinition	getFunctionDefinition(SessionHandle sessionHandle, org.apache.flink.table.catalog.UnresolvedIdentifier functionIdentifier) Get the specific definition of the function.
GatewayInfo	getGatewayInfo() Get the info about the SqlGatewayService.
OperationInfo	getOperationInfo(SessionHandle sessionHandle, OperationHandle operationHandle) Get the OperationInfo of the operation.
org.apache.flink.table.catalog.ResolvedSchema	getOperationResultSchema(SessionHandle sessionHandle, OperationHandle operationHandle) Get the result schema for the specified Operation.
Map<String,String>	getSessionConfig(SessionHandle sessionHandle) Get the current configuration of the Session.
EndpointVersion	getSessionEndpointVersion(SessionHandle sessionHandle) Get endpoint version that is negotiated in the openSession.
org.apache.flink.table.catalog.ResolvedCatalogBaseTable<?>	getTable(SessionHandle sessionHandle, org.apache.flink.table.catalog.ObjectIdentifier tableIdentifier) Return table of the given fully qualified name.
Set<String>	listCatalogs(SessionHandle sessionHandle) Return all available catalogs in the current session.
Set<String>	listDatabases(SessionHandle sessionHandle, String catalogName) Return all available schemas in the given catalog.
Set<FunctionInfo>	listSystemFunctions(SessionHandle sessionHandle) List all available system functions.
Set<TableInfo>	listTables(SessionHandle sessionHandle, String catalogName, String databaseName, Set<org.apache.flink.table.catalog.CatalogBaseTable.TableKind> tableKinds) Return all available tables/views in the given catalog and database.
Set<FunctionInfo>	listUserDefinedFunctions(SessionHandle sessionHandle, String catalogName, String databaseName) List all user defined functions.
SessionHandle	openSession(SessionEnvironment environment) Open the Session.
OperationHandle	submitOperation(SessionHandle sessionHandle, Callable<ResultSet> executor) Submit an operation and execute.

Method Detail

openSession

SessionHandle openSession(SessionEnvironment environment)
                   throws SqlGatewayException

Open the Session.

Parameters:

environment - Environment to initialize the Session.

Returns:

Returns a handle that used to identify the Session.

Throws:

SqlGatewayException

closeSession

void closeSession(SessionHandle sessionHandle)
           throws SqlGatewayException

Close the Session.

Parameters:

sessionHandle - handle to identify the Session needs to be closed.

Throws:

SqlGatewayException

configureSession

void configureSession(SessionHandle sessionHandle,
                      String statement,
                      long executionTimeoutMs)
               throws SqlGatewayException

Using the statement to initialize the Session. It's only allowed to execute SET/RESET/CREATE/DROP/USE/ALTER/LOAD MODULE/UNLOAD MODULE/ADD JAR.

It returns until the execution finishes.

Parameters:

sessionHandle - handle to identify the session.

statement - the statement used to configure the session.

executionTimeoutMs - the execution timeout. Please use non-positive value to forbid the timeout mechanism.

Throws:

SqlGatewayException

getSessionConfig

Map<String,String> getSessionConfig(SessionHandle sessionHandle)
                             throws SqlGatewayException

Get the current configuration of the Session.

Parameters:

sessionHandle - handle to identify the session.

Returns:

Returns configuration of the session.

Throws:

SqlGatewayException

getSessionEndpointVersion

EndpointVersion getSessionEndpointVersion(SessionHandle sessionHandle)
                                   throws SqlGatewayException

Get endpoint version that is negotiated in the openSession.

Parameters:

sessionHandle - handle to identify the session.

Returns:

Returns the version.

Throws:

SqlGatewayException

submitOperation

OperationHandle submitOperation(SessionHandle sessionHandle,
                                Callable<ResultSet> executor)
                         throws SqlGatewayException

Submit an operation and execute. The SqlGatewayService will take care of the execution and assign the OperationHandle for later to retrieve the results.

Parameters:

sessionHandle - handle to identify the session.

executor - the main logic to get the execution results.

Returns:

Returns the handle for later retrieve results.

Throws:

SqlGatewayException

cancelOperation

void cancelOperation(SessionHandle sessionHandle,
                     OperationHandle operationHandle)
              throws SqlGatewayException

Cancel the operation when it is not in terminal status.

It can't cancel an Operation if it is terminated.

Parameters:

sessionHandle - handle to identify the session.

operationHandle - handle to identify the operation.JarURLConnection

Throws:

SqlGatewayException

closeOperation

void closeOperation(SessionHandle sessionHandle,
                    OperationHandle operationHandle)
             throws SqlGatewayException

Close the operation and release all used resource by the operation.

Parameters:

sessionHandle - handle to identify the session.

operationHandle - handle to identify the operation.

Throws:

SqlGatewayException

getOperationInfo

OperationInfo getOperationInfo(SessionHandle sessionHandle,
                               OperationHandle operationHandle)
                        throws SqlGatewayException

Get the OperationInfo of the operation.

Parameters:

sessionHandle - handle to identify the session.

operationHandle - handle to identify the operation.

Throws:

SqlGatewayException

getOperationResultSchema

org.apache.flink.table.catalog.ResolvedSchema getOperationResultSchema(SessionHandle sessionHandle,
                                                                       OperationHandle operationHandle)
                                                                throws SqlGatewayException

Get the result schema for the specified Operation.

Note: The result schema is available when the Operation is in the OperationStatus.FINISHED.

Parameters:

sessionHandle - handle to identify the session.

operationHandle - handle to identify the operation.

Throws:

SqlGatewayException

executeStatement

OperationHandle executeStatement(SessionHandle sessionHandle,
                                 String statement,
                                 long executionTimeoutMs,
                                 org.apache.flink.configuration.Configuration executionConfig)
                          throws SqlGatewayException

Execute the submitted statement.

Parameters:

sessionHandle - handle to identify the session.

statement - the SQL to execute.

executionTimeoutMs - the execution timeout. Please use non-positive value to forbid the timeout mechanism.

executionConfig - execution config for the statement.

Returns:

handle to identify the operation.

Throws:

SqlGatewayException

fetchResults

ResultSet fetchResults(SessionHandle sessionHandle,
                       OperationHandle operationHandle,
                       long token,
                       int maxRows)
                throws SqlGatewayException

Fetch the results from the operation. When maxRows is Integer.MAX_VALUE, it means to fetch all available data.

Parameters:

sessionHandle - handle to identify the session.

operationHandle - handle to identify the operation.

token - token to identify results.

maxRows - max number of rows to fetch.

Returns:

Returns the results.

Throws:

SqlGatewayException

fetchResults

ResultSet fetchResults(SessionHandle sessionHandle,
                       OperationHandle operationHandle,
                       FetchOrientation orientation,
                       int maxRows)
                throws SqlGatewayException

Fetch the results from the operation. When maxRows is Integer.MAX_VALUE, it means to fetch all available data. It promises to return at least one rows if the results is not end-of-stream.

Parameters:

sessionHandle - handle to identify the session.

operationHandle - handle to identify the operation.

orientation - orientation to fetch the results.

maxRows - max number of rows to fetch.

Returns:

Returns the results.

Throws:

SqlGatewayException

getCurrentCatalog

String getCurrentCatalog(SessionHandle sessionHandle)
                  throws SqlGatewayException

Return current catalog name.

Parameters:

sessionHandle - handle to identify the session.

Returns:

name of the current catalog.

Throws:

SqlGatewayException

listCatalogs

Set<String> listCatalogs(SessionHandle sessionHandle)
                  throws SqlGatewayException

Return all available catalogs in the current session.

Parameters:

sessionHandle - handle to identify the session.

Returns:

names of the registered catalogs.

Throws:

SqlGatewayException

listDatabases

Set<String> listDatabases(SessionHandle sessionHandle,
                          String catalogName)
                   throws SqlGatewayException

Return all available schemas in the given catalog.

Parameters:

sessionHandle - handle to identify the session.

catalogName - name string of the given catalog.

Returns:

names of the registered schemas.

Throws:

SqlGatewayException

listTables

Set<TableInfo> listTables(SessionHandle sessionHandle,
                          String catalogName,
                          String databaseName,
                          Set<org.apache.flink.table.catalog.CatalogBaseTable.TableKind> tableKinds)
                   throws SqlGatewayException

Return all available tables/views in the given catalog and database.

Parameters:

sessionHandle - handle to identify the session.

catalogName - name of the given catalog.

databaseName - name of the given database.

tableKinds - used to specify the type of return values.

Returns:

table info of the registered tables/views.

Throws:

SqlGatewayException

getTable

org.apache.flink.table.catalog.ResolvedCatalogBaseTable<?> getTable(SessionHandle sessionHandle,
                                                                    org.apache.flink.table.catalog.ObjectIdentifier tableIdentifier)
                                                             throws SqlGatewayException

Return table of the given fully qualified name.

Parameters:

sessionHandle - handle to identify the session.

tableIdentifier - fully qualified name of the table.

Returns:

information of the table.

Throws:

SqlGatewayException

listUserDefinedFunctions

Set<FunctionInfo> listUserDefinedFunctions(SessionHandle sessionHandle,
                                           String catalogName,
                                           String databaseName)
                                    throws SqlGatewayException

List all user defined functions.

Parameters:

sessionHandle - handle to identify the session.

catalogName - name string of the given catalog.

databaseName - name string of the given database.

Returns:

user defined functions info.

Throws:

SqlGatewayException

listSystemFunctions

Set<FunctionInfo> listSystemFunctions(SessionHandle sessionHandle)
                               throws SqlGatewayException

List all available system functions.

Parameters:

sessionHandle - handle to identify the session.

Returns:

system functions info.

Throws:

SqlGatewayException

getFunctionDefinition

org.apache.flink.table.functions.FunctionDefinition getFunctionDefinition(SessionHandle sessionHandle,
                                                                          org.apache.flink.table.catalog.UnresolvedIdentifier functionIdentifier)
                                                                   throws SqlGatewayException

Get the specific definition of the function. If the input identifier only contains the function name, it is resolved with the order of the temporary system function, system function, temporary function and catalog function.

Parameters:

sessionHandle - handle to identify the session.

functionIdentifier - identifier of the function.

Returns:

the definition of the function.

Throws:

SqlGatewayException

getGatewayInfo

GatewayInfo getGatewayInfo()

Get the info about the SqlGatewayService.

Returns:

Returns gateway info.

completeStatement

List<String> completeStatement(SessionHandle sessionHandle,
                               String statement,
                               int position)
                        throws SqlGatewayException

Returns a list of completion hints for the given statement at the given position.

Parameters:

sessionHandle - handle to identify the session.

statement - sql statement to be completed.

position - position of where need completion hints.

Returns:

completion hints.

Throws:

SqlGatewayException