SQL: Polish the rest chapter (#38971)
Organize the text a bit and add tip on triple quotes in Kibana Console
This commit is contained in:
Costin Leau
Costin Leau
parent
e78f70e5d8
commit
79bc6aba79
Binary file not shown.
|
After Width: | Height: | Size: 53 KiB |
|
|
@ -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.
|
||||
|
|
@ -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]
|
||||
--------------------------------------------------
|
||||
|
|
|
|||
Loading…
Reference in New Issue