.. _controlcenter_userguide_ksql:

####
KSQL
####

|c3-short| provides the convenience of running streaming queries on one or more KSQL 
clusters within its graphical user interface. The
KSQL 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 
               KSQL in |c3-short| is determined by the assigned roles and associated privileges configured
               in both KSQL and |c3-short|.

For more information about KSQL, 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 KSQL clusters
======================================

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

To configure |c3-short| to communicate with your own multiple KSQL 
clusters 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 KSQL clusters. 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 KSQL and |c3-short|.

.. figure:: ../images/c3-KSQL-no-clusters.png
   :width: 600px
 
   Message displayed when KSQL is not configured for Control Center in a production environment

Click **Learn More** for information on :ref:`install_overview`.

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

.. _c3_ksql_clusters_page:

KSQL clusters page
==================

To access the KSQL clusters page, click the cluster from the 
navigation bar and select **KSQL** from the cluster submenu.

Use the KSQL clusters page to:

- View a summary of all KSQL clusters connected to |c3-short|.
- Search for a KSQL cluster being managed by the |c3-short| instance.
- Browse topic messages.
- Navigate to the :ref:`c3_ksql_editor`, :ref:`c3_ksql_streams`, 
  :ref:`c3_ksql_tables`, and :ref:`c3_ksql_running_queries` for each KSQL cluster.
  Click the KSQL cluster name link to navigate to the KSQL Editor and other pages.

.. figure:: ../images/c3-ksql-index-page.png
   :width: 600px
   :alt: KSQL clusters index page in Control Center

   KSQL clusters page

View the number of running queries, registered streams, and registered tables 
for each KSQL cluster.

.. _c3_ksql_editor:

KSQL Editor
===========

To access the KSQL Editor page, click the KSQL cluster name 
in the :ref:`c3_ksql_clusters_page`.

Use the KSQL Editor page to run KSQL queries and browse messages.

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

   KSQL Editor in Control Center

After creating streams and tables, the resizeable streams and tables pane becomes populated
with the defined streams and tables for the cluster (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: KSQL Editor in Control Center browse streams and table schemas pane

   KSQL Editor search and browse streams and tables

A **Search** box is available for you to search for streams and tables.

Click the documentation links for more KSQL information.

.. _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:`KSQL Editor <controlcenter_userguide_ksql>`. 
Run a query in the KSQL Editor to activate the message browser area.
After the messages area becomes 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 KSQL Editor browse messages pane

#. Click **Download (n)**. 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 KSQL cluster 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 KSQL cluster.
- Search for streams.
- Add a stream.
- View the Describe stream output (analogous to the :ref:`DESCRIBE <ksql-syntax-describe>` 
  command in the KSQL CLI).
- Jump to the KSQL Editor page to query the stream.
- Drop a stream (analogous to the :ref:`DROP <drop-stream>` 
  command in the KSQL CLI).

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

   KSQL Streams context menu in Control Center

View information such as the stream name, associated |ak| topic and 
its number of partitions and replicas, and the data format for existing streams.


.. _c3_ksql_tables:

Tables
======

To access the Tables page, click the KSQL cluster 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 KSQL cluster.
- Search for tables.
- Add a table.
- View the Describe table output (analogous to the :ref:`DESCRIBE <ksql-syntax-describe>` 
  command in the KSQL CLI)
- Jump to the KSQL Editor page to query the table.
- Drop a table (analogous to the :ref:`DROP <drop-table>` 
  command in the KSQL CLI).

.. figure:: ../images/c3-ksql-no-tables.png
   :width: 600px
   :alt: Control Center KSQL Table page view no tables yet

   Initial view

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

.. figure:: ../images/c3-ksql-tables-context-menu.png
   :width: 600px
   :alt: KSQL Tables context menu for Describe, Query, and Drop options in Control Center

   KSQL Streams context menu in Control Center

View information such as the table name, associated |ak| topic and 
its number of partitions and replicas, and the data format for existing tables.

.. _c3_ksql_running_queries:

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

To access the Running Queries page, click the KSQL cluster 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 :ref:`EXPLAIN <ksql-syntax-explain>` 
  command in the KSQL CLI).
- Terminate a running query.

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

   Initial view

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

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

   Quick start queries

.. 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_enable_disable_ksql:

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

The KSQL 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 KSQL 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 KSQL, and you do not want
anyone to access the KSQL feature. 

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

To disable the KSQL 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`