DOC: Add SQL section on client applications

Add setup instructions for a number of GUI SQL applications

docs/reference/sql/endpoints/client-apps/dbeaver.asciidoc

@@ -0,0 +1,57 @@
+[role="xpack"]
+[testenv="platinum"]
+[[sql-client-apps-dbeaver]]
+=== DBeaver
+
+[quote, https://dbeaver.io/]
+____
+https://dbeaver.io/[DBeaver] DBeaver is free and open source universal database tool for developers and database administrators.
+____
+
+==== Prerequisites
+
+* DBeaver version 5.1.4 or higher
+* {es-sql} <<sql-jdbc, JDBC driver>>
+
+==== New Connection
+
+Create a new connection either through the menu *File* > *New* > *Database Connection* menu or directly through the *Database Connection* panel.
+
+image:images/sql/client-apps/dbeaver-1-new-conn.png[]
+
+==== Select {es} type
+Select the {es} type from the available connection types:
+
+image:images/sql/client-apps/dbeaver-2-conn-es.png[]
+
+==== Specify the {es} cluster information
+
+Configure the {es-sql} connection appropriately:
+
+image:images/sql/client-apps/dbeaver-3-conn-props.png[]
+
+==== Verify the driver version
+
+Make sure the correct JDBC driver version is used by using the *Edit Driver Settings* button:
+
+image:images/sql/client-apps/dbeaver-4-driver-ver.png[]
+
+DBeaver is aware of the {es} JDBC maven repository so simply *Download/Update* the artifact or add a new one. As an alternative one can add a local file instead if the {es} Maven repository is not an option.
+
+When changing the driver, make sure to click on the *Find Class* button at the bottom - the Driver class should be picked out automatically however this provides a sanity check that the driver jar is properly found and it is not corrupt.
+
+==== Test connectivity
+
+Once the driver version and the settings are in place, use *Test Connection* to check that everything works. If things are okay, one should get a confirmation window with the version of the driver and that of {es-sql}:
+
+image:images/sql/client-apps/dbeaver-5-test-conn.png[]
+
+Click *Finish* and the new {es} connection appears in the *Database Connection* panel.
+
+DBeaver is now configured to talk to {es}.
+
+==== Connect to {es}
+
+Simply click on the {es} connection and start querying and exploring {es}:
+
+image:images/sql/client-apps/dbeaver-6-data.png[]

docs/reference/sql/endpoints/client-apps/dbvis.asciidoc

@@ -0,0 +1,42 @@
+[role="xpack"]
+[testenv="platinum"]
+[[sql-client-apps-dbvis]]
+=== DbVisualizer
+
+[quote, http://www.dbvis.com/]
+____
+https://www.dbvis.com/[DbVisualizer] is a database management and analysis tool for all major databases.
+____
+
+==== Prerequisites
+
+* {es-sql} <<sql-jdbc, JDBC driver>>
+
+==== Add {es} JDBC driver
+
+Add the {es} JDBC driver to DbVisualizer through *Tools* > *Driver Manager*:
+
+image:images/sql/client-apps/dbvis-1-driver-manager.png[]
+
+Create a new driver entry through *Driver* > *Create Driver* entry and add the JDBC driver in the files panel
+through the buttons on the right. Once specify, the driver class and its version should be automatically picked up - one can force the refresh through the *Find driver in liste locations* button, the second from the bottom on the right hand side:
+ 
+image:images/sql/client-apps/dbvis-2-driver.png[]
+
+==== Create a new connection
+
+Once the {es} driver is in place, create a new connection:
+
+image:images/sql/client-apps/dbvis-3-new-conn.png[]
+
+One can use the wizard or add the settings all at once:
+
+image:images/sql/client-apps/dbvis-4-conn-props.png[]
+
+Press *Connect* and the driver version (as that of the cluster) should show up under *Connection Message*.
+
+==== Execute SQL queries
+
+The setup is done. DbVisualizer can be used to run queries against {es} and explore its content:
+
+image:images/sql/client-apps/dbvis-5-data.png[]

docs/reference/sql/endpoints/client-apps/index.asciidoc

@@ -0,0 +1,21 @@
+[role="xpack"]
+[testenv="platinum"]
+[[sql-client-apps]]
+== SQL Client Applications
+
+Thanks to its <<sql-jdbc, JDBC>> interface, {es-sql} supports a broad range of applications.
+This section lists, in alphabetical order, a number of them and their respective configuration - the list however is by no means comprehensive (feel free to https://www.elastic.co/blog/art-of-pull-request[submit a PR] to improve it):
+as long as the app can use the {es-sql} driver, it can use {es-sql}.
+
+* <<sql-client-apps-dbeaver, DBeaver>>
+* <<sql-client-apps-dbvis, DbVisualizer>>
+* <<sql-client-apps-squirrel, SQuirreL SQL>>
+* <<sql-client-apps-workbench, SQL Workbench>>
+
+NOTE: Each application has its own requirements and license; these are outside the scope of this documentation
+which covers only the configuration aspect with {es-sql}.
+
+include::dbeaver.asciidoc[]
+include::dbvis.asciidoc[]
+include::squirrel.asciidoc[]
+include::workbench.asciidoc[]

docs/reference/sql/endpoints/client-apps/squirrel.asciidoc

@@ -0,0 +1,50 @@
+[role="xpack"]
+[testenv="platinum"]
+[[sql-client-apps-squirrel]]
+=== SQquirelL SQL
+
+[quote, http://squirrel-sql.sourceforge.net/]
+____
+http://squirrel-sql.sourceforge.net/[SQuirelL SQL] is a graphical, [multi-platform] Java program that will allow you to view the structure of a JDBC compliant database [...].
+____
+
+==== Prerequisites
+
+* {es-sql} <<sql-jdbc, JDBC driver>>
+
+==== Add {es} JDBC Driver
+
+To add the {es} JDBC driver, use *Windows* > *View Drivers* menu (or Ctrl+Shift+D shortcut):
+
+image:images/sql/client-apps/squirell-1-view-drivers.png[]
+
+This opens up the `Drivers` panel on the left. Click on the `+` sign to create a new driver:
+
+image:images/sql/client-apps/squirell-2-new-driver.png[]
+
+Select the *Extra Class Path* tab and *Add* the JDBC jar. *List Drivers* to have the `Class Name` filled-in
+automatically and name the connection:
+
+image:images/sql/client-apps/squirell-3-add-driver.png[]
+
+The driver should now appear in the list:
+
+image:images/sql/client-apps/squirell-4-driver-list.png[]
+
+==== Add an alias for {es}
+
+Add a new connection or in SQuirelL terminology an _alias_ using the new driver. To do so, select the *Aliases* panel on the left and click the `+` sign:
+
+image:images/sql/client-apps/squirell-5-add-alias.png[]
+
+Name the new alias and select the `Elasticsearch` driver previously added:
+
+image:images/sql/client-apps/squirell-6-alias-props.png[]
+
+The setup is completed. Double check it by clicking on *Test Connection*.
+
+==== Execute SQL queries
+
+The connection should open automatically (if it has been created before simply click on *Connect* in the *Alias* panel). SQuirelL SQL can now issue SQL commands to {es}:
+
+image:images/sql/client-apps/squirell-7-data.png[]

docs/reference/sql/endpoints/client-apps/workbench.asciidoc

@@ -0,0 +1,40 @@
+[role="xpack"]
+[testenv="platinum"]
+[[sql-client-apps-workbench]]
+=== SQL Workbench/J
+
+[quote, https://www.sql-workbench.eu/]
+____
+https://www.sql-workbench.eu/[SQL Workbench/J] is a free, DBMS-independent, cross-platform SQL query tool.
+____
+
+==== Prerequisites
+
+* {es-sql} <<sql-jdbc, JDBC driver>>
+
+==== Add {es} JDBC driver
+
+Add the {es} JDBC driver to SQL Workbench/J through *Manage Drivers* either from the main windows in the *File* menu or from the *Connect* window:
+
+image:images/sql/client-apps/workbench-1-manage-drivers.png[]
+
+Add a new entry to the list through the blank page button in the upper left corner. Add the JDBC jar, provide a name and click on the magnifier button to have the driver *Classname* picked-up automatically:
+
+image:images/sql/client-apps/workbench-2-add-driver.png[]
+
+==== Create a new connection profile
+
+With the driver configured, create a new connection profile through *File* > *Connect Window* (or Alt+C shortcut):
+
+image:images/sql/client-apps/workbench-3-connection.png[]
+
+Select the previously configured driver and set the URL of your cluster using the JDBC syntax.
+Verify the connection through the *Test* button - a confirmation window should appear that everything is properly configured.
+
+The setup is complete.
+
+==== Execute SQL queries
+
+SQL Workbench/J is ready to talk to {es} through SQL: click on the profile created to execute statements or explore the data:
+
+image:images/sql/client-apps/workbench-4-data.png[]

docs/reference/sql/endpoints/index.asciidoc

@@ -2,3 +2,4 @@ include::rest.asciidoc[]
 include::translate.asciidoc[]
 include::cli.asciidoc[]
 include::jdbc.asciidoc[]
+include::client-apps/index.asciidoc[]

docs/reference/sql/endpoints/jdbc.asciidoc

@@ -3,14 +3,20 @@
 [[sql-jdbc]]
 == SQL JDBC
 
-Elasticsearch's SQL jdbc driver is a rich, fully featured JDBC driver for Elasticsearch.
+{es}'s SQL jdbc driver is a rich, fully featured JDBC driver for {es}.
 It is Type 4 driver, meaning it is a platform independent, stand-alone, Direct to Database,
-pure Java driver that converts JDBC calls to Elasticsearch SQL.
+pure Java driver that converts JDBC calls to {es-sql}.
 
+[[sql-jdbc-installation]]
 [float]
 === Installation
 
-The JDBC driver can be obtained either by downloading it from the https://www.elastic.co/downloads/jdbc-client[elastic.co] site or by using a http://maven.apache.org/[Maven]-compatible tool with the following dependency:
+The JDBC driver can be obtained from:
+
+Dedicated page::
+https://www.elastic.co/downloads/jdbc-client[elastic.co] provides links, typically for manual downloads.
+Maven dependency::
+http://maven.apache.org/[Maven]-compatible tools can retrieve it automatically as a dependency:
 
 ["source","xml",subs="attributes"]
 ----

docs/reference/sql/index.asciidoc

@@ -36,6 +36,8 @@ indices and return results in tabular format.
     SQL and print tabular results.
 <<sql-jdbc,JDBC>>::
     A JDBC driver for {es}.
+<<sql-client-apps,Client Applications>>::
+    Documentation for configuring various SQL/BI tools with {es-sql}.
 <<sql-spec,SQL Language>>::
     Overview of the {es-sql} language, such as supported data types, commands and 
     syntax.

docs/reference/sql/language/syntax/describe-table.asciidoc

@@ -6,9 +6,12 @@
 .Synopsis
 [source, sql]
 ----
-DESCRIBE [table identifier<1>|[LIKE pattern<2>]]
+DESCRIBE [table identifier<1> | [LIKE pattern<2>]]
 ----
 
+<1> single table identifier or double quoted es multi index
+<2> SQL LIKE pattern
+
 or 
 
 [source, sql]
@@ -16,6 +19,8 @@ or
 DESC [table identifier<1>|[LIKE pattern<2>]]
 ----
 
+<1> single table identifier or double quoted es multi index
+<2> SQL LIKE pattern
 
 .Description