Restructure ES|QL docs (#100806)

* Break out 'Limitations' into separate page

* Add REST API docs

* Restructure commands, functions, and operators refs

* Add placeholder for getting started guide

* Group 'Syntax', 'Metafields', and 'MV fields' under 'Language'

* Add placeholder for Kibana page

* Add link from landing page

* Apply uniform formatting to ACOS, CASE, and DATE_PARSE function refs

* Reword default LIMIT

* Add support for COUNT(*)

* Move 'Commands' and 'Functions and operators' to individual pages

---------

Co-authored-by: Elastic Machine <elasticmachine@users.noreply.github.com>

docs/reference/esql/aggregation-functions.asciidoc

@@ -1,30 +0,0 @@
-[[esql-agg-functions]]
-== {esql} aggregation functions
-
-++++
-<titleabbrev>Aggregation functions</titleabbrev>
-++++
-
-<<esql-stats-by>> support these functions:
-
-// tag::functions[]
-* <<esql-agg-avg>>
-* <<esql-agg-count>>
-* <<esql-agg-count-distinct>>
-* <<esql-agg-max>>
-* <<esql-agg-median>>
-* <<esql-agg-median-absolute-deviation>>
-* <<esql-agg-min>>
-* <<esql-agg-percentile>>
-* <<esql-agg-sum>>
-// end::functions[]
-
-include::aggregation-functions/avg.asciidoc[]
-include::aggregation-functions/count.asciidoc[]
-include::aggregation-functions/count-distinct.asciidoc[]
-include::aggregation-functions/max.asciidoc[]
-include::aggregation-functions/median.asciidoc[]
-include::aggregation-functions/median-absolute-deviation.asciidoc[]
-include::aggregation-functions/min.asciidoc[]
-include::aggregation-functions/percentile.asciidoc[]
-include::aggregation-functions/sum.asciidoc[]

docs/reference/esql/esql-commands.asciidoc

@@ -0,0 +1,17 @@
+[[esql-commands]]
+== {esql} commands
+
+++++
+<titleabbrev>Commands</titleabbrev>
+++++
+
+{esql} provides a comprehensive set of source and processing commands:
+
+<<esql-source-commands>>::
+include::source-commands/esql-source-commands.asciidoc[tag=list]
+
+<<esql-processing-commands>>::
+include::processing-commands/esql-processing-commands.asciidoc[tag=list]
+
+include::source-commands/esql-source-commands.asciidoc[]
+include::processing-commands/esql-processing-commands.asciidoc[]

docs/reference/esql/esql-functions-operators.asciidoc

@@ -0,0 +1,42 @@
+[[esql-functions-operators]]
+== {esql} functions and operators
+
+++++
+<titleabbrev>Functions and operators</titleabbrev>
+++++
+
+{esql} provides a comprehensive set of functions and operators:
+
+[[esql-functions]]
+<<esql-agg-functions>>::
+include::functions/aggregation-functions.asciidoc[tag=list]
+
+<<esql-math-functions>>::
+include::functions/math-functions.asciidoc[tag=list]
+
+<<esql-string-functions>>::
+include::functions/string-functions.asciidoc[tag=list]
+
+<<esql-date-time-functions>>::
+include::functions/date-time-functions.asciidoc[tag=list]
+
+<<esql-type-conversion-functions>>::
+include::functions/type-conversion-functions.asciidoc[tag=list]
+
+<<esql-conditional-functions-and-expressions>>::
+include::functions/conditional-functions-and-expressions.asciidoc[tag=list]
+
+<<esql-mv-functions>>::
+include::functions/mv-functions.asciidoc[tag=list]
+
+<<esql-operators>>::
+include::functions/operators.asciidoc[tag=list]
+
+include::functions/aggregation-functions.asciidoc[]
+include::functions/math-functions.asciidoc[]
+include::functions/string-functions.asciidoc[]
+include::functions/date-time-functions.asciidoc[]
+include::functions/type-conversion-functions.asciidoc[]
+include::functions/conditional-functions-and-expressions.asciidoc[]
+include::functions/mv-functions.asciidoc[]
+include::functions/operators.asciidoc[]

docs/reference/esql/esql-get-started.asciidoc

@@ -0,0 +1,8 @@
+[[esql-getting-started]]
+== Getting started with {esql}
+
+++++
+<titleabbrev>Getting started</titleabbrev>
+++++
+
+coming::[8.11]

docs/reference/esql/esql-kibana.asciidoc

@@ -0,0 +1,8 @@
+[[esql-kibana]]
+== Using {esql} in {kib}
+
+++++
+<titleabbrev>Kibana</titleabbrev>
+++++
+
+coming::[8.11]

docs/reference/esql/esql-language.asciidoc

@@ -0,0 +1,16 @@
+[[esql-language]]
+== {esql} language
+
+++++
+<titleabbrev>{esql} language</titleabbrev>
+++++
+
+Detailed information about the {esql} language:
+
+* <<esql-syntax>>
+* <<esql-multivalued-fields>>
+* <<esql-metadata-fields>>
+
+include::esql-syntax.asciidoc[]
+include::multivalued-fields.asciidoc[]
+include::metadata-fields.asciidoc[]

docs/reference/esql/esql-limitations.asciidoc

@@ -0,0 +1,32 @@
+[[esql-limitations]]
+== {esql} limitations
+
+++++
+<titleabbrev>Limitations</titleabbrev>
+++++
+
+[discrete]
+[[esql-supported-types]]
+=== Supported types
+
+* {esql} currently supports the following <<mapping-types,field types>>:
+
+** `alias`
+** `boolean`
+** `date`
+** `double` (`float`, `half_float`, `scaled_float` are represented as `double`)
+** `ip`
+** `keyword` family including `keyword`, `constant_keyword`, and `wildcard`
+** `int` (`short` and `byte` are represented as `int`)
+** `long`
+** `null`
+** `text`
+** `unsigned_long`
+** `version`
+
+[discrete]
+[[esql-max-rows]]
+=== 10,000 row maximum
+
+A single query will not return more than 10,000 rows, regardless of the
+`LIMIT` command's value.

docs/reference/esql/esql-processing-commands.asciidoc

@@ -1,39 +0,0 @@
-[[esql-processing-commands]]
-== {esql} processing commands
-
-++++
-<titleabbrev>Processing commands</titleabbrev>
-++++
-
-{esql} processing commands change an input table by adding, removing, or changing
-rows and columns.
-
-image::images/esql/processing-command.svg[A processing command changing an input table,align="center"]
-
-{esql} supports these processing commands:
-
-* <<esql-dissect>>
-* <<esql-drop>>
-* <<esql-enrich>>
-* <<esql-eval>>
-* <<esql-grok>>
-* <<esql-keep>>
-* <<esql-limit>>
-* <<esql-mv_expand>>
-* <<esql-rename>>
-* <<esql-sort>>
-* <<esql-stats-by>>
-* <<esql-where>>
-
-include::processing-commands/dissect.asciidoc[]
-include::processing-commands/drop.asciidoc[]
-include::processing-commands/enrich.asciidoc[]
-include::processing-commands/eval.asciidoc[]
-include::processing-commands/grok.asciidoc[]
-include::processing-commands/keep.asciidoc[]
-include::processing-commands/limit.asciidoc[]
-include::processing-commands/mv_expand.asciidoc[]
-include::processing-commands/rename.asciidoc[]
-include::processing-commands/sort.asciidoc[]
-include::processing-commands/stats.asciidoc[]
-include::processing-commands/where.asciidoc[]

docs/reference/esql/esql-query-api.asciidoc

@@ -0,0 +1,84 @@
+[[esql-query-api]]
+== {esql} query API
+++++
+<titleabbrev>{esql} query API</titleabbrev>
+++++
+
+Returns search results for an <<esql,ES|QL ({es} query language)>> query.
+
+include::index.asciidoc[tag=esql-query-api-example]
+
+[discrete]
+[[esql-query-api-request]]
+=== {api-request-title}
+
+`POST _query`
+
+[discrete]
+[[esql-query-api-prereqs]]
+=== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have the `read`
+<<privileges-list-indices,index privilege>> for the data stream, index,
+or alias you search.
+
+[discrete]
+[[esql-query-api-query-params]]
+=== {api-query-parms-title}
+
+`delimiter`::
+(Optional, string) Separator for CSV results. Defaults to `,`. The API only
+supports this parameter for CSV responses.
+
+`format`::
+(Optional, string) Format for the response. For valid values, refer to
+<<esql-rest-format>>.
++
+You can also specify a format using the `Accept` HTTP header. If you specify
+both this parameter and the `Accept` HTTP header, this parameter takes
+precedence.
+
+[discrete]
+[role="child_attributes"]
+[[esql-query-api-request-body]]
+=== {api-request-body-title}
+
+`columnar`::
+(Optional, Boolean) If `true`, returns results in a columnar format. Defaults to
+`false`. The API only supports this parameter for CBOR, JSON, SMILE, and YAML
+responses. See <<esql-rest-columnar>>.
+
+`params`::
+(Optional, array) Values for parameters in the `query`. For syntax, refer to
+<<esql-rest-params>>.
+
+`query`::
+(Required, object) {esql} query to run. For syntax, refer to <<esql-syntax>>.
+
+[[esql-search-api-time-zone]]
+`time_zone`::
+(Optional, string) ISO-8601 time zone ID for the search. Several {esql}
+date/time functions use this time zone. Defaults to `Z` (UTC).
+
+[discrete]
+[role="child_attributes"]
+[[esql-query-api-response-body]]
+=== {api-response-body-title}
+
+`columns`::
+(array of objects)
+Column headings for the search results. Each object is a column.
++
+.Properties of `columns` objects
+[%collapsible%open]
+====
+`name`::
+(string) Name of the column.
+
+`type`::
+(string) Data type for the column.
+====
+
+`rows`::
+(array of arrays)
+Values for the search results.

docs/reference/esql/esql-rest.asciidoc

@@ -0,0 +1,246 @@
+[[esql-rest]]
+== {esql} REST API
+
+++++
+<titleabbrev>REST API</titleabbrev>
+++++
+
+[discrete]
+[[esql-rest-overview]]
+=== Overview
+
+The <<esql-query-api,{esql} query API>> accepts an {esql} query string in the
+`query` parameter, runs it, and returns the results. For example:
+
+[source,console]
+----
+POST /_query?format=txt
+{
+  "query": "FROM library | KEEP author, name, page_count, release_date | SORT page_count DESC | LIMIT 5"
+}
+----
+// 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[non_json]
+
+[discrete]
+[[esql-kibana-console]]
+=== 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 supports multi-line requests:
+
+[source,console]
+----
+POST /_query?format=txt
+{
+  "query": """
+    FROM library
+    | KEEP author, name, page_count, release_date
+    | SORT page_count DESC
+    | LIMIT 5
+  """
+}
+----
+// TEST[setup:library]
+
+[discrete]
+[[esql-rest-format]]
+=== Response formats
+
+{esql} can return the data in the following human readable and binary formats.
+You can set the format by specifying the `format` parameter in the URL or by
+setting the `Accept` or `Content-Type` HTTP header.
+
+NOTE: The URL parameter takes precedence over the HTTP headers. If neither is
+specified then the response is returned in the same format as the request.
+
+[cols="m,4m,8"]
+
+|===
+s|`format`
+s|HTTP header
+s|Description
+
+3+h| Human readable
+
+|csv
+|text/csv
+|{wikipedia}/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
+|{wikipedia}/Tab-separated_values[Tab-separated values]
+
+|txt
+|text/plain
+|CLI-like representation
+
+|yaml
+|application/yaml
+|{wikipedia}/YAML[YAML] (YAML Ain't Markup Language) human-readable format
+
+3+h| Binary
+
+|cbor
+|application/cbor
+|https://cbor.io/[Concise Binary Object Representation]
+
+|smile
+|application/smile
+|{wikipedia}/Smile_(data_interchange_format)[Smile] binary data format similar 
+to CBOR
+
+|===
+
+The `csv` format accepts a formatting URL query attribute, `delimiter`, which
+indicates which character should be used to separate the CSV values. It defaults
+to comma (`,`) and cannot take any of the following values: double quote (`"`),
+carriage-return (`\r`) and new-line (`\n`). The tab (`\t`) can also not be used.
+Use the `tsv` format instead.
+
+[discrete]
+[[esql-rest-filtering]]
+=== Filtering using {es} Query DSL
+
+Specify a Query DSL query in the `filter` parameter to filter the set of
+documents that an {esql} query runs on.
+
+[source,console]
+----
+POST /_query?format=txt
+{
+  "query": """
+    FROM library
+    | KEEP author, name, page_count, release_date
+    | SORT page_count DESC
+    | LIMIT 5
+  """,
+  "filter": {
+    "range": {
+      "page_count": {
+        "gte": 100,
+        "lte": 200
+      }
+    }
+  }
+}
+----
+// TEST[setup:library]
+
+Which returns:
+
+[source,text]
+--------------------------------------------------
+    author     |                name                |  page_count   | release_date
+---------------+------------------------------------+---------------+------------------------
+Douglas Adams  |The Hitchhiker's Guide to the Galaxy|180            |1979-10-12T00:00:00.000Z
+--------------------------------------------------
+// TESTRESPONSE[s/\|/\\|/ s/\+/\\+/]
+// TESTRESPONSE[non_json]
+
+[discrete]
+[[esql-rest-columnar]]
+=== Columnar results
+
+By default, {esql} returns results as rows. For example, `FROM` returns each
+individual document as one row. For the `json`, `yaml`, `cbor` and `smile`
+<<esql-rest-format,formats>>, {esql} can return the results in a columnar
+fashion where one row represents all the values of a certain column in the
+results.
+
+[source,console]
+----
+POST /_query?format=json
+{
+  "query": """
+    FROM library
+    | KEEP author, name, page_count, release_date
+    | SORT page_count DESC
+    | LIMIT 5
+  """,
+  "columnar": true
+}
+----
+// TEST[setup:library]
+
+Which returns:
+
+[source,console-result]
+----
+{
+  "columns": [
+    {"name": "author", "type": "text"},
+    {"name": "name", "type": "text"},
+    {"name": "page_count", "type": "integer"},
+    {"name": "release_date", "type": "date"}
+  ],
+  "values": [
+    ["Peter F. Hamilton", "Vernor Vinge", "Frank Herbert", "Alastair Reynolds", "James S.A. Corey"],
+    ["Pandora's Star", "A Fire Upon the Deep", "Dune", "Revelation Space", "Leviathan Wakes"],
+    [768, 613, 604, 585, 561],
+    ["2004-03-02T00:00:00.000Z", "1992-06-01T00:00:00.000Z", "1965-06-01T00:00:00.000Z", "2000-03-15T00:00:00.000Z", "2011-06-02T00:00:00.000Z"]
+  ]
+}
+----
+
+[discrete]
+[[esql-rest-params]]
+=== Passing parameters to a query
+
+Values, for example for a condition, can be passed to a query "inline", by
+integrating the value in the query string itself:
+
+[source,console]
+----
+POST /_query
+{
+  "query": """
+    FROM library
+    | EVAL year = DATE_EXTRACT("year", release_date)
+    | WHERE page_count > 300 AND author == "Frank Herbert"
+    | STATS count = COUNT(*) by year
+    | WHERE count > 0
+  """
+}
+----
+// TEST[setup:library]
+
+To avoid any attempts of hacking or code injection, extract the values in a
+separate list of parameters. Use question mark placeholders (`?`) in the query
+string for each of the parameters:
+
+[source,console]
+----
+POST /_query
+{
+  "query": """
+    FROM library
+    | EVAL year = DATE_EXTRACT("year", release_date)
+    | WHERE page_count > ? AND author == ?
+    | STATS count = COUNT(*) by year
+    | WHERE count > ?
+  """,
+  "params": [300, "Frank Herbert", 0]
+}
+----
+// TEST[setup:library]

docs/reference/esql/esql-syntax.asciidoc

@@ -1,5 +1,5 @@
 [[esql-syntax]]
-== {esql} syntax reference
+=== {esql} syntax reference
 
 ++++
 <titleabbrev>Syntax reference</titleabbrev>
@@ -22,18 +22,23 @@ source-command
 
 The result of a query is the table produced by the final processing command.
 
-For readability, this documentation puts each processing command on a new line.
-However, you can write an {esql} query as a single line. The following query is
-identical to the previous one:
+For an overview of all supported commands, functions, and operators, refer to <<esql-commands>> and <<esql-functions-operators>>.
+
+[NOTE]
+====
+For readability, this documentation puts each processing command on a new
+line. However, you can write an {esql} query as a single line. The following
+query is identical to the previous one:
 
 [source,esql]
 ----
 source-command | processing-command1 | processing-command2
 ----
+====
 
 [discrete]
 [[esql-comments]]
-=== Comments
+==== Comments
 {esql} uses C++ style comments:
 
 * double slash `//` for single line comments
@@ -61,86 +66,9 @@ FROM employees
 | WHERE height > 2
 ----
 
-[discrete]
-[[esql-operators]]
-=== Operators
-These binary comparison operators are supported:
-
-* equality: `==`
-* inequality: `!=`
-* less than: `<`
-* less than or equal: `<=`
-* larger than: `>`
-* larger than or equal: `>=`
-
-The `IN` operator allows testing whether a field or expression equals
-an element in a list of literals, fields or expressions:
-
-[source,esql]
-----
-include::{esql-specs}/row.csv-spec[tag=in-with-expressions]
-----
-
-For string comparison using wildcards or regular expressions, use `LIKE` or
-`RLIKE`:
-
-* Use `LIKE` to match strings using wildcards. The following wildcard characters
-are supported:
-+
---
-** `*` matches zero or more characters.
-** `?` matches one character.
-
-[source,esql]
-----
-FROM employees
-| WHERE first_name LIKE "?b*"
-| KEEP first_name, last_name
-----
---
-
-* Use `RLIKE` to match strings using <<regexp-syntax,regular expressions>>:
-+
-[source,esql]
-----
-FROM employees
-| WHERE first_name RLIKE ".leja.*"
-| KEEP first_name, last_name
-----
-
-The following boolean operators are supported:
-
-* `AND`
-* `OR`
-* `NOT`
-
-[discrete]
-[[esql-predicates]]
-=== Predicates
-
-For NULL comparison use the `IS NULL` and `IS NOT NULL` predicates:
-
-[source.merge.styled,esql]
-----
-include::{esql-specs}/null.csv-spec[tag=is-null]
-----
-[%header.monospaced.styled,format=dsv,separator=|]
-|===
-include::{esql-specs}/null.csv-spec[tag=is-null-result]
-|===
-
-[source.merge.styled,esql]
-----
-include::{esql-specs}/null.csv-spec[tag=is-not-null]
-----
-[%header.monospaced.styled,format=dsv,separator=|]
-|===
-include::{esql-specs}/null.csv-spec[tag=is-not-null-result]
-|===
-
 [discrete]
 [[esql-timespan-literals]]
-=== Timespan literals
+==== Timespan literals
 
 Datetime intervals and timespans can be expressed using timespan literals.
 Timespan literals are a combination of a number and a qualifier. These

docs/reference/esql/functions/abs.asciidoc

@@ -1,3 +1,4 @@
+[discrete]
 [[esql-abs]]
 === `ABS`
 [.text-center]

docs/reference/esql/functions/acos.asciidoc

@@ -1,9 +1,27 @@
+[discrete]
 [[esql-acos]]
 === `ACOS`
+
+*Syntax*
+
 [.text-center]
 image::esql/functions/signature/acos.svg[Embedded,opts=inline]
 
-Inverse https://en.wikipedia.org/wiki/Inverse_trigonometric_functions[cosine] trigonometric function.
+*Parameters*
+
+`n`::
+Numeric expression. If `null`, the function returns `null`.
+
+*Description*
+
+Returns the {wikipedia}/Inverse_trigonometric_functions[arccosine] of `n` as an
+angle, expressed in radians.
+
+*Supported types*
+
+include::types/acos.asciidoc[]
+
+*Example*
 
 [source.merge.styled,esql]
 ----
@@ -13,7 +31,3 @@ include::{esql-specs}/floats.csv-spec[tag=acos]
 |===
 include::{esql-specs}/floats.csv-spec[tag=acos-result]
 |===
-
-Supported types:
-
-include::types/acos.asciidoc[]

docs/reference/esql/functions/aggregation-functions.asciidoc

@@ -0,0 +1,30 @@
+[[esql-agg-functions]]
+=== {esql} aggregate functions
+
+++++
+<titleabbrev>Aggregate functions</titleabbrev>
+++++
+
+The <<esql-stats-by>> function supports these aggregate functions:
+
+// tag::list[]
+* <<esql-agg-avg>>
+* <<esql-agg-count>>
+* <<esql-agg-count-distinct>>
+* <<esql-agg-max>>
+* <<esql-agg-median>>
+* <<esql-agg-median-absolute-deviation>>
+* <<esql-agg-min>>
+* <<esql-agg-percentile>>
+* <<esql-agg-sum>>
+// end::list[]
+
+include::avg.asciidoc[]
+include::count.asciidoc[]
+include::count-distinct.asciidoc[]
+include::max.asciidoc[]
+include::median.asciidoc[]
+include::median-absolute-deviation.asciidoc[]
+include::min.asciidoc[]
+include::percentile.asciidoc[]
+include::sum.asciidoc[]

docs/reference/esql/functions/asin.asciidoc

@@ -1,3 +1,4 @@
+[discrete]
 [[esql-asin]]
 === `ASIN`
 [.text-center]

docs/reference/esql/functions/atan.asciidoc

@@ -1,3 +1,4 @@
+[discrete]
 [[esql-atan]]
 === `ATAN`
 [.text-center]

docs/reference/esql/functions/atan2.asciidoc

@@ -1,3 +1,4 @@
+[discrete]
 [[esql-atan2]]
 === `ATAN2`
 [.text-center]

docs/reference/esql/functions/auto_bucket.asciidoc

@@ -1,3 +1,4 @@
+[discrete]
 [[esql-auto_bucket]]
 === `AUTO_BUCKET`
 Creates human-friendly buckets and returns a `datetime` value for each row that

docs/reference/esql/aggregation-functions/avg.asciidoc → docs/reference/esql/functions/avg.asciidoc

@@ -1,3 +1,4 @@
+[discrete]
 [[esql-agg-avg]]
 === `AVG`
 The average of a numeric field.

docs/reference/esql/functions/binary.asciidoc

@@ -0,0 +1,12 @@
+[discrete]
+[[esql-binary-operators]]
+=== Binary operators
+
+These binary comparison operators are supported:
+
+* equality: `==`
+* inequality: `!=`
+* less than: `<`
+* less than or equal: `<=`
+* larger than: `>`
+* larger than or equal: `>=`

docs/reference/esql/functions/case.asciidoc

@@ -1,17 +1,42 @@
+[discrete]
 [[esql-case]]
 === `CASE`
 
+*Syntax*
+
+[source,txt]
+----
+CASE(condition1, value1[, ..., conditionN, valueN][, default_value])
+----
+
+*Parameters*
+
+`conditionX`::
+A condition.
+
+`valueX`:: 
+The value that's returned when the corresponding condition is the first to
+evaluate to `true`.
+
+`default_value`::
+The default value that's is returned when no condition matches.
+
+*Description*
+
 Accepts pairs of conditions and values. The function returns the value that
-belongs to the first condition that evaluates to `true`. If the number of
-arguments is odd, the last argument is the default value which is returned when
-no condition matches.
+belongs to the first condition that evaluates to `true`.
+
+If the number of arguments is odd, the last argument is the default value which
+is returned when no condition matches.
+
+*Example*
 
 [source,esql]
+[source.merge.styled,esql]
 ----
-FROM employees
-| EVAL type = CASE(
-    languages <= 1, "monolingual",
-    languages <= 2, "bilingual",
-     "polyglot")
-| KEEP first_name, last_name, type
+include::{esql-specs}/docs.csv-spec[tag=case]
 ----
+[%header.monospaced.styled,format=dsv,separator=|]
+|===
+include::{esql-specs}/docs.csv-spec[tag=case-result]
+|===

docs/reference/esql/functions/ceil.asciidoc

@@ -1,3 +1,4 @@
+[discrete]
 [[esql-ceil]]
 === `CEIL`
 [.text-center]

docs/reference/esql/functions/cidr_match.asciidoc

@@ -1,3 +1,4 @@
+[discrete]
 [[esql-cidr_match]]
 === `CIDR_MATCH`
 

docs/reference/esql/functions/coalesce.asciidoc

@@ -1,3 +1,4 @@
+[discrete]
 [[esql-coalesce]]
 === `COALESCE`
 

docs/reference/esql/functions/concat.asciidoc

@@ -1,3 +1,4 @@
+[discrete]
 [[esql-concat]]
 === `CONCAT`
 Concatenates two or more strings.

docs/reference/esql/functions/conditional-functions-and-expressions.asciidoc

@@ -0,0 +1,21 @@
+[[esql-conditional-functions-and-expressions]]
+=== {esql} conditional functions and expressions
+
+++++
+<titleabbrev>Conditional functions and expressions</titleabbrev>
+++++
+
+Conditional functions return one of their arguments by evaluating in an if-else
+manner. {esql} supports these conditional functions: 
+
+// tag::list[]
+* <<esql-case>>
+* <<esql-coalesce>>
+* <<esql-greatest>>
+* <<esql-least>>
+// end::list[]
+
+include::case.asciidoc[]
+include::coalesce.asciidoc[]
+include::greatest.asciidoc[]
+include::least.asciidoc[]

docs/reference/esql/functions/cos.asciidoc

@@ -1,3 +1,4 @@
+[discrete]
 [[esql-cos]]
 === `COS`
 [.text-center]

docs/reference/esql/functions/cosh.asciidoc

@@ -1,3 +1,4 @@
+[discrete]
 [[esql-cosh]]
 === `COSH`
 [.text-center]

docs/reference/esql/aggregation-functions/count-distinct.asciidoc → docs/reference/esql/functions/count-distinct.asciidoc

@@ -1,3 +1,4 @@
+[discrete]
 [[esql-agg-count-distinct]]
 === `COUNT_DISTINCT`
 The approximate number of distinct values.
@@ -14,6 +15,7 @@ include::{esql-specs}/stats_count_distinct.csv-spec[tag=count-distinct-result]
 Can take any field type as input and the result is always a `long` not matter
 the input type.
 
+[discrete]
 ==== Counts are approximate
 
 Computing exact counts requires loading values into a set and returning its
@@ -28,6 +30,7 @@ properties:
 
 include::../../aggregations/metrics/cardinality-aggregation.asciidoc[tag=explanation]
 
+[discrete]
 ==== Precision is configurable
 
 The `COUNT_DISTINCT` function takes an optional second parameter to configure the

docs/reference/esql/aggregation-functions/count.asciidoc → docs/reference/esql/functions/count.asciidoc

@@ -1,3 +1,4 @@
+[discrete]
 [[esql-agg-count]]
 === `COUNT`
 Counts field values.
@@ -14,5 +15,13 @@ include::{esql-specs}/stats.csv-spec[tag=count-result]
 Can take any field type as input and the result is always a `long` not matter
 the input type.
 
-NOTE: There isn't yet a `COUNT(*)`. Please count a single valued field if you
-      need a count of rows.
+To count the number of rows, use `COUNT(*)`:
+
+[source.merge.styled,esql]
+----
+include::{esql-specs}/docs.csv-spec[tag=countAll]
+----
+[%header.monospaced.styled,format=dsv,separator=|]
+|===
+include::{esql-specs}/docs.csv-spec[tag=countAll-result]
+|===

docs/reference/esql/functions/date-time-functions.asciidoc

@@ -0,0 +1,24 @@
+[[esql-date-time-functions]]
+=== {esql} date-time functions
+
+++++
+<titleabbrev>Date-time functions</titleabbrev>
+++++
+
+{esql} supports these date-time functions:
+
+// tag::list[]
+* <<esql-auto_bucket>>
+* <<esql-date_extract>>
+* <<esql-date_format>>
+* <<esql-date_parse>>
+* <<esql-date_trunc>>
+* <<esql-now>>
+// end::list[]
+
+include::auto_bucket.asciidoc[]
+include::date_extract.asciidoc[]
+include::date_format.asciidoc[]
+include::date_parse.asciidoc[]
+include::date_trunc.asciidoc[]
+include::now.asciidoc[]

docs/reference/esql/functions/date_extract.asciidoc

@@ -1,7 +1,8 @@
+[discrete]
 [[esql-date_extract]]
 === `DATE_EXTRACT`
 Extracts parts of a date, like year, month, day, hour.
-The supported field types are those provided by https://docs.oracle.com/javase/8/docs/api/java/time/temporal/ChronoField.html[java.time.temporal.ChronoField]
+The supported field types are those provided by https://docs.oracle.com/javase/8/docs/api/java/time/temporal/ChronoField.html[java.time.temporal.ChronoField].
 
 [source.merge.styled,esql]
 ----

docs/reference/esql/functions/date_format.asciidoc

@@ -1,3 +1,4 @@
+[discrete]
 [[esql-date_format]]
 === `DATE_FORMAT`
 Returns a string representation of a date in the provided format. If no format

docs/reference/esql/functions/date_parse.asciidoc

@@ -1,9 +1,37 @@
+[discrete]
 [[esql-date_parse]]
 === `DATE_PARSE`
-Converts a string to a date, in the provided format. If no format
-is specified, the `yyyy-MM-dd'T'HH:mm:ss.SSSZ` format is used.
+
+*Syntax*
+
+[source,txt]
+----
+DATE_PARSE([format,] date_string)
+----
+
+*Parameters*
+
+`format`::
+The date format. Refer to the
+https://docs.oracle.com/en/java/javase/14/docs/api/java.base/java/time/format/DateTimeFormatter.html[`DateTimeFormatter`
+documentation] for the syntax. If `null`, the function returns `null`.
+
+`date_string`::
+Date expression as a string. If `null` or an empty string, the function returns
+`null`.
+
+*Description*
+
+Returns a date by parsing the second argument using the format specified in the
+first argument.
+
+*Example*
 
 [source.merge.styled,esql]
 ----
 include::{esql-specs}/docs.csv-spec[tag=dateParse]
 ----
+[%header.monospaced.styled,format=dsv,separator=|]
+|===
+include::{esql-specs}/docs.csv-spec[tag=dateParse-result]
+|===

docs/reference/esql/functions/date_trunc.asciidoc

@@ -1,3 +1,4 @@
+[discrete]
 [[esql-date_trunc]]
 === `DATE_TRUNC`
 Rounds down a date to the closest interval. Intervals can be expressed using the

docs/reference/esql/functions/e.asciidoc

@@ -1,3 +1,4 @@
+[discrete]
 [[esql-e]]
 === `E`
 [.text-center]

docs/reference/esql/functions/ends_with.asciidoc

@@ -1,3 +1,4 @@
+[discrete]
 [[esql-ends_with]]
 === `ENDS_WITH`
 [.text-center]

docs/reference/esql/functions/floor.asciidoc

@@ -1,3 +1,4 @@
+[discrete]
 [[esql-floor]]
 === `FLOOR`
 [.text-center]

docs/reference/esql/functions/greatest.asciidoc

@@ -1,3 +1,4 @@
+[discrete]
 [[esql-greatest]]
 === `GREATEST`
 [.text-center]

docs/reference/esql/functions/in.asciidoc

@@ -0,0 +1,11 @@
+[discrete]
+[[esql-in-operator]]
+=== `IN`
+
+The `IN` operator allows testing whether a field or expression equals
+an element in a list of literals, fields or expressions:
+
+[source,esql]
+----
+include::{esql-specs}/row.csv-spec[tag=in-with-expressions]
+----

docs/reference/esql/functions/is_finite.asciidoc

@@ -1,3 +1,4 @@
+[discrete]
 [[esql-is_finite]]
 === `IS_FINITE`
 Returns a boolean that indicates whether its input is a finite number.

docs/reference/esql/functions/is_infinite.asciidoc

@@ -1,3 +1,4 @@
+[discrete]
 [[esql-is_infinite]]
 === `IS_INFINITE`
 Returns a boolean that indicates whether its input is infinite.

docs/reference/esql/functions/is_nan.asciidoc

@@ -1,3 +1,4 @@
+[discrete]
 [[esql-is_nan]]
 === `IS_NAN`
 Returns a boolean that indicates whether its input is not a number.

docs/reference/esql/functions/least.asciidoc

@@ -1,3 +1,4 @@
+[discrete]
 [[esql-least]]
 === `LEAST`
 [.text-center]

docs/reference/esql/functions/left.asciidoc

@@ -1,3 +1,4 @@
+[discrete]
 [[esql-left]]
 === `LEFT`
 [.text-center]

docs/reference/esql/functions/length.asciidoc

@@ -1,3 +1,4 @@
+[discrete]
 [[esql-length]]
 === `LENGTH`
 Returns the character length of a string.

docs/reference/esql/functions/like.asciidoc

@@ -0,0 +1,20 @@
+[discrete]
+[[esql-like-operator]]
+=== `LIKE`
+
+Use `LIKE` to filter data based on string patterns using wildcards. `LIKE`
+usually acts on a field placed on the left-hand side of the operator, but it can
+also act on a constant (literal) expression. The right-hand side of the operator
+represents the pattern.
+
+The following wildcard characters are supported:
+
+* `*` matches zero or more characters.
+* `?` matches one character.
+
+[source,esql]
+----
+FROM employees
+| WHERE first_name LIKE "?b*"
+| KEEP first_name, last_name
+----

docs/reference/esql/functions/log10.asciidoc

@@ -1,3 +1,4 @@
+[discrete]
 [[esql-log10]]
 === `LOG10`
 [.text-center]

docs/reference/esql/functions/logical.asciidoc

@@ -0,0 +1,9 @@
+[discrete]
+[[esql-logical-operators]]
+=== Logical operators
+
+The following logical operators are supported:
+
+* `AND`
+* `OR`
+* `NOT`

docs/reference/esql/functions/ltrim.asciidoc

@@ -1,3 +1,4 @@
+[discrete]
 [[esql-ltrim]]
 === `LTRIM`
 Removes leading whitespaces from strings.

docs/reference/esql/functions/math-functions.asciidoc

@@ -0,0 +1,52 @@
+[[esql-math-functions]]
+=== {esql} mathematical functions
+
+++++
+<titleabbrev>Mathematical functions</titleabbrev>
+++++
+
+{esql} supports these mathematical functions:
+
+// tag::list[]
+* <<esql-abs>>
+* <<esql-acos>>
+* <<esql-asin>>
+* <<esql-atan>>
+* <<esql-atan2>>
+* <<esql-ceil>>
+* <<esql-cos>>
+* <<esql-cosh>>
+* <<esql-e>>
+* <<esql-floor>>
+* <<esql-log10>>
+* <<esql-pi>>
+* <<esql-pow>>
+* <<esql-round>>
+* <<esql-sin>>
+* <<esql-sinh>>
+* <<esql-sqrt>>
+* <<esql-tan>>
+* <<esql-tanh>>
+* <<esql-tau>>
+// end::list[]
+
+include::abs.asciidoc[]
+include::acos.asciidoc[]
+include::asin.asciidoc[]
+include::atan.asciidoc[]
+include::atan2.asciidoc[]
+include::ceil.asciidoc[]
+include::cos.asciidoc[]
+include::cosh.asciidoc[]
+include::e.asciidoc[]
+include::floor.asciidoc[]
+include::log10.asciidoc[]
+include::pi.asciidoc[]
+include::pow.asciidoc[]
+include::round.asciidoc[]
+include::sin.asciidoc[]
+include::sinh.asciidoc[]
+include::sqrt.asciidoc[]
+include::tan.asciidoc[]
+include::tanh.asciidoc[]
+include::tau.asciidoc[]

docs/reference/esql/aggregation-functions/max.asciidoc → docs/reference/esql/functions/max.asciidoc

@@ -1,3 +1,4 @@
+[discrete]
 [[esql-agg-max]]
 === `MAX`
 The maximum value of a numeric field.

docs/reference/esql/aggregation-functions/median-absolute-deviation.asciidoc → docs/reference/esql/functions/median-absolute-deviation.asciidoc

@@ -1,3 +1,4 @@
+[discrete]
 [[esql-agg-median-absolute-deviation]]
 === `MEDIAN_ABSOLUTE_DEVIATION`
 The median absolute deviation, a measure of variability. It is a robust

docs/reference/esql/aggregation-functions/median.asciidoc → docs/reference/esql/functions/median.asciidoc

@@ -1,3 +1,4 @@
+[discrete]
 [[esql-agg-median]]
 === `MEDIAN`
 The value that is greater than half of all values and less than half of

docs/reference/esql/aggregation-functions/min.asciidoc → docs/reference/esql/functions/min.asciidoc

@@ -1,3 +1,4 @@
+[discrete]
 [[esql-agg-min]]
 === `MIN`
 The minimum value of a numeric field.

docs/reference/esql/functions/mv-functions.asciidoc

@@ -0,0 +1,28 @@
+[[esql-mv-functions]]
+=== {esql} multivalue functions
+
+++++
+<titleabbrev>Multivalue functions</titleabbrev>
+++++
+
+{esql} supports these multivalue functions:
+
+// tag::list[]
+* <<esql-mv_avg>>
+* <<esql-mv_concat>>
+* <<esql-mv_count>>
+* <<esql-mv_dedupe>>
+* <<esql-mv_max>>
+* <<esql-mv_median>>
+* <<esql-mv_min>>
+* <<esql-mv_sum>>
+// end::list[]
+
+include::mv_avg.asciidoc[]
+include::mv_concat.asciidoc[]
+include::mv_count.asciidoc[]
+include::mv_dedupe.asciidoc[]
+include::mv_max.asciidoc[]
+include::mv_median.asciidoc[]
+include::mv_min.asciidoc[]
+include::mv_sum.asciidoc[]

docs/reference/esql/functions/mv_avg.asciidoc

@@ -1,3 +1,4 @@
+[discrete]
 [[esql-mv_avg]]
 === `MV_AVG`
 Converts a multivalued field into a single valued field containing the average

docs/reference/esql/functions/mv_concat.asciidoc

@@ -1,3 +1,4 @@
+[discrete]
 [[esql-mv_concat]]
 === `MV_CONCAT`
 Converts a multivalued string field into a single valued field containing the

docs/reference/esql/functions/mv_count.asciidoc

@@ -1,3 +1,4 @@
+[discrete]
 [[esql-mv_count]]
 === `MV_COUNT`
 Converts a multivalued field into a single valued field containing a count of the number

docs/reference/esql/functions/mv_dedupe.asciidoc

@@ -1,3 +1,4 @@
+[discrete]
 [[esql-mv_dedupe]]
 === `MV_DEDUPE`
 Removes duplicates from a multivalued field. For example:

docs/reference/esql/functions/mv_max.asciidoc

@@ -1,3 +1,4 @@
+[discrete]
 [[esql-mv_max]]
 === `MV_MAX`
 Converts a multivalued field into a single valued field containing the maximum value. For example:

docs/reference/esql/functions/mv_median.asciidoc

@@ -1,3 +1,4 @@
+[discrete]
 [[esql-mv_median]]
 === `MV_MEDIAN`
 Converts a multivalued field into a single valued field containing the median value. For example:

docs/reference/esql/functions/mv_min.asciidoc

@@ -1,3 +1,4 @@
+[discrete]
 [[esql-mv_min]]
 === `MV_MIN`
 Converts a multivalued field into a single valued field containing the minimum value. For example:

docs/reference/esql/functions/mv_sum.asciidoc

@@ -1,3 +1,4 @@
+[discrete]
 [[esql-mv_sum]]
 === `MV_SUM`
 Converts a multivalued field into a single valued field containing the sum

docs/reference/esql/functions/now.asciidoc

@@ -1,3 +1,4 @@
+[discrete]
 [[esql-now]]
 === `NOW`
 Returns current date and time.

docs/reference/esql/functions/operators.asciidoc

@@ -0,0 +1,36 @@
+[[esql-operators]]
+=== {esql} operators
+
+++++
+<titleabbrev>Operators</titleabbrev>
+++++
+
+Boolean operators for comparing against one or multiple expressions.
+
+// tag::list[]
+* <<esql-binary-operators>>
+* <<esql-logical-operators>>
+* <<esql-predicates>>
+* <<esql-cidr_match>>
+* <<esql-ends_with>>
+* <<esql-in-operator>>
+* <<esql-is_finite>>
+* <<esql-is_infinite>>
+* <<esql-is_nan>>
+* <<esql-like-operator>>
+* <<esql-rlike-operator>>
+* <<esql-starts_with>>
+// end::list[]
+
+include::binary.asciidoc[]
+include::logical.asciidoc[]
+include::predicates.asciidoc[]
+include::cidr_match.asciidoc[]
+include::ends_with.asciidoc[]
+include::in.asciidoc[]
+include::is_finite.asciidoc[]
+include::is_infinite.asciidoc[]
+include::is_nan.asciidoc[]
+include::like.asciidoc[]
+include::rlike.asciidoc[]
+include::starts_with.asciidoc[]

docs/reference/esql/aggregation-functions/percentile.asciidoc → docs/reference/esql/functions/percentile.asciidoc

@@ -1,3 +1,4 @@
+[discrete]
 [[esql-agg-percentile]]
 === `PERCENTILE`
 The value at which a certain percentage of observed values occur. For example,
@@ -13,6 +14,7 @@ include::{esql-specs}/stats_percentile.csv-spec[tag=percentile]
 include::{esql-specs}/stats_percentile.csv-spec[tag=percentile-result]
 |===
 
+[discrete]
 [[esql-agg-percentile-approximate]]
 ==== `PERCENTILE` is (usually) approximate
 

docs/reference/esql/functions/pi.asciidoc

@@ -1,3 +1,4 @@
+[discrete]
 [[esql-pi]]
 === `PI`
 [.text-center]

docs/reference/esql/functions/pow.asciidoc

@@ -1,3 +1,4 @@
+[discrete]
 [[esql-pow]]
 === `POW`
 [.text-center]
@@ -15,6 +16,7 @@ include::{esql-specs}/math.csv-spec[tag=powDI]
 include::{esql-specs}/math.csv-spec[tag=powDI-result]
 |===
 
+[discrete]
 ==== Type rules
 
 The type of the returned value is determined by the types of the base and exponent.
@@ -40,6 +42,7 @@ This means that for very large non-floating point values there is a small chance
 operation can lead to slightly different answers than expected.
 However, a more likely outcome of very large non-floating point values is numerical overflow.
 
+[discrete]
 ==== Arithmetic errors
 
 Arithmetic errors and numeric overflow do not result in an error. Instead, the result will be `null`
@@ -70,6 +73,7 @@ include::{esql-specs}/math.csv-spec[tag=pow2d]
 include::{esql-specs}/math.csv-spec[tag=pow2d-result]
 |===
 
+[discrete]
 ==== Fractional exponents
 
 The exponent can be a fraction, which is similar to performing a root.
@@ -84,6 +88,7 @@ include::{esql-specs}/math.csv-spec[tag=powID-sqrt]
 include::{esql-specs}/math.csv-spec[tag=powID-sqrt-result]
 |===
 
+[discrete]
 ==== Table of supported input and output types
 
 For clarity, the following table describes the output result type for all combinations of numeric input types:

docs/reference/esql/functions/predicates.asciidoc

@@ -0,0 +1,23 @@
+[discrete]
+[[esql-predicates]]
+=== `IS NULL` and `IS NOT NULL` predicates
+
+For NULL comparison, use the `IS NULL` and `IS NOT NULL` predicates:
+
+[source.merge.styled,esql]
+----
+include::{esql-specs}/null.csv-spec[tag=is-null]
+----
+[%header.monospaced.styled,format=dsv,separator=|]
+|===
+include::{esql-specs}/null.csv-spec[tag=is-null-result]
+|===
+
+[source.merge.styled,esql]
+----
+include::{esql-specs}/null.csv-spec[tag=is-not-null]
+----
+[%header.monospaced.styled,format=dsv,separator=|]
+|===
+include::{esql-specs}/null.csv-spec[tag=is-not-null-result]
+|===

docs/reference/esql/functions/replace.asciidoc

@@ -1,3 +1,4 @@
+[discrete]
 [[esql-replace]]
 === `REPLACE`
 The function substitutes in the string (1st argument) any match of the regular expression (2nd argument) with the replacement string (3rd argument).

docs/reference/esql/functions/right.asciidoc

@@ -1,3 +1,4 @@
+[discrete]
 [[esql-right]]
 === `RIGHT`
 [.text-center]

docs/reference/esql/functions/rlike.asciidoc

@@ -0,0 +1,15 @@
+[discete]
+[[esql-rlike-operator]]
+==== `RLIKE`
+
+Use `RLIKE` to filter data based on string patterns using using
+<<regexp-syntax,regular expressions>>. `RLIKE` usually acts on a field placed on
+the left-hand side of the operator, but it can also act on a constant (literal)
+expression. The right-hand side of the operator represents the pattern.
+
+[source,esql]
+----
+FROM employees
+| WHERE first_name RLIKE ".leja.*"
+| KEEP first_name, last_name
+----

docs/reference/esql/functions/round.asciidoc

@@ -1,3 +1,4 @@
+[discrete]
 [[esql-round]]
 === `ROUND`
 Rounds a number to the closest number with the specified number of digits.

docs/reference/esql/functions/rtrim.asciidoc

@@ -1,3 +1,4 @@
+[discrete]
 [[esql-rtrim]]
 === `RTRIM`
 Removes trailing whitespaces from strings.

docs/reference/esql/functions/sin.asciidoc

@@ -1,3 +1,4 @@
+[discrete]
 [[esql-sin]]
 === `SIN`
 [.text-center]

docs/reference/esql/functions/sinh.asciidoc

@@ -1,3 +1,4 @@
+[discrete]
 [[esql-sinh]]
 === `SINH`
 [.text-center]

docs/reference/esql/functions/split.asciidoc

@@ -1,3 +1,4 @@
+[discrete]
 [[esql-split]]
 === `SPLIT`
 Split a single valued string into multiple strings. For example:

docs/reference/esql/functions/sqrt.asciidoc

@@ -1,3 +1,4 @@
+[discrete]
 [[esql-sqrt]]
 === `SQRT`
 [.text-center]

docs/reference/esql/functions/starts_with.asciidoc

@@ -1,3 +1,4 @@
+[discrete]
 [[esql-starts_with]]
 === `STARTS_WITH`
 [.text-center]

docs/reference/esql/functions/string-functions.asciidoc

@@ -0,0 +1,32 @@
+[[esql-string-functions]]
+=== {esql} string functions
+
+++++
+<titleabbrev>String functions</titleabbrev>
+++++
+
+{esql} supports these string functions:
+
+// tag::list[]
+* <<esql-concat>>
+* <<esql-left>>
+* <<esql-length>>
+* <<esql-ltrim>>
+* <<esql-replace>>
+* <<esql-right>>
+* <<esql-rtrim>>
+* <<esql-split>>
+* <<esql-substring>>
+* <<esql-trim>>
+// end::list[]
+
+include::concat.asciidoc[]
+include::left.asciidoc[]
+include::length.asciidoc[]
+include::ltrim.asciidoc[]
+include::replace.asciidoc[]
+include::right.asciidoc[]
+include::rtrim.asciidoc[]
+include::split.asciidoc[]
+include::substring.asciidoc[]
+include::trim.asciidoc[]

docs/reference/esql/functions/substring.asciidoc

@@ -1,3 +1,4 @@
+[discrete]
 [[esql-substring]]
 === `SUBSTRING`
 Returns a substring of a string, specified by a start position and an optional

docs/reference/esql/aggregation-functions/sum.asciidoc → docs/reference/esql/functions/sum.asciidoc

@@ -1,3 +1,4 @@
+[discrete]
 [[esql-agg-sum]]
 === `SUM`
 The sum of a numeric field.

docs/reference/esql/functions/tan.asciidoc

@@ -1,3 +1,4 @@
+[discrete]
 [[esql-tan]]
 === `TAN`
 [.text-center]

docs/reference/esql/functions/tanh.asciidoc

@@ -1,3 +1,4 @@
+[discrete]
 [[esql-tanh]]
 === `TANH`
 [.text-center]

docs/reference/esql/functions/tau.asciidoc

@@ -1,3 +1,4 @@
+[discrete]
 [[esql-tau]]
 === `TAU`
 [.text-center]

docs/reference/esql/functions/to_boolean.asciidoc

@@ -1,3 +1,4 @@
+[discrete]
 [[esql-to_boolean]]
 === `TO_BOOLEAN`
 Converts an input value to a boolean value.

docs/reference/esql/functions/to_datetime.asciidoc

@@ -1,3 +1,4 @@
+[discrete]
 [[esql-to_datetime]]
 === `TO_DATETIME`
 Converts an input value to a date value.

docs/reference/esql/functions/to_degrees.asciidoc

@@ -1,3 +1,4 @@
+[discrete]
 [[esql-to_degrees]]
 === `TO_DEGREES`
 Converts a number in https://en.wikipedia.org/wiki/Radian[radians]

docs/reference/esql/functions/to_double.asciidoc

@@ -1,3 +1,4 @@
+[discrete]
 [[esql-to_double]]
 === `TO_DOUBLE`
 Converts an input value to a double value.

docs/reference/esql/functions/to_integer.asciidoc

@@ -1,3 +1,4 @@
+[discrete]
 [[esql-to_integer]]
 === `TO_INTEGER`
 Converts an input value to an integer  value.

docs/reference/esql/functions/to_ip.asciidoc

@@ -1,3 +1,4 @@
+[discrete]
 [[esql-to_ip]]
 === `TO_IP`
 Converts an input string to an IP value.

docs/reference/esql/functions/to_long.asciidoc

@@ -1,3 +1,4 @@
+[discrete]
 [[esql-to_long]]
 === `TO_LONG`
 Converts an input value to a long value.

docs/reference/esql/functions/to_radians.asciidoc

@@ -1,3 +1,4 @@
+[discrete]
 [[esql-to_radians]]
 === `TO_RADIANS`
 Converts a number in https://en.wikipedia.org/wiki/Degree_(angle)[degrees] to

docs/reference/esql/functions/to_string.asciidoc

@@ -1,3 +1,4 @@
+[discrete]
 [[esql-to_string]]
 === `TO_STRING`
 [.text-center]

docs/reference/esql/functions/to_unsigned_long.asciidoc

@@ -1,3 +1,4 @@
+[discrete]
 [[esql-to_unsigned_long]]
 === `TO_UNSIGNED_LONG`
 Converts an input value to an unsigned long value.

docs/reference/esql/functions/to_version.asciidoc

@@ -1,3 +1,4 @@
+[discrete]
 [[esql-to_version]]
 === `TO_VERSION`
 [.text-center]

docs/reference/esql/functions/trim.asciidoc

@@ -1,3 +1,4 @@
+[discrete]
 [[esql-trim]]
 === `TRIM`
 [.text-center]

docs/reference/esql/functions/type-conversion-functions.asciidoc

@@ -0,0 +1,34 @@
+[[esql-type-conversion-functions]]
+=== {esql} type conversion functions
+
+++++
+<titleabbrev>Type conversion functions</titleabbrev>
+++++
+
+{esql} supports these type conversion functions:
+
+// tag::list[]
+* <<esql-to_boolean>>
+* <<esql-to_datetime>>
+* <<esql-to_degrees>>
+* <<esql-to_double>>
+* <<esql-to_integer>>
+* <<esql-to_ip>>
+* <<esql-to_long>>
+* <<esql-to_radians>>
+* <<esql-to_string>>
+* <<esql-to_unsigned_long>>
+* <<esql-to_version>>
+// end::list[]
+
+include::to_boolean.asciidoc[]
+include::to_datetime.asciidoc[]
+include::to_degrees.asciidoc[]
+include::to_double.asciidoc[]
+include::to_integer.asciidoc[]
+include::to_ip.asciidoc[]
+include::to_long.asciidoc[]
+include::to_radians.asciidoc[]
+include::to_string.asciidoc[]
+include::to_unsigned_long.asciidoc[]
+include::to_version.asciidoc[]

docs/reference/esql/index.asciidoc

@@ -38,8 +38,9 @@ The result of a query is the table produced by the final processing command.
 [discrete]
 ==== The {esql} API
 
-Use the `_query` endpoint to run an {esql} query:
+Use the <<esql-rest,`_query` endpoint>> to run an {esql} query:
 
+// tag::esql-query-api-example[]
 [source,console]
 ----
 POST /_query
@@ -54,6 +55,7 @@ POST /_query
 }
 ----
 // TEST[setup:library]
