SQL: Update docs (elastic/x-pack-elasticsearch#3386)

* Remove "overview". That is already covered in the index page.
* Write a basic getting started page.
* Fix the CLI startup instructions.

Original commit: elastic/x-pack-elasticsearch@dabe72b5cc

docs/en/sql/endpoints/sql-cli.asciidoc

@@ -2,38 +2,38 @@
 [[sql-cli]]
 == SQL CLI
 
-The SQL CLI is a stand alone Java application for quick interaction
+X-Pack ships with a script to run the SQL CLI in its bin directory:
-with X-Pack SQL. You can run it like this:
 
-["source","bash",subs="attributes,callouts"]
+[source,bash]
 --------------------------------------------------
-$ java -jar cli-{version}.jar
+$ ./bin/x-pack/sql-cli
 --------------------------------------------------
 
+The jar containing the SQL CLI is a stand alone Java application and
+the scripts just launch it. You can move it around to other machines
+without having to install Elasticsearch or X-Pack on them.
+
 You can pass the URL of the Elasticsearch instance to connect to as
 the first parameter:
 
-["source","bash",subs="attributes,callouts"]
+[source,bash]
 --------------------------------------------------
-$ java -jar cli-{version}.jar https://some.server:9200
+$ ./bin/x-pack/sql-cli https://some.server:9200
 --------------------------------------------------
 
-The cli jar is entirely stand alone and can be moved whereever it is
-needed.
-
 Once the CLI is running you can use any <<sql-spec,query>> that
 Elasticsearch supports:
 
 [source,sqlcli]
 --------------------------------------------------
 sql> SELECT * FROM library WHERE page_count > 500 ORDER BY page_count DESC;
-           author           |         name          |  page_count
+     author      |        name        |  page_count   | release_date
-----------------------------+-----------------------+---------------
+-----------------+--------------------+---------------+---------------
-Victor Hugo                 |Les Misérables         |1463
+Peter F. Hamilton|Pandora's Star      |768            |1078185600000
-Miguel De Cervantes Saavedra|Don Quixote            |1072
+Vernor Vinge     |A Fire Upon the Deep|613            |707356800000
-Miguel De Cervantes Saavedra|Don Quixote            |1072
+Frank Herbert    |Dune                |604            |-144720000000
-Herman Melville             |Moby-Dick or, The Whale|720
+Alastair Reynolds|Revelation Space    |585            |953078400000
-Charles Dickens             |Oliver Twist           |608
+James S.A. Corey |Leviathan Wakes     |561            |1306972800000
 --------------------------------------------------
 // TODO it'd be lovely to be able to assert that this is correct but
 // that is probably more work then it is worth right now.

docs/en/sql/endpoints/sql-jdbc.asciidoc

@@ -3,7 +3,11 @@
 == SQL JDBC
 
 Elasticsearch's SQL jdbc driver is a fully featured JDBC driver
-for Elasticsearch. You can connect to it using the two APIs offered
+for Elasticsearch.
+
+TODO add example of resolving the artifact in maven and gradle.
+
+You can connect to it using the two APIs offered
 by JDBC, namely `java.sql.Driver` and `DriverManager`:
 
 ["source","java",subs="attributes,callouts,macros"]
@@ -15,7 +19,7 @@ HTTP traffic. The port is usually 9200.
 <2> Properties for connecting to Elasticsearch. An empty `Properties`
 instance is fine for unsecured Elasticsearch.
 
-or `javax.sql.DataSource` through 
+or `javax.sql.DataSource` through
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
 include-tagged::{jdbc-tests}/JdbcIntegrationTestCase.java[connect-ds]

docs/en/sql/index.asciidoc

@@ -25,7 +25,6 @@ indices and return tabular results. There are four main components:
     A JDBC driver for Elasticsearch.
 --
 
-include::sql-overview.asciidoc[]
 include::sql-getting-started.asciidoc[]
 include::endpoints/sql-endpoints.asciidoc[]
 include::functions/sql-functions.asciidoc[]

docs/en/sql/sql-getting-started.asciidoc

@@ -1,5 +1,61 @@
 [[sql-getting-started]]
 == Getting Started with SQL
 
-Basic chapter on using REST, CLI and JDBC to run some basic queries and return some results.
+To start using Elasticsearch SQL, first
-To keep this chapter should be about adding 3-4 entries of data, then using each technology to get the results out.
+<<installing-xpack-es, install X-Pack in Elasticsearch>>. Then create
+in index with some data to experiment with:
+
+[source,js]
+--------------------------------------------------
+PUT /library/book/_bulk?refresh
+{"index":{"_id": "Leviathan Wakes"}}
+{"name": "Leviathan Wakes", "author": "James S.A. Corey", "release_date": "2011-06-02", "page_count": 561}
+{"index":{"_id": "Hyperion"}}
+{"name": "Hyperion", "author": "Dan Simmons", "release_date": "1989-05-26", "page_count": 482}
+{"index":{"_id": "Dune"}}
+{"name": "Dune", "author": "Frank Herbert", "release_date": "1965-06-01", "page_count": 604}
+--------------------------------------------------
+// CONSOLE
+
+And now you can execute SQL using the <<sql-rest>> right away:
+
+[source,js]
+--------------------------------------------------
+POST /_xpack/sql
+{
+    "query": "SELECT * FROM library WHERE release_date < '2000-01-01'"
+}
+--------------------------------------------------
+// CONSOLE
+// TEST[continued]
+
+Which should return something along the lines of:
+
+[source,text]
+--------------------------------------------------
+    author     |     name      |  page_count   | release_date
+---------------+---------------+---------------+---------------
+Dan Simmons    |Hyperion       |482            |612144000000
+Frank Herbert  |Dune           |604            |-144720000000
+--------------------------------------------------
+// TESTRESPONSE[s/\|/\\|/ s/\+/\\+/]
+// TESTRESPONSE[_cat]
+
+You can also use the <<sql-cli>>. There is a script to start it
+shipped in x-pack's bin directory:
+
+[source,bash]
+--------------------------------------------------
+$ ./bin/x-pack/sql-cli
+--------------------------------------------------
+
+From there you can run the same query:
+
+[source,sqlcli]
+--------------------------------------------------
+sql> SELECT * FROM library WHERE release_date < '2000-01-01';
+    author     |     name      |  page_count   | release_date
+---------------+---------------+---------------+---------------
+Dan Simmons    |Hyperion       |482            |612144000000
+Frank Herbert  |Dune           |604            |-144720000000
+--------------------------------------------------

docs/en/sql/sql-overview.asciidoc

@@ -1,4 +0,0 @@
-[[sql-overview]]
-== Overview
-
-Overview of the difference chapters in SQL docs.