.. _controlcenter_userguide_ksql:

################
|ksqldb| in |c3| 
################

|c3-short| provides the convenience of running streaming queries on one or more
|ksqldb| clusters within its graphical user interface. The |ksqldb| feature is
:ref:`enabled <c3_enable_disable_ksql>` by default in |c3-short|.

.. important:: If :ref:`RBAC <c3_rbac_ksql>` is enabled, the ability to view
               and use |ksqldb| in |c3-short| is determined by the assigned
               roles and associated privileges configured in both |ksqldb| and
               |c3-short|.

For more information about |ksqldb|, see :ref:`ksql_home`.

.. tip:: Go through the |cp| :ref:`Local <ce-quickstart>` or
         :ref:`Docker <ce-docker-quickstart>` quick start guides for a fast
         set up of streams, tables, and persisted running queries in |c3-short|.

.. _c3_config_ksql_cluster:

Configure |c3-short| for |ksqldb| applications
==============================================

When you start a local |cp| install using the :ref:`confluent_local_start`
command from the |confluent-cli|, a default |ksqldb| application named **ksqlDB**
is created for you.

To configure |c3-short| to communicate with your own multiple |ksqldb| 
applications in a production environment, set the following options in the 
appropriate ``control-center.properties`` files:

- ``confluent.controlcenter.ksql.<name of cluster>.url = <list of urls>``
- ``confluent.controlcenter.ksql.<name of cluster>.advertised.url = <list of urls>``

These options are required for connecting |c3-short| to your |ksqldb| applications.
For more information, see the :ref:`controlcenter_ksql_settings` options in the
:ref:`controlcenter_configuration`.

.. important:: Be sure to review :ref:`integrate-ksql-with-confluent-control-center`
               for more information on configurations for both |ksqldb| and |c3-short|.

Links to comprehensive |ksqldb| documentation are available throughout the
|c3-short| |ksqldb| web interface.

.. _c3_ksql_clusters_page:

|ksqldb| applications page
==========================

To access the |ksqldb| applications page, click the cluster from the navigation
bar and select **ksqlDB** from the cluster submenu.

Use the |ksqldb| applications page to:

- View a summary of all |ksqldb| applications connected to |c3-short|.
- Search for a |ksqldb| application being managed by the |c3-short| instance.
- Browse topic messages.
- View the number of running queries, registered streams, and registered tables
  for each |ksqldb| application.
- Navigate to the :ref:`c3_ksql_editor`, :ref:`c3_ksql_streams`, 
  :ref:`c3_ksql_tables`, and :ref:`c3_ksql_running_queries` for each |ksqldb|
  application. Click the |ksqldb| application name link to navigate to the |ksqldb|
  Editor and other pages.

.. figure:: ../images/c3-ksql-index-page.png
   :width: 600px
   :alt: ksqlDB applications index page in Confluent Control Center

   ksqlDB applications page in Control Center

.. _c3_ksql_editor:

|ksqldb| Editor
===============

To access the |ksqldb| Editor page, click the |ksqldb| application name in the
:ref:`c3_ksql_clusters_page`.

Use the |ksqldb| Editor page to run SQL queries and browse messages.

.. figure:: ../images/c3-ksql-editor.png
   :width: 600px
   :alt: ksqlDB Editor in Confluent Control Center

   ksqlDB Editor in Control Center

After creating streams and tables, the resizeable streams and tables pane is
populated with the defined streams and tables for the application, beyond the
default ``KSQL_PROCESSING_LOG``:

- Streams are indicated with a blue **St** expandable node: |str|
- Tables are indicated with an orange **Tb** expandable node: |tbl|

.. |str| image:: ../images/c3-ksql-str-icon.png

.. |tbl| image:: ../images/c3-ksql-tbl-icon.png

Click a node to view the schema for a stream or table.

.. figure:: ../images/c3-ksql-st-tb-search-pane.png
   :width: 600px
   :alt: ksqlDB Editor in Confluent Control Center browse streams and table schemas pane

   ksqlDB Editor in Confluent Control Center with search and browse pane indicated