+// end::esql-query-api-example[]
 
 The results come back in rows:
 
@@ -74,28 +76,14 @@ The results come back in rows:
 }
 ----
 
-By default, results are returned as JSON. To return results formatted as text,
-CSV, or TSV, use the `format` parameter:
+By default, results are returned as JSON. You can return data in other
+<<esql-rest-format,response formats>> by specifying the `format` parameter in
+the URL or by setting the `Accept` or `Content-Type` HTTP header.
 
-[source,console]
-----
-POST /_query?format=txt
-{
-  "query": """
-    FROM library
-    | EVAL year = DATE_TRUNC(1 YEARS, release_date)
-    | STATS MAX(page_count) BY year
-    | SORT year
-    | LIMIT 5
-  """
-}
-----
-// TEST[setup:library]
-
-The above query's `LIMIT` command limits results to 5 rows.
-
-If not specified, `LIMIT` defaults to `500`. A single query will not return
-more than 10,000 rows, regardless of the `LIMIT` value.
+By default, an {esql} query returns up to 500 rows. You can change this using
+the <<esql-limit,`LIMIT` command>>. The previous query's `LIMIT` command limits
+results to 5 rows. The maximum number of returned rows is 10,000 rows,
+regardless of the `LIMIT` value.
 
 [discrete]
 ==== {kib}
