KSQL Operations

Local Development and Testing with Confluent CLI

For development and testing purposes, you can use Confluent CLI to spin up services on a single host. For more information, see the Confluent Platform Quick Start.


The Confluent CLI is meant for development purposes only and is not suitable for a production environment. The data that are produced are transient and are intended to be temporary.

Starting and Stopping KSQL Clusters

KSQL provides start and stop scripts.

This script starts the KSQL server. It requires a server configuration file as an argument and is located in the /bin directory of your Confluent Platform installation. For more information, see Starting the KSQL Server.
This script stops the KSQL server. It is located in the /bin directory of your Confluent Platform installation.


  • The KSQL REST API supports a “server info” request at http://<server>:8088/info.
  • Check runtime stats for the KSQL server that you are connected to via DESCRIBE EXTENDED <stream or table> and EXPLAIN <name of query>.
  • Run ksql-print-metrics on a KSQL server. For example, see this blog post.

Monitoring and Metrics

KSQL includes JMX (Java Management Extensions) metrics which give insights into what is happening inside your KSQL servers. These metrics include the number of messages, the total throughput, throughput distribution, error rate, and more.

To enable JMX metrics, set JMX_PORT before starting the KSQL server:

$ export JMX_PORT=1099 && \
  <path-to-confluent>/bin/ksql-server-start <path-to-confluent>/etc/ksql/ksql-server.properties

The ksql-print-metrics command line utility collects these metrics and prints them to the console. You can invoke this utility from your terminal:

$ <path-to-confluent>/bin/ksql-print-metrics

Your output should resemble:

messages-consumed-avg: 96416.96196183885
messages-consumed-min: 88900.3329377909
error-rate: 0.0
num-persistent-queries: 2.0
messages-consumed-per-sec: 193024.78294586178
messages-produced-per-sec: 193025.4730374501
num-active-queries: 2.0
num-idle-queries: 0.0
messages-consumed-max: 103397.81191436431

For more information about Kafka Streams metrics, see Monitoring your application.

Capacity Planning

The Capacity Planning guide describes how to size your KSQL clusters.


SELECT query hangs and doesn’t stop?

Queries in KSQL, including non-persistent queries such as SELECT * FROM myTable, are continuous streaming queries. Streaming queries will not stop unless explicitly terminated. To terminate a non-persistent query in the KSQL CLI you must type Ctrl + C.

No results from SELECT * FROM table or stream?

This is typically caused by the query being configured to process only newly arriving data instead, and no new input records are being received. To fix, do one of the following:

Can’t create a stream from the output of windowed aggregate?

The output of a windowed aggregate is a record per grouping key and per window, and is not a single record. This is not currently supported in KSQL.

KSQL doesn’t clean up its internal topics?

Make sure that your Kafka cluster is configured with delete.topic.enable=true. For more information, see deleteTopics.