Package io.confluent.ksql.api.client

Interface Client

    • 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 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

      • assertSchema

        CompletableFuture<Void> assertSchema​(String subject,
                                     boolean exists)
        Asserts the existence of a schema with the given subject name. If the assertion fails, then the CompletableFuture will complete exceptionally

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

        Parameters:
        subject - subject name
        exists - 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 the CompletableFuture will complete exceptionally

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

        Parameters:
        id - schema id
        exists - 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 the CompletableFuture will complete exceptionally

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

        Parameters:
        subject - subject name
        id - schema id
        exists - 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 the CompletableFuture will complete exceptionally

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

        Parameters:
        subject - subject name
        exists - true to check that a schema exists, false to check that a schema does not exist
        timeout - 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 the CompletableFuture will complete exceptionally

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

        Parameters:
        id - schema id
        exists - true to check that a schema exists, false to check that a schema does not exist
        timeout - 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 the CompletableFuture will complete exceptionally

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

        Parameters:
        subject - subject name
        id - schema id
        exists - true to check that a schema exists, false to check that a schema does not exist
        timeout - 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 the CompletableFuture will complete exceptionally

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

        Parameters:
        topic - topic name
        exists - 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 the CompletableFuture will complete exceptionally

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

        Parameters:
        topic - topic name
        exists - true to check that a schema exists, false to check that a schema does not exist
        timeout - 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 the CompletableFuture will complete exceptionally

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

        Parameters:
        topic - topic name
        configs - map of topic configurations to check
        exists - 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 the CompletableFuture will complete exceptionally

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

        Parameters:
        topic - topic name
        configs - map of topic configurations to check
        exists - true to check that a schema exists, false to check that a schema does not exist
        timeout - 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 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.