Restructure the SQL Language section to have proper sub-sections (#43007)

astefan · astefan · commit 6b21cacd8e44 · 2019-06-11T17:22:23.000+03:00
Rest docs page update - have the section be on separate pages - add an Overview page - add other formats examples (cherry picked from commit 309bd69)
diff --git a/docs/reference/sql/endpoints/rest.asciidoc b/docs/reference/sql/endpoints/rest.asciidoc
@@ -3,6 +3,16 @@
 [[sql-rest]]
 == SQL REST API
 
+* <<sql-rest-overview>>
+* <<sql-rest-format>>
+* <<sql-pagination>>
+* <<sql-rest-filtering>>
+* <<sql-rest-columnar>>
+* <<sql-rest-fields>>
+
+[[sql-rest-overview]]
+=== Overview
+
 The SQL REST API accepts SQL in a JSON document, executes it,
 and returns the results. 
 For example:
@@ -34,14 +44,13 @@ James S.A. Corey |Leviathan Wakes     |561            |2011-06-02T00:00:00.000Z
 
 [[sql-kibana-console]]
 .Using Kibana Console
-If you are using {kibana-ref}/console-kibana.html[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
@@ -94,6 +103,35 @@ s|Description
 
 |===
 
+Here are some examples for the human readable formats:
+
+==== CSV
+
+[source,js]
+--------------------------------------------------
+POST /_sql?format=csv
+{
+    "query": "SELECT * FROM library ORDER BY page_count DESC",
+    "fetch_size": 5
+}
+--------------------------------------------------
+// CONSOLE
+// TEST[setup:library]
+
+Which returns:
+
+[source,text]
+--------------------------------------------------
+author,name,page_count,release_date
+Peter F. Hamilton,Pandora's Star,768,2004-03-02T00:00:00.000Z
+Vernor Vinge,A Fire Upon the Deep,613,1992-06-01T00:00:00.000Z
+Frank Herbert,Dune,604,1965-06-01T00:00:00.000Z
+Alastair Reynolds,Revelation Space,585,2000-03-15T00:00:00.000Z
+James S.A. Corey,Leviathan Wakes,561,2011-06-02T00:00:00.000Z
+--------------------------------------------------
+// TESTRESPONSE[_cat]
+
+==== JSON
 
 [source,js]
 --------------------------------------------------
@@ -129,8 +167,113 @@ Which returns:
 --------------------------------------------------
 // TESTRESPONSE[s/sDXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAAEWWWdrRlVfSS1TbDYtcW9lc1FJNmlYdw==:BAFmBmF1dGhvcgFmBG5hbWUBZgpwYWdlX2NvdW50AWYMcmVsZWFzZV9kYXRl\+v\/\/\/w8=/$body.cursor/]
 
+==== TSV
+
+[source,js]
+--------------------------------------------------
+POST /_sql?format=tsv
+{
+    "query": "SELECT * FROM library ORDER BY page_count DESC",
+    "fetch_size": 5
+}
+--------------------------------------------------
+// CONSOLE
+// TEST[setup:library]
+
+Which returns:
+
+[source,text]
+--------------------------------------------------
+author	name	page_count	release_date
+Peter F. Hamilton	Pandora's Star	768	2004-03-02T00:00:00.000Z
+Vernor Vinge	A Fire Upon the Deep	613	1992-06-01T00:00:00.000Z
+Frank Herbert	Dune	604	1965-06-01T00:00:00.000Z
+Alastair Reynolds	Revelation Space	585	2000-03-15T00:00:00.000Z
+James S.A. Corey	Leviathan Wakes	561	2011-06-02T00:00:00.000Z
+--------------------------------------------------
+// TESTRESPONSE[s/\t/ /]
+// TESTRESPONSE[_cat]
+
+==== TXT
+
+[source,js]
+--------------------------------------------------
+POST /_sql?format=txt
+{
+    "query": "SELECT * FROM library ORDER BY page_count DESC",
+    "fetch_size": 5
+}
+--------------------------------------------------
+// CONSOLE
+// TEST[setup:library]
+
+Which returns:
+
+[source,text]
+--------------------------------------------------
+     author      |        name        |  page_count   |      release_date      
+-----------------+--------------------+---------------+------------------------
+Peter F. Hamilton|Pandora's Star      |768            |2004-03-02T00:00:00.000Z
+Vernor Vinge     |A Fire Upon the Deep|613            |1992-06-01T00:00:00.000Z
+Frank Herbert    |Dune                |604            |1965-06-01T00:00:00.000Z
+Alastair Reynolds|Revelation Space    |585            |2000-03-15T00:00:00.000Z
+James S.A. Corey |Leviathan Wakes     |561            |2011-06-02T00:00:00.000Z
+--------------------------------------------------
+// TESTRESPONSE[s/\|/\\|/ s/\+/\\+/]
+// TESTRESPONSE[_cat]
+
+==== YAML
+
+[source,js]
+--------------------------------------------------
+POST /_sql?format=yaml
+{
+    "query": "SELECT * FROM library ORDER BY page_count DESC",
+    "fetch_size": 5
+}
+--------------------------------------------------
+// CONSOLE
+// TEST[setup:library]
+
+Which returns:
+
+[source,yaml]
+--------------------------------------------------
+columns:
+- name: "author"
+  type: "text"
+- name: "name"
+  type: "text"
+- name: "page_count"
+  type: "short"
+- name: "release_date"
+  type: "datetime"
+rows:
+- - "Peter F. Hamilton"
+  - "Pandora's Star"
+  - 768
+  - "2004-03-02T00:00:00.000Z"
+- - "Vernor Vinge"
+  - "A Fire Upon the Deep"
+  - 613
+  - "1992-06-01T00:00:00.000Z"
+- - "Frank Herbert"
+  - "Dune"
+  - 604
+  - "1965-06-01T00:00:00.000Z"
+- - "Alastair Reynolds"
+  - "Revelation Space"
+  - 585
+  - "2000-03-15T00:00:00.000Z"
+- - "James S.A. Corey"
+  - "Leviathan Wakes"
+  - 561
+  - "2011-06-02T00:00:00.000Z"
+cursor: "sDXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAAEWWWdrRlVfSS1TbDYtcW9lc1FJNmlYdw==:BAFmBmF1dGhvcgFmBG5hbWUBZgpwYWdlX2NvdW50AWYMcmVsZWFzZV9kYXRl+v///w8="
+--------------------------------------------------
+// TESTRESPONSE[s/sDXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAAEWWWdrRlVfSS1TbDYtcW9lc1FJNmlYdw==:BAFmBmF1dGhvcgFmBG5hbWUBZgpwYWdlX2NvdW50AWYMcmVsZWFzZV9kYXRl\+v\/\/\/w8=/$body.cursor/]
+
 [[sql-pagination]]
-[float]
 === Paginating through a large response
 
 Using the example above, one can continue to the next page by sending back the `cursor` field. In
@@ -198,7 +341,6 @@ 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
@@ -236,7 +378,6 @@ Douglas Adams  |The Hitchhiker's Guide to the Galaxy|180            |1979-10-12T
 // TESTRESPONSE[non_json]
 
 [[sql-rest-columnar]]
-[float]
 === Columnar results
 
 The most well known way of displaying the results of an SQL query result in general is the one where each
@@ -311,7 +452,6 @@ Which looks like:
 // TESTRESPONSE[s/46ToAwFzQERYRjFaWEo1UVc1a1JtVjBZMmdCQUFBQUFBQUFBQUVXWjBaNlFXbzNOV0pVY21Wa1NUZDJhV2t3V2xwblp3PT3\/\/\/\/\/DwQBZgZhdXRob3IBBHRleHQAAAFmBG5hbWUBBHRleHQAAAFmCnBhZ2VfY291bnQBBGxvbmcBAAFmDHJlbGVhc2VfZGF0ZQEIZGF0ZXRpbWUBAAEP/$body.cursor/]
 
 [[sql-rest-fields]]
-[float]
 === Supported REST parameters
 
 In addition to the `query` and `fetch_size`, a request a number of user-defined fields for specifying
diff --git a/docs/reference/sql/language/data-types.asciidoc b/docs/reference/sql/language/data-types.asciidoc
@@ -1,7 +1,7 @@
 [role="xpack"]
 [testenv="basic"]
 [[sql-data-types]]
-== Data Types
+=== Data Types
 
 [cols="^,^m,^,^"]
 
@@ -89,7 +89,7 @@ s|SQL precision
 
 [[sql-multi-field]]
 [float]
-=== SQL and multi-fields
+==== SQL and multi-fields
 
 A core concept in {es} is that of an `analyzed` field, that is a full-text value that is interpreted in order
 to be effectively indexed. These fields are of type <<text, `text`>> and are not used for sorting or aggregations as their actual value depends on the <<analyzer, `analyzer`>> used hence why {es} also offers the <<keyword, `keyword`>> type for storing the _exact_
diff --git a/docs/reference/sql/language/index-patterns.asciidoc b/docs/reference/sql/language/index-patterns.asciidoc
@@ -1,11 +1,13 @@
 [role="xpack"]
 [testenv="basic"]
 [[sql-index-patterns]]
-== Index patterns
+=== Index patterns
 
 {es-sql} supports two types of patterns for matching multiple indices or tables:
 
-* {es} multi-index
+[[sql-index-patterns-multi]]
+[float]
+==== {es} multi-index
 
 The {es} notation for enumerating, including or excluding <<multi-index,multi index syntax>>
 is supported _as long_ as it is quoted or escaped as a table identifier.
@@ -33,7 +35,9 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[fromTablePatternQuoted]
 
 NOTE: There is the restriction that all resolved concrete tables have the exact same mapping.
 
-* SQL `LIKE` notation
+[[sql-index-patterns-like]]
+[float]
+==== SQL `LIKE` notation
 
 The common `LIKE` statement (including escaping if needed) to match a wildcard pattern, based on one `_`
 or multiple `%` characters.
diff --git a/docs/reference/sql/language/syntax/commands/index.asciidoc b/docs/reference/sql/language/syntax/commands/index.asciidoc
@@ -1,7 +1,7 @@
 [role="xpack"]
 [testenv="basic"]
 [[sql-commands]]
-== SQL Commands
+=== SQL Commands
 
 This section contains the list of SQL commands supported by {es-sql} along with their syntax:
 
diff --git a/docs/reference/sql/language/syntax/lexic/index.asciidoc b/docs/reference/sql/language/syntax/lexic/index.asciidoc
@@ -1,7 +1,7 @@
 [role="xpack"]
 [testenv="basic"]
 [[sql-lexical-structure]]
-== Lexical Structure
+=== Lexical Structure
 
 This section covers the major lexical structure of SQL, which for the most part, is going to resemble that of ANSI SQL itself hence why low-levels details are not discussed in depth.
 
@@ -10,8 +10,7 @@ This section covers the major lexical structure of SQL, which for the most part,
 A token can be a __key word__, an _identifier_ (_quoted_ or _unquoted_), a _literal_ (or constant) or a special character symbol (typically a delimiter). Tokens are typically separated by whitespace (be it space, tab) though in some cases, where there is no ambiguity (typically due to a character symbol) this is not needed - however for readability purposes this should be avoided.
 
 [[sql-syntax-keywords]]
-[float]
-=== Key Words
+==== Key Words
 
 Take the following example:
 
@@ -35,8 +34,7 @@ Identifiers however are not - as {es} is case sensitive, {es-sql} uses the recei
 To help differentiate between the two, through-out the documentation the SQL key words are upper-cased a convention we find increases readability and thus recommend to others.
 
 [[sql-syntax-identifiers]]
-[float]
-=== Identifiers
+==== Identifiers
 
 Identifiers can be of two types: __quoted__ and __unquoted__:
 
@@ -59,14 +57,13 @@ The first identifier from needs to quoted as otherwise it clashes with the `FROM
 Hence why in general, *especially* when dealing with user input it is *highly* recommended to use quotes for identifiers. It adds minimal increase to your queries and in return offers clarity and disambiguation.
 
 [[sql-syntax-literals]]
-[float]
-=== Literals (Constants)
+==== Literals (Constants)
 
 {es-sql} supports two kind of __implicitly-typed__ literals: strings and numbers.
 
 [[sql-syntax-string-literals]]
 [float]
-==== String Literals
+===== String Literals
 
 A string literal is an arbitrary number of characters bounded by single quotes `'`: `'Giant Robot'`. 
 To include a single quote in the string, escape it using another single quote: `'Captain EO''s Voyage'`. 
@@ -75,7 +72,7 @@ NOTE: An escaped single quote is *not* a double quote (`"`), but a single quote
 
 [sql-syntax-numeric-literals]
 [float]
-==== Numeric Literals
+===== Numeric Literals
 
 Numeric literals are accepted both in decimal and scientific notation with exponent marker (`e` or `E`), starting either with a digit or decimal point `.`:
 
@@ -92,7 +89,7 @@ Numeric literals that contain a decimal point are always interpreted as being of
 
 [[sql-syntax-generic-literals]]
 [float]
-==== Generic Literals
+===== Generic Literals
 
 When dealing with arbitrary type literal, one creates the object by casting, typically, the string representation to the desired type. This can be achieved through the dedicated <<sql-operators-cast, cast operator>> and <<sql-functions-type-conversion, functions>>:
 
@@ -106,8 +103,7 @@ CONVERT('10.0.0.1', IP)                     -- cast '10.0.0.1' to an IP
 Do note that {es-sql} provides functions that out of the box return popular literals (like `E()`) or provide dedicated parsing for certain strings.
 
 [[sql-syntax-single-vs-double-quotes]]
-[float]
-=== Single vs Double Quotes
+==== Single vs Double Quotes
 
 It is worth pointing out that in SQL, single quotes `'` and double quotes `"` have different meaning and *cannot* be used interchangeably.
 Single quotes are used to declare a <<sql-syntax-string-literals, string literal>> while double quotes for <<sql-syntax-identifiers, identifiers>>.
@@ -126,8 +122,7 @@ SELECT "first_name" <1>
 <2> Single quotes `'` used for a string literal
 
 [[sql-syntax-special-chars]]
-[float]
-=== Special characters
+==== Special characters
 
 A few characters that are not alphanumeric have a dedicated meaning different from that of an operator. For completeness these are specified below:
 
@@ -146,8 +141,7 @@ s|Description
 |===
 
 [[sql-syntax-operators]]
-[float]
-=== Operators
+==== Operators
 
 Most operators in {es-sql} have the same precedence and are left-associative. As this is done at parsing time, parenthesis need to be used to enforce a different precedence.
 
@@ -205,8 +199,7 @@ s|Description
 
 
 [[sql-syntax-comments]]
-[float]
-=== Comments
+==== Comments
 
 {es-sql} allows comments which are sequence of characters ignored by the parsers.
 
