Interface Client
-
- All Superinterfaces:
AutoCloseable
,Closeable
public interface Client extends Closeable
A client that connects to a specific ksqlDB server.
-
-
Nested Class Summary
Nested Classes Modifier and Type Interface Description static interface
Client.HttpRequest
Instances ofClient.HttpRequest
are used to make direct HTTP requests to ksqlDB server's REST API.static interface
Client.HttpResponse
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Modifier and Type Method Description CompletableFuture<Void>
assertSchema(int id, boolean exists)
Asserts the existence of a schema with the given id.CompletableFuture<Void>
assertSchema(int id, boolean exists, Duration timeout)
Asserts the existence of a schema with the given id within the specified timeout.CompletableFuture<Void>
assertSchema(String subject, boolean exists)
Asserts the existence of a schema with the given subject name.CompletableFuture<Void>
assertSchema(String subject, boolean exists, Duration timeout)
Asserts the existence of a schema with the given subject name within the specified timeout.CompletableFuture<Void>
assertSchema(String subject, int id, boolean exists)
Asserts the existence of a schema with the given subject name and id.CompletableFuture<Void>
assertSchema(String subject, int id, boolean exists, Duration timeout)
Asserts the existence of a schema with the given subject name and id within the specified timeout.CompletableFuture<Void>
assertTopic(String topic, boolean exists)
Asserts the existence of a topic.CompletableFuture<Void>
assertTopic(String topic, boolean exists, Duration timeout)
Asserts the existence of a topic within the specified timeout.CompletableFuture<Void>
assertTopic(String topic, Map<String,Integer> configs, boolean exists)
Asserts the existence of a topic with the given configurations.CompletableFuture<Void>
assertTopic(String topic, Map<String,Integer> configs, boolean exists, Duration timeout)
Asserts the existence of a topic with the given configurations within the specified timeout.Client.HttpRequest
buildRequest(String method, String path)
A factory to constructClient.HttpRequest
objects.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.CompletableFuture<Void>
createConnector(String connectorName, boolean isSource, Map<String,Object> properties, boolean ifNotExists)
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.CompletableFuture<Void>
dropConnector(String connectorName, boolean ifExists)
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', 'PAUSE', 'RESUME', '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
-
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 connectorisSource
- true if the connector is a source connector, false if it is a sink connectorproperties
- connector propertiesifNotExists
- 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 dropifExists
- 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
-
assertSchema
CompletableFuture<Void> assertSchema(String subject, boolean exists)
Asserts the existence of a schema with the given subject name. If the assertion fails, then theCompletableFuture
will complete exceptionallyIf a non-200 response is received from the server, the
CompletableFuture
will be failed.- Parameters:
subject
- subject nameexists
- true to check that a schema exists, false to check that a schema does not exist- Returns:
- a future that completes once the server response is received
-
assertSchema
CompletableFuture<Void> assertSchema(int id, boolean exists)
Asserts the existence of a schema with the given id. If the assertion fails, then theCompletableFuture
will complete exceptionallyIf a non-200 response is received from the server, the
CompletableFuture
will be failed.- Parameters:
id
- schema idexists
- true to check that a schema exists, false to check that a schema does not exist- Returns:
- a future that completes once the server response is received
-
assertSchema
CompletableFuture<Void> assertSchema(String subject, int id, boolean exists)
Asserts the existence of a schema with the given subject name and id. If the assertion fails, then theCompletableFuture
will complete exceptionallyIf a non-200 response is received from the server, the
CompletableFuture
will be failed.- Parameters:
subject
- subject nameid
- schema idexists
- true to check that a schema exists, false to check that a schema does not exist- Returns:
- a future that completes once the server response is received
-
assertSchema
CompletableFuture<Void> assertSchema(String subject, boolean exists, Duration timeout)
Asserts the existence of a schema with the given subject name within the specified timeout. If the assertion fails, then theCompletableFuture
will complete exceptionallyIf a non-200 response is received from the server, the
CompletableFuture
will be failed.- Parameters:
subject
- subject nameexists
- true to check that a schema exists, false to check that a schema does not existtimeout
- the amount of time to wait for a successful assertion- Returns:
- a future that completes once the server response is received
-
assertSchema
CompletableFuture<Void> assertSchema(int id, boolean exists, Duration timeout)
Asserts the existence of a schema with the given id within the specified timeout. If the assertion fails, then theCompletableFuture
will complete exceptionallyIf a non-200 response is received from the server, the
CompletableFuture
will be failed.- Parameters:
id
- schema idexists
- true to check that a schema exists, false to check that a schema does not existtimeout
- the amount of time to wait for a successful assertion- Returns:
- a future that completes once the server response is received
-
assertSchema
CompletableFuture<Void> assertSchema(String subject, int id, boolean exists, Duration timeout)
Asserts the existence of a schema with the given subject name and id within the specified timeout. If the assertion fails, then theCompletableFuture
will complete exceptionallyIf a non-200 response is received from the server, the
CompletableFuture
will be failed.- Parameters:
subject
- subject nameid
- schema idexists
- true to check that a schema exists, false to check that a schema does not existtimeout
- the amount of time to wait for a successful assertion- Returns:
- a future that completes once the server response is received
-
assertTopic
CompletableFuture<Void> assertTopic(String topic, boolean exists)
Asserts the existence of a topic. If the assertion fails, then theCompletableFuture
will complete exceptionallyIf a non-200 response is received from the server, the
CompletableFuture
will be failed.- Parameters:
topic
- topic nameexists
- true to check that a schema exists, false to check that a schema does not exist- Returns:
- a future that completes once the server response is received
-
assertTopic
CompletableFuture<Void> assertTopic(String topic, boolean exists, Duration timeout)
Asserts the existence of a topic within the specified timeout. If the assertion fails, then theCompletableFuture
will complete exceptionallyIf a non-200 response is received from the server, the
CompletableFuture
will be failed.- Parameters:
topic
- topic nameexists
- true to check that a schema exists, false to check that a schema does not existtimeout
- the amount of time to wait for a successful assertion- Returns:
- a future that completes once the server response is received
-
assertTopic
CompletableFuture<Void> assertTopic(String topic, Map<String,Integer> configs, boolean exists)
Asserts the existence of a topic with the given configurations. If the assertion fails, then theCompletableFuture
will complete exceptionallyIf a non-200 response is received from the server, the
CompletableFuture
will be failed.- Parameters:
topic
- topic nameconfigs
- map of topic configurations to checkexists
- true to check that a schema exists, false to check that a schema does not exist- Returns:
- a future that completes once the server response is received
-
assertTopic
CompletableFuture<Void> assertTopic(String topic, Map<String,Integer> configs, boolean exists, Duration timeout)
Asserts the existence of a topic with the given configurations within the specified timeout. If the assertion fails, then theCompletableFuture
will complete exceptionallyIf a non-200 response is received from the server, the
CompletableFuture
will be failed.- Parameters:
topic
- topic nameconfigs
- map of topic configurations to checkexists
- true to check that a schema exists, false to check that a schema does not existtimeout
- the amount of time to wait for a successful assertion- Returns:
- a future that completes once the server response is received
-
buildRequest
Client.HttpRequest buildRequest(String method, String path)
A factory to constructClient.HttpRequest
objects. Instances ofClient.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 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)
-
-