Interface Client
-
- All Superinterfaces:
AutoCloseable
,Closeable
public interface Client extends Closeable
A client that connects to a specific ksqlDB server.
-
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Modifier and Type Method Description void
close()
Closes the underlying HTTP client.static Client
create(ClientOptions clientOptions)
static Client
create(ClientOptions clientOptions, io.vertx.core.Vertx vertx)
CompletableFuture<Void>
createConnector(String connectorName, boolean isSource, Map<String,Object> properties)
Creates a connector.void
define(String variable, Object value)
Define a session variable which can be referenced in sql commands by wrapping the variable name with${}
.CompletableFuture<ConnectorDescription>
describeConnector(String connectorName)
Returns metadata about a connector.CompletableFuture<SourceDescription>
describeSource(String sourceName)
Returns metadata about the ksqlDB stream or table of the provided name.CompletableFuture<Void>
dropConnector(String connectorName)
Drops a connector.BatchedQueryResult
executeQuery(String sql)
Executes a query (push or pull) and returns all result rows in a single batch, once the query has completed.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.CompletableFuture<ExecuteStatementResult>
executeStatement(String sql)
Sends a SQL request to the ksqlDB server.CompletableFuture<ExecuteStatementResult>
executeStatement(String sql, Map<String,Object> properties)
Sends a SQL request with the specified properties to the ksqlDB server.Map<String,Object>
getVariables()
CompletableFuture<Void>
insertInto(String streamName, KsqlObject row)
Inserts a row into a ksqlDB stream.CompletableFuture<List<ConnectorInfo>>
listConnectors()
Returns a list of connectors.CompletableFuture<List<QueryInfo>>
listQueries()
Returns the list of queries currently running on the ksqlDB server.CompletableFuture<List<StreamInfo>>
listStreams()
Returns the list of ksqlDB streams from the ksqlDB server's metastore.CompletableFuture<List<TableInfo>>
listTables()
Returns the list of ksqlDB tables from the ksqlDB server's metastoreCompletableFuture<List<TopicInfo>>
listTopics()
Returns the list of Kafka topics available for use with ksqlDB.CompletableFuture<ServerInfo>
serverInfo()
Returns metadata about the ksqlDB server.CompletableFuture<AcksPublisher>
streamInserts(String streamName, org.reactivestreams.Publisher<KsqlObject> insertsPublisher)
Inserts rows into a ksqlDB stream.CompletableFuture<StreamedQueryResult>
streamQuery(String sql)
Executes a query (push or pull) and returns the results one row at a time.CompletableFuture<StreamedQueryResult>
streamQuery(String sql, Map<String,Object> properties)
Executes a query (push or pull) and returns the results one row at a time.CompletableFuture<Void>
terminatePushQuery(String queryId)
Terminates a push query with the specified query ID.void
undefine(String variable)
Undefine a session variable.
-
-
-
Method Detail
-
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 executeproperties
- 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 thestreamQuery(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 thestreamQuery(String, Map)
method instead.- Parameters:
sql
- statement of query to executeproperties
- 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 streamrow
- 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 aorg.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 streaminsertsPublisher
- 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 theCompletableFuture
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 theCompletableFuture
is completed.If a non-200 response is received from the server, the
CompletableFuture
will be failed.- Parameters:
sql
- the request to be executedproperties
- 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 metastoreIf 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 connectorisSource
- true if the connector is a source connector, false if it is a sink connectorproperties
- connector properties- 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
-
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
-
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 variablevalue
- 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 interfaceAutoCloseable
- Specified by:
close
in interfaceCloseable
-
create
static Client create(ClientOptions clientOptions)
-
create
static Client create(ClientOptions clientOptions, io.vertx.core.Vertx vertx)
-
-