Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

ESQL: Add version to docs #107225

Merged
merged 6 commits into from
Apr 15, 2024
Merged

ESQL: Add version to docs #107225

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
dcbb6d7
Add draft for esql version doc
alex-spies Apr 8, 2024
195bc10
Add example
alex-spies Apr 8, 2024
aa2794e
Add version to examples in docs
alex-spies Apr 9, 2024
57ea977
Apply suggestions from code review
nik9000 Apr 15, 2024
ce88f3d
Fewer rockets
nik9000 Apr 15, 2024
40cf581
Move
nik9000 Apr 15, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion docs/reference/esql/esql-async-query-api.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,8 @@ POST /_query/async
| SORT year
| LIMIT 5
""",
"wait_for_completion_timeout": "2s"
"wait_for_completion_timeout": "2s",
"version": "2024.04.01.🚀"
}
----
// TEST[setup:library]
Expand Down
9 changes: 7 additions & 2 deletions docs/reference/esql/esql-query-api.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,8 @@ POST /_query
| STATS MAX(page_count) BY year
| SORT year
| LIMIT 5
"""
""",
"version": "2024.04.01.🚀"
}
----
// TEST[setup:library]
Expand Down Expand Up @@ -76,7 +77,11 @@ For syntax, refer to <<esql-locale-param>>.
<<esql-rest-params>>.

`query`::
(Required, object) {esql} query to run. For syntax, refer to <<esql-syntax>>.
(Required, string) {esql} query to run. For syntax, refer to <<esql-syntax>>.

`version`::
(Required, string) {esql} language version. Can be sent in short or long form, e.g.
`2024.04.01` or `2024.04.01.🚀`. See <<esql-version>> for details.

[discrete]
[role="child_attributes"]
Expand Down
24 changes: 16 additions & 8 deletions docs/reference/esql/esql-rest.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,8 @@ The <<esql-query-api,{esql} query API>> accepts an {esql} query string in the
----
POST /_query?format=txt
{
"query": "FROM library | KEEP author, name, page_count, release_date | SORT page_count DESC | LIMIT 5"
"query": "FROM library | KEEP author, name, page_count, release_date | SORT page_count DESC | LIMIT 5",
"version": "2024.04.01.🚀"
}
----
// TEST[setup:library]
Expand Down Expand Up @@ -55,7 +56,8 @@ POST /_query?format=txt
| KEEP author, name, page_count, release_date
| SORT page_count DESC
| LIMIT 5
"""
""",
"version": "2024.04.01.🚀"
}
----
// TEST[setup:library]
Expand Down Expand Up @@ -143,7 +145,8 @@ POST /_query?format=txt
"lte": 200
}
}
}
},
"version": "2024.04.01.🚀"
}
----
// TEST[setup:library]
Expand Down Expand Up @@ -179,7 +182,8 @@ POST /_query?format=json
| SORT page_count DESC
| LIMIT 5
""",
"columnar": true
"columnar": true,
"version": "2024.04.01.🚀"
}
----
// TEST[setup:library]
Expand Down Expand Up @@ -226,7 +230,8 @@ POST /_query
| EVAL birth_date = date_parse(birth_date_string)
| EVAL month_of_birth = DATE_FORMAT("MMMM",birth_date)
| LIMIT 5
"""
""",
"version": "2024.04.01.🚀"
}
----
// TEST[setup:library]
Expand All @@ -249,7 +254,8 @@ POST /_query
| STATS count = COUNT(*) by year
| WHERE count > 0
| LIMIT 5
"""
""",
"version": "2024.04.01.🚀"
}
----
// TEST[setup:library]
Expand All @@ -270,7 +276,8 @@ POST /_query
| WHERE count > ?
| LIMIT 5
""",
"params": [300, "Frank Herbert", 0]
"params": [300, "Frank Herbert", 0],
"version": "2024.04.01.🚀"
}
----
// TEST[setup:library]
Expand Down Expand Up @@ -304,7 +311,8 @@ POST /_query/async
| SORT year
| LIMIT 5
""",
"wait_for_completion_timeout": "2s"
"wait_for_completion_timeout": "2s",
"version": "2024.04.01.🚀"
}
----
// TEST[setup:library]
Expand Down
4 changes: 4 additions & 0 deletions docs/reference/esql/esql-using.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,8 +18,12 @@ Using {esql} to query across multiple clusters.
<<esql-task-management>>::
Using the <<tasks,task management API>> to list and cancel {esql} queries.

