Package 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 Details

    • 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

    • refreshMaterializedTable

      OperationHandle refreshMaterializedTable(SessionHandle sessionHandle, String materializedTableIdentifier, boolean isPeriodic, @Nullable String scheduleTime, Map<String,String> dynamicOptions, Map<String,String> staticPartitions, Map<String,String> executionConfig)
      Trigger a refresh operation of specific materialized table.
      Parameters:
      sessionHandle - handle to identify the session.
      materializedTableIdentifier - A fully qualified materialized table identifier: 'catalogName.databaseName.objectName', used for locating the materialized table in catalog.
      isPeriodic - Represents whether the workflow is refreshed periodically or one-time-only.
      scheduleTime - The time point at which the scheduler triggers this refresh operation.
      staticPartitions - The specific partitions for one-time-only refresh workflow.
      executionConfig - The flink job config.
      Returns:
      handle to identify the operation.

    • deployScript

      <ClusterID> ClusterID deployScript(SessionHandle sessionHandle, @Nullable URI scriptUri, @Nullable String script, org.apache.flink.configuration.Configuration executionConfig) throws SqlGatewayException
      Deploy the script in application mode.
      Parameters:
      sessionHandle - handle to identify the session.
      scriptUri - URI of the script.
      script - the content of the script.
      executionConfig - to run the script.
      Returns:
      the cluster description.
      Throws:
      SqlGatewayException