Package io.confluent.ksql.api.client

Interface Client

All Superinterfaces:
AutoCloseable, Closeable
public interface Client extends Closeable
A client that connects to a specific ksqlDB server.

  • Method Details

    • streamQuery

      CompletableFuture<StreamedQueryResult> streamQuery(String sql)
      Executes a query (push or pull) and returns the results one row at a time.

      This method may be used to issue both push and pull queries, but the usage pattern is better for push queries. For pull queries, consider using the executeQuery(String) method instead.

      If a non-200 response is received from the server, the CompletableFuture will be failed.

      Parameters:
      sql - statement of query to execute
      Returns:
      a future that completes once the server response is received, and contains the query result if successful

    • streamQuery

      CompletableFuture<StreamedQueryResult> streamQuery(String sql, Map<String,Object> properties)
      Executes a query (push or pull) and returns the results one row at a time.

      This method may be used to issue both push and pull queries, but the usage pattern is better for push queries. For pull queries, consider using the executeQuery(String, Map) method instead.

      If a non-200 response is received from the server, the CompletableFuture will be failed.

      Parameters:
      sql - statement of query to execute
      properties - query properties
      Returns:
      a future that completes once the server response is received, and contains the query result if successful

    • executeQuery

      BatchedQueryResult executeQuery(String sql)
      Executes a query (push or pull) and returns all result rows in a single batch, once the query has completed.

      This method is suitable for both pull queries and for terminating push queries, for example, queries that have a LIMIT clause. For non-terminating push queries, use the streamQuery(String) method instead.

      Parameters:
      sql - statement of query to execute
      Returns:
      query result

    • executeQuery

      BatchedQueryResult executeQuery(String sql, Map<String,Object> properties)
      Executes a query (push or pull) and returns all result rows in a single batch, once the query has completed.

      This method is suitable for both pull queries and for terminating push queries, for example, queries that have a LIMIT clause. For non-terminating push queries, use the streamQuery(String, Map) method instead.

      Parameters:
      sql - statement of query to execute
      properties - query properties
      Returns:
      query result

    • insertInto

      CompletableFuture<Void> insertInto(String streamName, KsqlObject row)
      Inserts a row into a ksqlDB stream.

      The CompletableFuture will be failed if a non-200 response is received from the server, or if the server encounters an error while processing the insertion.

      Parameters:
      streamName - name of the target stream
      row - the row to insert. Keys are column names and values are column values.
      Returns:
      a future that completes once the server response is received

    • streamInserts

      CompletableFuture<AcksPublisher> streamInserts(String streamName, org.reactivestreams.Publisher<KsqlObject> insertsPublisher)
      Inserts rows into a ksqlDB stream. Rows to insert are supplied by a org.reactivestreams.Publisher and server acknowledgments are exposed similarly.

      The CompletableFuture will be failed if a non-200 response is received from the server.

      See InsertsPublisher for an example publisher that may be passed an argument to this method.

      Parameters:
      streamName - name of the target stream
      insertsPublisher - the publisher to provide rows to insert
      Returns:
      a future that completes once the initial server response is received, and contains a publisher that publishes server acknowledgments for inserted rows.

    • terminatePushQuery

      CompletableFuture<Void> terminatePushQuery(String queryId)
      Terminates a push query with the specified query ID.

      If a non-200 response is received from the server, the CompletableFuture will be failed.

      Parameters:
      queryId - ID of the query to terminate
      Returns:
      a future that completes once the server response is received

    • executeStatement

      CompletableFuture<ExecuteStatementResult> executeStatement(String sql)
      Sends a SQL request to the ksqlDB server. This method supports 'CREATE', 'CREATE ... AS SELECT', 'DROP', 'TERMINATE', and 'INSERT INTO ... AS SELECT' statements.

      Each request should contain exactly one statement. Requests that contain multiple statements will be rejected by the client, in the form of failing the CompletableFuture, and the request will not be sent to the server.

      The CompletableFuture is completed once a response is received from the server. Note that the actual execution of the submitted statement is asynchronous, so the statement may not have been executed by the time the CompletableFuture is completed.

      If a non-200 response is received from the server, the CompletableFuture will be failed.

      Parameters:
      sql - the request to be executed
      Returns:
      a future that completes once the server response is received, and contains the query ID for statements that start new persistent queries

    • executeStatement

      CompletableFuture<ExecuteStatementResult> executeStatement(String sql, Map<String,Object> properties)
      Sends a SQL request with the specified properties to the ksqlDB server. This method supports 'CREATE', 'CREATE ... AS SELECT', 'DROP', 'TERMINATE', and 'INSERT INTO ... AS SELECT' statements.

      Each request should contain exactly one statement. Requests that contain multiple statements will be rejected by the client, in the form of failing the CompletableFuture, and the request will not be sent to the server.

      The CompletableFuture is completed once a response is received from the server. Note that the actual execution of the submitted statement is asynchronous, so the statement may not have been executed by the time the CompletableFuture is completed.

      If a non-200 response is received from the server, the CompletableFuture will be failed.

      Parameters:
      sql - the request to be executed
      properties - properties associated with the request
      Returns:
      a future that completes once the server response is received, and contains the query ID for statements that start new persistent queries

    • listStreams

      CompletableFuture<List<StreamInfo>> listStreams()
      Returns the list of ksqlDB streams from the ksqlDB server's metastore.

      If a non-200 response is received from the server, the CompletableFuture will be failed.

      Returns:
      list of streams

    • listTables

      CompletableFuture<List<TableInfo>> listTables()
      Returns the list of ksqlDB tables from the ksqlDB server's metastore

      If a non-200 response is received from the server, the CompletableFuture will be failed.

      Returns:
      list of tables

    • listTopics

      CompletableFuture<List<TopicInfo>> listTopics()
      Returns the list of Kafka topics available for use with ksqlDB.

      If a non-200 response is received from the server, the CompletableFuture will be failed.

      Returns:
      list of topics

    • listQueries

      CompletableFuture<List<QueryInfo>> listQueries()
      Returns the list of queries currently running on the ksqlDB server.

      If a non-200 response is received from the server, the CompletableFuture will be failed.

      Returns:
      list of queries

    • describeSource

      CompletableFuture<SourceDescription> describeSource(String sourceName)
      Returns metadata about the ksqlDB stream or table of the provided name.

      If a non-200 response is received from the server, the CompletableFuture will be failed.

      Parameters:
      sourceName - stream or table name
      Returns:
      metadata for stream or table

    • serverInfo

      CompletableFuture<ServerInfo> serverInfo()
      Returns metadata about the ksqlDB server.

      If a non-200 response is received from the server, the CompletableFuture will be failed.

      Returns:
      metadata for server

    • createConnector

      CompletableFuture<Void> createConnector(String connectorName, boolean isSource, Map<String,Object> properties)
      Creates a connector.

      If a non-200 response is received from the server, the CompletableFuture will be failed.

      Parameters:
      connectorName - name of the connector
      isSource - true if the connector is a source connector, false if it is a sink connector
      properties - connector properties
      Returns:
      result of connector creation

    • createConnector

      CompletableFuture<Void> createConnector(String connectorName, boolean isSource, Map<String,Object> properties, boolean ifNotExists)
      Creates a connector.

      If a non-200 response is received from the server, the CompletableFuture will be failed.

      Parameters:
      connectorName - name of the connector
      isSource - true if the connector is a source connector, false if it is a sink connector
      properties - connector properties
      ifNotExists - is ifNotExists is set to true, then the command won't fail if a connector with the same name already exists
      Returns:
      result of connector creation

    • dropConnector

      CompletableFuture<Void> dropConnector(String connectorName)
      Drops a connector.

      If a non-200 response is received from the server, the CompletableFuture will be failed.

      Parameters:
      connectorName - name of the connector to drop
      Returns:
      a future that completes once the server response is received

    • dropConnector

      CompletableFuture<Void> dropConnector(String connectorName, boolean ifExists)
      Drops a connector.

      If a non-200 response is received from the server, the CompletableFuture will be failed.

      Parameters:
      connectorName - name of the connector to drop
      ifExists - ifExists is set to true, then the statement won't fail if the connector does not exist
      Returns:
      a future that completes once the server response is received

    • listConnectors

      CompletableFuture<List<ConnectorInfo>> listConnectors()
      Returns a list of connectors.

      If a non-200 response is received from the server, the CompletableFuture will be failed.

      Returns:
      a list of connectors

    • describeConnector

      CompletableFuture<ConnectorDescription> describeConnector(String connectorName)
      Returns metadata about a connector.

      If a non-200 response is received from the server, the CompletableFuture will be failed.

      Parameters:
      connectorName - name of the connector to describe
      Returns:
      metadata about connector

    • buildRequest

      Client.HttpRequest buildRequest(String method, String path)
      A factory to construct Client.HttpRequest objects. Instances of Client.HttpRequest are used to make direct HTTP requests to ksqlDB server's REST API.
      Parameters:
      method - the http verb (for example, "get", "put"). the input is case-sensitive and may not be null.
      path - a non-null URL path
      Returns:
      a future that completes with a Client.HttpResponse if the http request completes or throws an exception for low level network errors

    • define

      void define(String variable, Object value)
      Define a session variable which can be referenced in sql commands by wrapping the variable name with ${}.

      If the variable is already defined, the existing value will be overridden.

      Parameters:
      variable - the name of the variable
      value - the value represented by the variable

    • undefine

      void undefine(String variable)
      Undefine a session variable. '${<variable name>}' will no longer be replaced in other functions.

      If the variable is not defined, then this method call is a no-op.

      Parameters:
      variable - the name of the variable to undefine

    • getVariables

      Map<String,Object> getVariables()
      Returns:
      a map of the session variables and values used for variable substitution.

    • close

      void close()
      Closes the underlying HTTP client.
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable

    • create

      static Client create(ClientOptions clientOptions)

    • create

      static Client create(ClientOptions clientOptions, io.vertx.core.Vertx vertx)