A **Search** box enables searching for streams and tables.

.. _c3_download_selected_msgs_ksql:

Download selected messages
==========================

Download selected rows of messages in a JSON format. You can download messages
from the Messages browser in :ref:`Topics <controlcenter_userguide_topics>` or
:ref:`ksqlDB Editor <controlcenter_userguide_ksql>`.

Run a query in the |ksqldb| Editor to activate the message browser area. After
the messages area is populated with messages, you can select messages for
download, whether the query is running or stopped.

#. Select one or more contiguous or non-contiguous rows. The Download button
   becomes available and shows the number of selected messages.

   .. tip:: Press the **command** key + click to select non-contiguous rows.
            Press **shift** + click on a beginning and ending row to select
            a contiguous range of messages.

   .. figure:: ../images/c3-ksql-download-msg.png
      :width: 600px
      :alt: Selected message for download in ksqlDB Editor browse messages pane

   .. |download| image:: ../images/c3-ksql-download-button.png

#. Click the download button: |download|. A file named ``selected_data_<n>.json``
   that contains the selected messages in JSON format is downloaded into your 
   downloads directory. The *n* represents the number of selected messages.

   Example filename:  ``selected_data_1.json``

   Example contents:

   .. code:: json

      [{"ROWTIME":1562939957397,"ROWKEY":"6578171","VIEWTIME":6578171,"USERID":"User_6","PAGEID":"Page_85"}]

.. _c3_ksql_streams:

Streams
=======

To access the Streams page, click the |ksqldb| application name in the
:ref:`c3_ksql_clusters_page` and click the **Streams** tab.

Use the Streams page to:

- View a summary of streams for the |ksqldb| application.
- Search for streams.
- Add a stream.
- View the Describe stream output (analogous to the :ksqldb-docs:`DESCRIBE|developer-guide/ksqldb-reference/describe/` 
  command in the |ksqldb| CLI).
- Jump to the |ksqldb| Editor page to query the stream.
- Drop a stream (analogous to the :ksqldb-docs:`DROP STREAM|developer-guide/ksqldb-reference/drop-stream/` 
  command in the |ksqldb| CLI).

.. figure:: ../images/c3-ksql-streams-page.png
   :width: 600px
   :alt: ksqlDB Streams page in Control Center

   ksqlDB Streams page in Control Center

Click a stream to view its information, like the stream name, associated |ak|
topic, number of partitions and replicas, and the data format.

.. figure:: ../images/c3-ksql-stream-inspect.png
   :width: 600px
   :alt: ksqlDB Inspect Stream page in Control Center

   ksqlDB Inspect Stream page in Control Center

.. _c3_ksql_tables:

Tables
======

To access the Tables page, click the |ksqldb| application name 
in the :ref:`c3_ksql_clusters_page` and click the **Tables** tab.

Use the Tables page to:

- View a summary of tables for the |ksqldb| application.
- Search for tables.
- Add a table.
- View the Describe table output (analogous to the `DESCRIBE|developer-guide/ksqldb-reference/describe/` 
  command in the |ksqldb| CLI)
- Jump to the |ksqldb| Editor page to query the table.
- Drop a table (analogous to the `DROP TABLE|developer-guide/ksqldb-reference/drop-table/` 
  command in the |ksqldb| CLI).

.. figure:: ../images/c3-ksql-no-tables.png
   :width: 600px
   :alt: Initial view of the ksqlDB Tables page in Confluent Control Center

   Initial view of the ksqlDB Tables page in Control Center

Click **Learn More** to view the |ksqldb| recipes available in the
`Stream Processing Cookbook <https://www.confluent.io/stream-processing-cookbook/>`__.

Click a table to view its information, like the table name, associated |ak|
topic, number of partitions and replicas, and the data format.

.. figure:: ../images/c3-ksql-table-inspect.png
   :width: 600px
   :alt: ksqlDB Inspect Table page in Confluent Control Center

   ksqlDB Inspect Table page in Control Center

.. _c3_ksql_running_queries:

Running Queries
===============

