From dcbb6d7388f44710291580547a095249496ccb02 Mon Sep 17 00:00:00 2001 From: Alexander Spies Date: Mon, 8 Apr 2024 16:53:40 +0200 Subject: [PATCH 1/6] Add draft for esql version doc --- docs/reference/esql/esql-query-api.asciidoc | 6 ++++- docs/reference/esql/esql-using.asciidoc | 4 +++ docs/reference/esql/esql-version.asciidoc | 29 +++++++++++++++++++++ 3 files changed, 38 insertions(+), 1 deletion(-) create mode 100644 docs/reference/esql/esql-version.asciidoc diff --git a/docs/reference/esql/esql-query-api.asciidoc b/docs/reference/esql/esql-query-api.asciidoc index d7fa25a5a8d4f..a6829af09476e 100644 --- a/docs/reference/esql/esql-query-api.asciidoc +++ b/docs/reference/esql/esql-query-api.asciidoc @@ -76,7 +76,11 @@ For syntax, refer to <>. <>. `query`:: -(Required, object) {esql} query to run. For syntax, refer to <>. +(Required, string) {esql} query to run. For syntax, refer to <>. + +`version`:: +(Required, string) {esql} language version. Can be sent in short or long form, e.g. +`2024.04.01` or `2024.04.01.🚀`. See <> for details. [discrete] [role="child_attributes"] diff --git a/docs/reference/esql/esql-using.asciidoc b/docs/reference/esql/esql-using.asciidoc index 3e045163069ec..d45a7f1743d23 100644 --- a/docs/reference/esql/esql-using.asciidoc +++ b/docs/reference/esql/esql-using.asciidoc @@ -18,8 +18,12 @@ Using {esql} to query across multiple clusters. <>:: Using the <> to list and cancel {esql} queries. +<>:: +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[] diff --git a/docs/reference/esql/esql-version.asciidoc b/docs/reference/esql/esql-version.asciidoc new file mode 100644 index 0000000000000..ad9b8a523da75 --- /dev/null +++ b/docs/reference/esql/esql-version.asciidoc @@ -0,0 +1,29 @@ +[[esql-version]] +=== {esql} language versions + +++++ +Language versions +++++ + +[discrete] +[[esql-versions-released]] +==== Released versions + +{esql} is released at version `2024.04.01.🚀`. +This is the only available version for now. + +[discrete] +[[esql-versions-explanation]] +=== How versions work + +{esql} versions are separate from Elasticsearch versions. +Their goal is to make sure that queries that were once written +remain valid even as Elasticsearch and {esql} evolve. + +// TODO: example at 2024.04.01 + +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. From 195bc101754e29fa414d68b7c2ccb2a961a5be9d Mon Sep 17 00:00:00 2001 From: Alexander Spies Date: Mon, 8 Apr 2024 18:40:21 +0200 Subject: [PATCH 2/6] Add example --- docs/reference/esql/esql-version.asciidoc | 21 ++++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) diff --git a/docs/reference/esql/esql-version.asciidoc b/docs/reference/esql/esql-version.asciidoc index ad9b8a523da75..7a1896a3501ab 100644 --- a/docs/reference/esql/esql-version.asciidoc +++ b/docs/reference/esql/esql-version.asciidoc @@ -20,7 +20,26 @@ This is the only available version for now. Their goal is to make sure that queries that were once written remain valid even as Elasticsearch and {esql} evolve. -// TODO: example at 2024.04.01 +For instance, the following query + +[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. From aa2794e704a38f1b2e21810353230b119e229bb2 Mon Sep 17 00:00:00 2001 From: Alexander Spies Date: Tue, 9 Apr 2024 11:37:40 +0200 Subject: [PATCH 3/6] Add version to examples in docs --- .../esql/esql-async-query-api.asciidoc | 3 ++- docs/reference/esql/esql-query-api.asciidoc | 3 ++- docs/reference/esql/esql-rest.asciidoc | 24 ++++++++++++------- .../esql/multivalued-fields.asciidoc | 18 +++++++++----- 4 files changed, 32 insertions(+), 16 deletions(-) diff --git a/docs/reference/esql/esql-async-query-api.asciidoc b/docs/reference/esql/esql-async-query-api.asciidoc index 6cd23fc524f96..2f9defd888a6c 100644 --- a/docs/reference/esql/esql-async-query-api.asciidoc +++ b/docs/reference/esql/esql-async-query-api.asciidoc @@ -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] diff --git a/docs/reference/esql/esql-query-api.asciidoc b/docs/reference/esql/esql-query-api.asciidoc index a6829af09476e..d4470be406ecf 100644 --- a/docs/reference/esql/esql-query-api.asciidoc +++ b/docs/reference/esql/esql-query-api.asciidoc @@ -16,7 +16,8 @@ POST /_query | STATS MAX(page_count) BY year | SORT year | LIMIT 5 - """ + """, + "version": "2024.04.01.🚀" } ---- // TEST[setup:library] diff --git a/docs/reference/esql/esql-rest.asciidoc b/docs/reference/esql/esql-rest.asciidoc index de2b6dedd8776..d14fca61fd2a7 100644 --- a/docs/reference/esql/esql-rest.asciidoc +++ b/docs/reference/esql/esql-rest.asciidoc @@ -16,7 +16,8 @@ The <> 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] @@ -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] @@ -143,7 +145,8 @@ POST /_query?format=txt "lte": 200 } } - } + }, + "version": "2024.04.01.🚀" } ---- // TEST[setup:library] @@ -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] @@ -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] @@ -249,7 +254,8 @@ POST /_query | STATS count = COUNT(*) by year | WHERE count > 0 | LIMIT 5 - """ + """, + "version": "2024.04.01.🚀" } ---- // TEST[setup:library] @@ -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] @@ -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] diff --git a/docs/reference/esql/multivalued-fields.asciidoc b/docs/reference/esql/multivalued-fields.asciidoc index 871a741d5ee24..2a05c8eb8a43e 100644 --- a/docs/reference/esql/multivalued-fields.asciidoc +++ b/docs/reference/esql/multivalued-fields.asciidoc @@ -17,7 +17,8 @@ POST /mv/_bulk?refresh POST /_query { - "query": "FROM mv | LIMIT 2" + "query": "FROM mv | LIMIT 2", + "version": "2024.04.01.🚀" } ---- @@ -65,7 +66,8 @@ POST /mv/_bulk?refresh POST /_query { - "query": "FROM mv | LIMIT 2" + "query": "FROM mv | LIMIT 2", + "version": "2024.04.01.🚀" } ---- @@ -106,7 +108,8 @@ POST /mv/_bulk?refresh POST /_query { - "query": "FROM mv | LIMIT 2" + "query": "FROM mv | LIMIT 2", + "version": "2024.04.01.🚀" } ---- @@ -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.🚀" } ---- @@ -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] @@ -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] From 57ea977a2187aa232e9810a73c6b9acc46d4e3e6 Mon Sep 17 00:00:00 2001 From: Nik Everett Date: Mon, 15 Apr 2024 10:20:44 -0400 Subject: [PATCH 4/6] Apply suggestions from code review Co-authored-by: Liam Thompson <32779855+leemthompo@users.noreply.github.com> --- docs/reference/esql/esql-version.asciidoc | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/docs/reference/esql/esql-version.asciidoc b/docs/reference/esql/esql-version.asciidoc index 7a1896a3501ab..7763b3737b23a 100644 --- a/docs/reference/esql/esql-version.asciidoc +++ b/docs/reference/esql/esql-version.asciidoc @@ -9,16 +9,15 @@ [[esql-versions-released]] ==== Released versions -{esql} is released at version `2024.04.01.🚀`. -This is the only available version for now. +* Version `2024.04.01.🚀` [discrete] [[esql-versions-explanation]] === How versions work -{esql} versions are separate from Elasticsearch versions. -Their goal is to make sure that queries that were once written -remain valid even as Elasticsearch and {esql} evolve. +{esql} language versions are independent of {es} versions. +Versioning the language ensures that your queries will always +remain valid for a version, independent of new {es} and {esql} releases. For instance, the following query @@ -41,8 +40,8 @@ POST /_query?format=txt 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. +We won't make breaking changes to released {esql} versions and +versions will remain supported until they are deprecated. +New features, bug fixes, and performance improvements +will be continue to be added to released {esql} versions, +provided they do not involve breaking changes. From ce88f3df47a7ed3c6176e3da1e33f838c0bcbc3c Mon Sep 17 00:00:00 2001 From: Nik Everett Date: Mon, 15 Apr 2024 10:23:29 -0400 Subject: [PATCH 5/6] Fewer rockets --- .../reference/esql/esql-async-query-api.asciidoc | 2 +- docs/reference/esql/esql-query-api.asciidoc | 2 +- docs/reference/esql/esql-rest.asciidoc | 16 ++++++++-------- docs/reference/esql/esql-version.asciidoc | 8 ++++---- docs/reference/esql/multivalued-fields.asciidoc | 12 ++++++------ 5 files changed, 20 insertions(+), 20 deletions(-) diff --git a/docs/reference/esql/esql-async-query-api.asciidoc b/docs/reference/esql/esql-async-query-api.asciidoc index 2f9defd888a6c..82e7bb3cea9a5 100644 --- a/docs/reference/esql/esql-async-query-api.asciidoc +++ b/docs/reference/esql/esql-async-query-api.asciidoc @@ -25,7 +25,7 @@ POST /_query/async | LIMIT 5 """, "wait_for_completion_timeout": "2s", - "version": "2024.04.01.🚀" + "version": "2024.04.01" } ---- // TEST[setup:library] diff --git a/docs/reference/esql/esql-query-api.asciidoc b/docs/reference/esql/esql-query-api.asciidoc index d4470be406ecf..e5e0e9fda12ec 100644 --- a/docs/reference/esql/esql-query-api.asciidoc +++ b/docs/reference/esql/esql-query-api.asciidoc @@ -17,7 +17,7 @@ POST /_query | SORT year | LIMIT 5 """, - "version": "2024.04.01.🚀" + "version": "2024.04.01" } ---- // TEST[setup:library] diff --git a/docs/reference/esql/esql-rest.asciidoc b/docs/reference/esql/esql-rest.asciidoc index d14fca61fd2a7..106dba0e85dfe 100644 --- a/docs/reference/esql/esql-rest.asciidoc +++ b/docs/reference/esql/esql-rest.asciidoc @@ -17,7 +17,7 @@ The <> 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", - "version": "2024.04.01.🚀" + "version": "2024.04.01" } ---- // TEST[setup:library] @@ -57,7 +57,7 @@ POST /_query?format=txt | SORT page_count DESC | LIMIT 5 """, - "version": "2024.04.01.🚀" + "version": "2024.04.01" } ---- // TEST[setup:library] @@ -146,7 +146,7 @@ POST /_query?format=txt } } }, - "version": "2024.04.01.🚀" + "version": "2024.04.01" } ---- // TEST[setup:library] @@ -183,7 +183,7 @@ POST /_query?format=json | LIMIT 5 """, "columnar": true, - "version": "2024.04.01.🚀" + "version": "2024.04.01" } ---- // TEST[setup:library] @@ -231,7 +231,7 @@ POST /_query | EVAL month_of_birth = DATE_FORMAT("MMMM",birth_date) | LIMIT 5 """, - "version": "2024.04.01.🚀" + "version": "2024.04.01" } ---- // TEST[setup:library] @@ -255,7 +255,7 @@ POST /_query | WHERE count > 0 | LIMIT 5 """, - "version": "2024.04.01.🚀" + "version": "2024.04.01" } ---- // TEST[setup:library] @@ -277,7 +277,7 @@ POST /_query | LIMIT 5 """, "params": [300, "Frank Herbert", 0], - "version": "2024.04.01.🚀" + "version": "2024.04.01" } ---- // TEST[setup:library] @@ -312,7 +312,7 @@ POST /_query/async | LIMIT 5 """, "wait_for_completion_timeout": "2s", - "version": "2024.04.01.🚀" + "version": "2024.04.01" } ---- // TEST[setup:library] diff --git a/docs/reference/esql/esql-version.asciidoc b/docs/reference/esql/esql-version.asciidoc index 7763b3737b23a..aa00aa5dcf018 100644 --- a/docs/reference/esql/esql-version.asciidoc +++ b/docs/reference/esql/esql-version.asciidoc @@ -9,7 +9,7 @@ [[esql-versions-released]] ==== Released versions -* Version `2024.04.01.🚀` +* Version `2024.04.01` [discrete] [[esql-versions-explanation]] @@ -25,7 +25,7 @@ For instance, the following query ---- POST /_query?format=txt { - "version": "2024.04.01.🚀", + "version": "2024.04.01", "query": """ FROM library | EVAL release_month = DATE_TRUNC(1 month, release_date) @@ -42,6 +42,6 @@ syntax changes or changes how the used commands or functions work. We won't make breaking changes to released {esql} versions and versions will remain supported until they are deprecated. -New features, bug fixes, and performance improvements -will be continue to be added to released {esql} versions, +New features, bug fixes, and performance improvements +will be continue to be added to released {esql} versions, provided they do not involve breaking changes. diff --git a/docs/reference/esql/multivalued-fields.asciidoc b/docs/reference/esql/multivalued-fields.asciidoc index 2a05c8eb8a43e..35f46db25425b 100644 --- a/docs/reference/esql/multivalued-fields.asciidoc +++ b/docs/reference/esql/multivalued-fields.asciidoc @@ -18,7 +18,7 @@ POST /mv/_bulk?refresh POST /_query { "query": "FROM mv | LIMIT 2", - "version": "2024.04.01.🚀" + "version": "2024.04.01" } ---- @@ -67,7 +67,7 @@ POST /mv/_bulk?refresh POST /_query { "query": "FROM mv | LIMIT 2", - "version": "2024.04.01.🚀" + "version": "2024.04.01" } ---- @@ -109,7 +109,7 @@ POST /mv/_bulk?refresh POST /_query { "query": "FROM mv | LIMIT 2", - "version": "2024.04.01.🚀" + "version": "2024.04.01" } ---- @@ -152,7 +152,7 @@ POST /mv/_bulk?refresh POST /_query { "query": "FROM mv | EVAL b=TO_STRING(b) | LIMIT 2", - "version": "2024.04.01.🚀" + "version": "2024.04.01" } ---- @@ -191,7 +191,7 @@ POST /mv/_bulk?refresh POST /_query { "query": "FROM mv | EVAL b + 2, a + b | LIMIT 4", - "version": "2024.04.01.🚀" + "version": "2024.04.01" } ---- // TEST[continued] @@ -231,7 +231,7 @@ 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", - "version": "2024.04.01.🚀" + "version": "2024.04.01" } ---- // TEST[continued] From 40cf5812a95b3e2c185cdf500d475d151219fb7e Mon Sep 17 00:00:00 2001 From: Nik Everett Date: Mon, 15 Apr 2024 10:27:02 -0400 Subject: [PATCH 6/6] Move --- docs/reference/esql/esql-version.asciidoc | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/reference/esql/esql-version.asciidoc b/docs/reference/esql/esql-version.asciidoc index aa00aa5dcf018..16bf1f66e3166 100644 --- a/docs/reference/esql/esql-version.asciidoc +++ b/docs/reference/esql/esql-version.asciidoc @@ -17,9 +17,14 @@ {esql} language versions are independent of {es} versions. Versioning the language ensures that your queries will always -remain valid for a version, independent of new {es} and {esql} releases. +remain valid, independent of new {es} and {esql} releases. And it lets us +evolve ESQL as we learn more from people using it. We don't plan to make +huge changes to it, but we know we've made mistakes and we don't want those +to live forever. -For instance, the following query +For instance, the following query will remain valid, even if a future +version of {esql} introduces syntax changes or changes how the used +commands or functions work. [source,console] ---- @@ -37,9 +42,6 @@ POST /_query?format=txt ---- // 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. - We won't make breaking changes to released {esql} versions and versions will remain supported until they are deprecated. New features, bug fixes, and performance improvements