SQL: Polish the rest chapter (#38971)

Organize the text a bit and add tip on triple quotes in Kibana Console

Author: costin

docs/reference/images/sql/rest/console-triple-quotes.png

@@ -4,8 +4,8 @@
 == SQL REST API
 
 The SQL REST API accepts SQL in a JSON document, executes it,
-and returns the results. For example:
-
+and returns the results. 
+For example:
 
 [source,js]
 --------------------------------------------------
@@ -32,19 +32,68 @@ James S.A. Corey |Leviathan Wakes     |561            |2011-06-02T00:00:00.000Z
 // TESTRESPONSE[s/\|/\\|/ s/\+/\\+/]
 // TESTRESPONSE[_cat]
 
-While the `text/plain` format is nice for humans, computers prefer something
-more structured. You can replace the value of `format` with:
-- `json` aka `application/json`
-- `yaml` aka `application/yaml`
-- `smile` aka `application/smile`
-- `cbor` aka `application/cbor`
-- `txt` aka `text/plain`
-- `csv` aka `text/csv`
-- `tsv` aka `text/tab-separated-values`
+[[sql-kibana-console]]
+.Using Kibana Console
+If you are using {kibana-ref}/console-kibana.html[Kibana Console].
+(which is highly recommended), take advantage of the
+triple quotes `"""` when creating the query. This not only automatically escapes double
+quotes (`"`) inside the query string but also support multi-line as shown below:
+image:images/sql/rest/console-triple-quotes.png[]
+
+[[sql-rest-format]]
+[float]
+=== Response Data Formats
+
+While the textual format is nice for humans, computers prefer something
+more structured.
+
+{es-sql} can return the data in the following formats which can be set
+either through the `format` property in the URL or by setting the `Accept` HTTP header:
+
+NOTE: The URL parameter takes precedence over the `Accept` HTTP header.
+If neither is specified then the response is returned in the same format as the request.
+
+[cols="^m,^4m,^8"]
+
+|===
+s|format
+s|`Accept` HTTP header
+s|Description
+
+3+h| Human Readable
+
+|csv
+|text/csv
+|https://en.wikipedia.org/wiki/Comma-separated_values[Comma-separated values]
+
+|json
+|application/json
+|https://www.json.org/[JSON] (JavaScript Object Notation) human-readable format
+
+|tsv
+|text/tab-separated-values
+|https://en.wikipedia.org/wiki/Tab-separated_values[Tab-separated values]
+
+|txt
+|text/plain
+|CLI-like representation
+
+|yaml
+|application/yaml
+|https://en.wikipedia.org/wiki/YAML[YAML] (YAML Ain't Markup Language) human-readable format
+
+3+h| Binary Formats
+
+|cbor
+|application/cbor
+|http://cbor.io/[Concise Binary Object Representation]
+
+|smile
+|application/smile
+|https://en.wikipedia.org/wiki/Smile_(data_interchange_format)[Smile] binary data format similar to CBOR
+
+|===
 
-Alternatively you can set the `Accept` HTTP header to the appropriate media
-format. The GET parameter takes precedence over the header. If neither is
-specified then the response is returned in the same format as the request.
 
 [source,js]
 --------------------------------------------------
@@ -80,7 +129,11 @@ Which returns:
 --------------------------------------------------
 // TESTRESPONSE[s/sDXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAAEWWWdrRlVfSS1TbDYtcW9lc1FJNmlYdw==:BAFmBmF1dGhvcgFmBG5hbWUBZgpwYWdlX2NvdW50AWYMcmVsZWFzZV9kYXRl\+v\/\/\/w8=/$body.cursor/]
 
-You can continue to the next page by sending back the `cursor` field. In
+[[sql-pagination]]
+[float]
+=== Paginating through a large response
+
+Using the example above, onu can continue to the next page by sending back the `cursor` field. In
 case of text format the cursor is returned as `Cursor` http header.
 
 [source,js]
@@ -111,7 +164,7 @@ Which looks like:
 --------------------------------------------------
 // TESTRESPONSE[s/sDXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAAEWODRMaXBUaVlRN21iTlRyWHZWYUdrdw==:BAFmBmF1dGhvcgFmBG5hbWUBZgpwYWdlX2NvdW50AWYMcmVsZWFzZV9kYXRl9f\/\/\/w8=/$body.cursor/]
 
-Note that the `column` object is only part of the first page.
+Note that the `columns` object is only part of the first page.
 
 You've reached the last page when there is no `cursor` returned
 in the results. Like Elasticsearch's <<search-request-scroll,scroll>>,
@@ -145,9 +198,11 @@ Which will like return the
 
 
 [[sql-rest-filtering]]
+[float]
+=== Filtering using {es} query DSL
 
 You can filter the results that SQL will run on using a standard
-Elasticsearch query DSL by specifying the query in the filter
+{es} query DSL by specifying the query in the filter
 parameter.
 
 [source,js]
@@ -181,10 +236,48 @@ Douglas Adams  |The Hitchhiker's Guide to the Galaxy|180            |1979-10-12T
 // TESTRESPONSE[_cat]
 
 [[sql-rest-fields]]
-In addition to the `query` and `cursor` fields, the request can
-contain `fetch_size` and `time_zone`. `fetch_size` is a hint for how
-many results to return in each page. SQL might chose to return more
-or fewer results though. `time_zone` is the time zone to use for datetime
-functions and datetime parsing. `time_zone` defaults to `utc` and can take
-any values documented
-http://www.joda.org/joda-time/apidocs/org/joda/time/DateTimeZone.html[here].
+[float]
+=== Supported REST parameters
+
+In addition to the `query` and `fetch_size`, a request a number of user-defined fields for specifying
+the request time-outs or localization information (such as timezone).
+
+The table below lists the supported parameters:
+
+[cols="^m,^m,^5"]
+
+|===
+
+s|name
+s|Default value
+s|Description
+
+|query
+|Mandatory
+|SQL query to execute
+
+|fetch_size
+|1000
+|The maximum number of rows (or entries) to return in one response
+
+|filter
+|none
+|Optional {es} query DSL for additional <<sql-rest-filtering, filtering>>.
+
+|request_timeout
+|90s
+|The timeout before the request fails.
+
+|page_timeout
+|45s
+|The timeout before a pagination request fails.
+
+|time_zone
+|`Z` (or `UTC`)
+|Time-zone in ISO 8601 used for executing the query on the server.
+More information available https://docs.oracle.com/javase/8/docs/api/java/time/ZoneId.html[here].
+
+|===
+
+Do note that most parameters (outside the timeout ones) make sense only during the initial query - any follow-up pagination request only requires the `cursor` parameter as explained in the <<sql-pagination, pagination>> chapter.
+That's because the query has already been executed and the calls are simply about returning the found results - thus the parameters are simply ignored.

docs/reference/sql/endpoints/rest.asciidoc

@@ -4,7 +4,7 @@
 == SQL Translate API
 
 The SQL Translate API accepts SQL in a JSON document and translates it
-into native Elasticsearch queries. For example:
+into native {es} queries. For example:
 
 [source,js]
 --------------------------------------------------