To access the Running Queries page, click the |ksqldb| application name 
in the :ref:`c3_ksql_clusters_page` and click the **Running Queries** tab.

Use the Running Queries page to:

- View the syntax and details of running queries.
- Search running queries.
- View the query execution plan by clicking **Explain** (analogous to the :ksqldb-docs:`EXPLAIN|developer-guide/ksqldb-reference/explain/` 
  command in the |ksqldb| CLI).
- Terminate a running query.

.. figure:: ../images/c3-ksql-no-persisted-queries-running.png
   :width: 600px
   :alt: ksqlDB Running Queries initial page blank in Confluent Control Center

   Initial view of the ksqlDB Running Queries page in Control Center

Click **Persistent Query Examples** to view the |ksqldb| recipes available in 
the `Stream Processing Cookbook <https://www.confluent.io/stream-processing-cookbook/>`_.

.. figure:: ../images/c3-ksql-persistent-query.png
   :width: 600px
   :alt: ksqlDB Running Queries page in Confluent Control Center

   ksqlDB Running Queries page in Control Center

.. tip:: Go through the |cp| :ref:`Local <ce-quickstart>` or :ref:`Docker <ce-docker-quickstart>` 
         quick start guides for a fast set up 
         of streams, tables, and persisted running queries in |c3-short|.

Flow View 
=========	

To access the Flow View page, click the |ksqldb| cluster name 	
in the :ref:`c3_ksql_clusters_page` and click the **Flow** tab.	

Use Flow View to:

- View the topology of your |ksqldb| application.
- Inspect the details of streams, tables, and the |ksqldb| statements that	
  create them.
- View events as they flow through your application.

.. figure:: ../images/c3-ksql-flow-1.png	
   :width: 600px	
   :alt: ksqlDB Flow View in Confluent Control Center	

   ksqlDB application topology in Flow View	

Click a node in the graph to see details about the topology of your |ksqldb|	
application. For example, click on a stream to see its schema and the messages
as they arrive in realtime.

.. figure:: ../images/c3-ksql-flow-2.png	
   :width: 600px	
   :alt: ksqlDB Flow View in Control Center	

   Detail view of a stream showing live messages

.. _c3_enable_disable_ksql:

Enable and disable the |ksqldb| feature in |c3-short|
=====================================================

The |ksqldb| feature is enabled by default. The feature can be disabled by setting
the ``confluent.controlcenter.ksql.enable`` option in the |c3-short| properties
file to ``false``. After disabling the feature, the |ksqldb| submenu in the Cluster
navigation is no longer visible in the |c3-short| UI. You can disable the setting
if you are not using |rbac| in |c3-short| or |ksqldb|, and you do not want anyone
to access the |ksqldb| feature. 

.. important:: If :ref:`RBAC <c3_rbac_ksql>` is enabled for |c3-short|, 
               it takes precedence over Access Control settings.

To disable the |ksqldb| feature in |c3-short|:

#. Set the ``confluent.controlcenter.ksql.enable`` option in your
   ``control-center.properties`` file to ``false``.

   .. code:: bash

      ...
      confluent.controlcenter.ksql.enable=false
      ...

   .. note:: Make the change in the appropriate |c3-short| properties files
             configured for your environments, including
             ``control-center-dev.properties`` or
             ``control-center-production.properties``. The properties files are
             located in ``/path-to-confluent/etc/confluent-control-center/``.

#. Restart |c3-short| and pass in the properties file for the configuration to
   take effect.

   - Local (dev) environment:

     .. important:: Do not use :ref:`confluent_local` for production use.

     .. sourcecode:: bash

        confluent local stop --path <path-to-confluent>
        confluent local start --path <path-to-confluent> ../etc/confluent-control-center/control-center.properties


   - Production environment:

     .. sourcecode:: bash

       ./bin/control-center-stop
       ./bin/control-center-start ../etc/confluent-control-center/control-center.properties

To enable the feature again, set the option back to ``true`` and restart
|c3-short| with the updated properties file.

Next Steps
==========

- :ref:`ksql_quickstart-c3`