<<esql-version>>::
Information about {esql} language versions.

include::esql-rest.asciidoc[]
include::esql-kibana.asciidoc[]
include::esql-security-solution.asciidoc[]
include::esql-across-clusters.asciidoc[]
include::task-management.asciidoc[]
include::esql-version.asciidoc[]
48 changes: 48 additions & 0 deletions docs/reference/esql/esql-version.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
[[esql-version]]
=== {esql} language versions

++++
<titleabbrev>Language versions</titleabbrev>
++++

[discrete]
[[esql-versions-released]]
==== Released versions

{esql} is released at version `2024.04.01.🚀`.
nik9000 marked this conversation as resolved.
Show resolved Hide resolved
This is the only available version for now.
nik9000 marked this conversation as resolved.
Show resolved Hide resolved

[discrete]
[[esql-versions-explanation]]
=== How versions work

{esql} versions are separate from Elasticsearch versions.
nik9000 marked this conversation as resolved.
Show resolved Hide resolved
Their goal is to make sure that queries that were once written
remain valid even as Elasticsearch and {esql} evolve.
nik9000 marked this conversation as resolved.
Show resolved Hide resolved

For instance, the following query
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It doesn't read well to have a code sample mid-sentence, so I'd recommend moving lines 41 + 42 up here.


[source,console]
----
POST /_query?format=txt
{
"version": "2024.04.01.🚀",
"query": """
FROM library
| EVAL release_month = DATE_TRUNC(1 month, release_date)
| KEEP release_month
| SORT release_month ASC
| LIMIT 3
"""
}
----
// TEST[setup:library]

will remain valid, even if a future version of {esql} introduces
syntax changes or changes how the used commands or functions work.

A released {esql} version will not receive breaking changes and
will remain supported until it is deprecated.
Already released {esql} versions will still profit from new features,
bug fixes and performance improvements as long as those do not
require breaking changes.
nik9000 marked this conversation as resolved.
Show resolved Hide resolved
18 changes: 12 additions & 6 deletions docs/reference/esql/multivalued-fields.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,8 @@ POST /mv/_bulk?refresh

POST /_query
{
"query": "FROM mv | LIMIT 2"
"query": "FROM mv | LIMIT 2",
"version": "2024.04.01.🚀"
}
----

Expand Down Expand Up @@ -65,7 +66,8 @@ POST /mv/_bulk?refresh

POST /_query
{
"query": "FROM mv | LIMIT 2"
"query": "FROM mv | LIMIT 2",
"version": "2024.04.01.🚀"
}
----

Expand Down Expand Up @@ -106,7 +108,8 @@ POST /mv/_bulk?refresh

POST /_query
{
"query": "FROM mv | LIMIT 2"
"query": "FROM mv | LIMIT 2",
"version": "2024.04.01.🚀"
}
----

Expand Down Expand Up @@ -148,7 +151,8 @@ POST /mv/_bulk?refresh

POST /_query
{
"query": "FROM mv | EVAL b=TO_STRING(b) | LIMIT 2"
"query": "FROM mv | EVAL b=TO_STRING(b) | LIMIT 2",
"version": "2024.04.01.🚀"
}
----

Expand Down Expand Up @@ -186,7 +190,8 @@ POST /mv/_bulk?refresh
----
POST /_query
{
"query": "FROM mv | EVAL b + 2, a + b | LIMIT 4"
"query": "FROM mv | EVAL b + 2, a + b | LIMIT 4",
"version": "2024.04.01.🚀"
}
----
// TEST[continued]
Expand Down Expand Up @@ -225,7 +230,8 @@ Work around this limitation by converting the field to single value with one of:
----
POST /_query
{
"query": "FROM mv | EVAL b=MV_MIN(b) | EVAL b + 2, a + b | LIMIT 4"
"query": "FROM mv | EVAL b=MV_MIN(b) | EVAL b + 2, a + b | LIMIT 4",
"version": "2024.04.01.🚀"
}
----
// TEST[continued]
Expand Down