@@ -106,46 +94,23 @@ select *Try {esql}* to get started.
 NOTE: {esql} queries in Discover and Lens are subject to the time range selected
 with the time filter.
 
-[discrete]
-[[esql-limitations]]
-=== Limitations
-
-* {esql} currently supports the following <<mapping-types,field types>>:
-
-** `alias`
-** `boolean`
-** `date`
-** `double` (`float`, `half_float`, `scaled_float` are represented as `double`)
-** `ip`
-** `keyword` family including `keyword`, `constant_keyword`, and `wildcard`
-** `int` (`short` and `byte` are represented as `int`)
-** `long`
-** `null`
-** `text`
-** `unsigned_long`
-** `version`
-
-* A single query will not return more than 10,000 rows, regardless of the
-`LIMIT` command's value.
 --
 
 include::esql-get-started.asciidoc[]
 
-include::esql-syntax.asciidoc[]
-
-include::esql-source-commands.asciidoc[]
+include::esql-language.asciidoc[]
 
-include::esql-processing-commands.asciidoc[]
+include::esql-commands.asciidoc[]
 
-include::esql-functions.asciidoc[]
+include::esql-functions-operators.asciidoc[]
 
-include::aggregation-functions.asciidoc[]
+include::esql-rest.asciidoc[]
 
-include::multivalued-fields.asciidoc[]
-
-include::metadata-fields.asciidoc[]
+include::esql-kibana.asciidoc[]
 
 include::task-management.asciidoc[]
 
+include::esql-limitations.asciidoc[]
+
 :esql-tests!:
 :esql-specs!: