ESQL: Add version to docs

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]

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]
@@ -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"]

docs/reference/esql/esql-rest.asciidoc

@@ -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]
@@ -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]

docs/reference/esql/esql-using.asciidoc

@@ -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[]

docs/reference/esql/esql-version.asciidoc

@@ -0,0 +1,49 @@
+[[esql-version]]
+=== {esql} language versions
+
+++++
+<titleabbrev>Language versions</titleabbrev>
+++++
+
+[discrete]
+[[esql-versions-released]]
+==== Released versions
+
+* Version `2024.04.01`
+
+[discrete]
+[[esql-versions-explanation]]
+=== How versions work
+
+{esql} language versions are independent of {es} versions.
+Versioning the language ensures that your queries will always
+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 will remain valid, even if a future
+version of {esql} introduces syntax changes or changes how the used
+commands or functions work.
+
+[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]
+
+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.

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]