Skip to content

Commit

Permalink
Restructure ES|QL docs (elastic#100806)
Browse files Browse the repository at this point in the history
* 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>
  • Loading branch information
abdonpijpelink and elasticmachine committed Oct 17, 2023
1 parent 7a6cbd4 commit 45b2666
Show file tree
Hide file tree
Showing 122 changed files with 1,112 additions and 231 deletions.
30 changes: 0 additions & 30 deletions docs/reference/esql/aggregation-functions.asciidoc

This file was deleted.

17 changes: 17 additions & 0 deletions docs/reference/esql/esql-commands.asciidoc
Original file line number Diff line number Diff line change
@@ -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[]
42 changes: 42 additions & 0 deletions docs/reference/esql/esql-functions-operators.asciidoc
Original file line number Diff line number Diff line change
@@ -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[]
8 changes: 8 additions & 0 deletions docs/reference/esql/esql-get-started.asciidoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
[[esql-getting-started]]
== Getting started with {esql}

++++
<titleabbrev>Getting started</titleabbrev>
++++

coming::[8.11]
8 changes: 8 additions & 0 deletions docs/reference/esql/esql-kibana.asciidoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
[[esql-kibana]]
== Using {esql} in {kib}

++++
<titleabbrev>Kibana</titleabbrev>
++++

coming::[8.11]
16 changes: 16 additions & 0 deletions docs/reference/esql/esql-language.asciidoc
Original file line number Diff line number Diff line change
@@ -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[]
32 changes: 32 additions & 0 deletions docs/reference/esql/esql-limitations.asciidoc
Original file line number Diff line number Diff line change
@@ -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.
39 changes: 0 additions & 39 deletions docs/reference/esql/esql-processing-commands.asciidoc

This file was deleted.

84 changes: 84 additions & 0 deletions docs/reference/esql/esql-query-api.asciidoc
Original file line number Diff line number Diff line change
@@ -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.
Loading

0 comments on commit 45b2666

Please sign in to comment.