Additional support for docs for ES|QL operators and version-specific differentiation (elastic#125251)

This PR was originally focused on improving support for Kibana docs, in particular the missing operator docs, but it has expanded to cover a bunch of related things:

* Primarily the main work was to improve operators support. ESQL generated docs cover all functions and most operators for which their is a clear operator class and test class. However, some are built-in behaviour and need additional support. This PR adds more generated content for those operators.
* Various specific operators requested by Kibana: Cast & null-predicates, and in particular the addition of examples
* Two functions without examples: mv_append and to_date_nanos
* Many small visual document cleanups (spelling, grammar, capitalization, etc.)
* Initial support for `applies_to` for multi-version differentiation.

This last point requires more work, as it is not yet agreed on just how we want this to look. We'll probably need to do refinements in followup PR. Consider the version in this PR as a first step into how this could look.

Author: craigtaverner

docs/reference/query-languages/esql/_snippets/operators/examples/cast.md

@@ -1,3 +1,5 @@
+% This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.
+
 **Example**
 
 ```esql

docs/reference/query-languages/esql/_snippets/operators/examples/predicates.md

@@ -1,3 +1,5 @@
+% This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.
+
 **Examples**
 
 ```esql

x-pack/plugin/esql/qa/testFixtures/src/main/resources/convert.csv-spec

@@ -218,7 +218,8 @@ emp_no:integer | languages:integer | height:double
 convertToDatePeriod
 required_capability: cast_string_literal_to_temporal_amount
 //tag::castToDatePeriod[]
-row x = "2024-01-01"::datetime | eval y = x + "3 DAYS"::date_period, z = x - to_dateperiod("3 days");
+ROW x = "2024-01-01"::datetime
+| EVAL y = x + "3 DAYS"::date_period, z = x - TO_DATEPERIOD("3 days");
 //end::castToDatePeriod[]
 
 //tag::castToDatePeriod-result[]
@@ -230,7 +231,8 @@ x:datetime |y:datetime |z:datetime
 convertToTimeDuration
 required_capability: cast_string_literal_to_temporal_amount
 //tag::castToTimeDuration[]
-row x = "2024-01-01"::datetime | eval y = x + "3 hours"::time_duration, z = x - to_timeduration("3 hours");
+ROW x = "2024-01-01"::datetime
+| EVAL y = x + "3 hours"::time_duration, z = x - TO_TIMEDURATION("3 hours");
 //end::castToTimeDuration[]
 
 //tag::castToTimeDuration-result[]

x-pack/plugin/esql/qa/testFixtures/src/main/resources/date.csv-spec

@@ -344,7 +344,8 @@ null
 
 docsDateDiff#[skip:-8.12.99, reason:date_diff added in 8.13]
 // tag::docsDateDiff[]
-ROW date1 = TO_DATETIME("2023-12-02T11:00:00.000Z"), date2 = TO_DATETIME("2023-12-02T11:00:00.001Z")
+ROW date1 = TO_DATETIME("2023-12-02T11:00:00.000Z"),
+    date2 = TO_DATETIME("2023-12-02T11:00:00.001Z")
 | EVAL dd_ms = DATE_DIFF("microseconds", date1, date2)
 // end::docsDateDiff[]
 ;
@@ -425,12 +426,12 @@ evalDateDiffYearForDocs
 required_capability: date_diff_year_calendarial
 
 // tag::evalDateDiffYearForDocs[]
-ROW end_23=TO_DATETIME("2023-12-31T23:59:59.999Z"),
-  start_24=TO_DATETIME("2024-01-01T00:00:00.000Z"),
-    end_24=TO_DATETIME("2024-12-31T23:59:59.999")
-| EVAL end23_to_start24=DATE_DIFF("year", end_23, start_24)
-| EVAL end23_to_end24=DATE_DIFF("year", end_23, end_24)
-| EVAL start_to_end_24=DATE_DIFF("year", start_24, end_24)
+ROW end_23 = TO_DATETIME("2023-12-31T23:59:59.999Z"),
+  start_24 = TO_DATETIME("2024-01-01T00:00:00.000Z"),
+    end_24 = TO_DATETIME("2024-12-31T23:59:59.999")
+| EVAL end23_to_start24 = DATE_DIFF("year", end_23, start_24)
+| EVAL end23_to_end24   = DATE_DIFF("year", end_23, end_24)
+| EVAL start_to_end_24  = DATE_DIFF("year", start_24, end_24)
 // end::evalDateDiffYearForDocs[]
 ;
 
@@ -1002,7 +1003,8 @@ date:date                 | year:long
 docsDateExtractBusinessHours
 // tag::docsDateExtractBusinessHours[]
 FROM sample_data
-| WHERE DATE_EXTRACT("hour_of_day", @timestamp) < 9 AND DATE_EXTRACT("hour_of_day", @timestamp) >= 17
+| WHERE DATE_EXTRACT("hour_of_day", @timestamp) < 9
+    AND DATE_EXTRACT("hour_of_day", @timestamp) >= 17
 // end::docsDateExtractBusinessHours[]
 ;
 
@@ -1214,16 +1216,20 @@ required_capability: agg_values
 mvAppendDates
 required_capability: fn_mv_append
 
+// tag::mv_append_date[]
 FROM employees
 | WHERE emp_no == 10039 OR emp_no == 10040
 | SORT emp_no
-| EVAL dates = mv_append(birth_date, hire_date)
+| EVAL dates = MV_APPEND(birth_date, hire_date)
 | KEEP emp_no, birth_date, hire_date, dates
+// end::mv_append_date[]
 ;
 
+// tag::mv_append_date-result[]
 emp_no:integer | birth_date:date      | hire_date:date       | dates:date
 10039          | 1959-10-01T00:00:00Z | 1988-01-19T00:00:00Z | [1959-10-01T00:00:00Z, 1988-01-19T00:00:00Z]
 10040          | null                 | 1993-02-14T00:00:00Z | null 
+// end::mv_append_date-result[]
 ;
 
 

x-pack/plugin/esql/qa/testFixtures/src/main/resources/date_nanos.csv-spec

@@ -619,11 +619,19 @@ date nanos less than
 required_capability: to_date_nanos
 required_capability: date_nanos_binary_comparison
 
-FROM date_nanos | WHERE MV_MIN(nanos) < TO_DATE_NANOS("2023-10-23T12:27:28.948Z") AND millis > "2000-01-01" | SORT nanos DESC;
+// tag::to_date_nanos[]
+FROM date_nanos
+| WHERE MV_MIN(nanos) < TO_DATE_NANOS("2023-10-23T12:27:28.948Z")
+    AND millis > "2000-01-01"
+| SORT nanos DESC
+// end::to_date_nanos[]
+;
 
+// tag::to_date_nanos-result[]
 millis:date              | nanos:date_nanos               | num:long
 2023-10-23T12:15:03.360Z | 2023-10-23T12:15:03.360103847Z | 1698063303360103847
 2023-10-23T12:15:03.360Z | 2023-10-23T12:15:03.360103847Z | 1698063303360103847
+// end::to_date_nanos-result[]
 ;
 
 date nanos less than, no mv min

x-pack/plugin/esql/qa/testFixtures/src/main/resources/ip.csv-spec

@@ -548,8 +548,8 @@ beta         | 127.0.0.1
 ipPrefix
 required_capability: fn_ip_prefix
 //tag::ipPrefix[]
-row ip4 = to_ip("1.2.3.4"), ip6 = to_ip("fe80::cae2:65ff:fece:feb9")
-| eval ip4_prefix = ip_prefix(ip4, 24, 0), ip6_prefix = ip_prefix(ip6, 0, 112);
+ROW ip4 = to_ip("1.2.3.4"), ip6 = TO_IP("fe80::cae2:65ff:fece:feb9")
+| EVAL ip4_prefix = IP_PREFIX(ip4, 24, 0), ip6_prefix = IP_PREFIX(ip6, 0, 112);
 //end::ipPrefix[]
 
 //tag::ipPrefix-result[]

x-pack/plugin/esql/qa/testFixtures/src/main/resources/math.csv-spec

@@ -237,7 +237,7 @@ base: double | value: double | s:double
 ;
 
 logofNegativeValue#[skip:-8.12.99,reason:new scalar function added in 8.13]
-row base = 2.0, value = -2
+ROW base = 2.0, value = -2
 | EVAL s = LOG(base, value);
 
 warning:Line 2:12: evaluation of [LOG(base, value)] failed, treating result as null. Only first 20 failures recorded.
@@ -248,7 +248,7 @@ base: double | value: integer | s:double
 ;
 
 logofNegativeBase#[skip:-8.12.99,reason:new scalar function added in 8.13]
-row base = -2, value = 2.0
+ROW base = -2, value = 2.0
 | EVAL s = LOG(base, value);
 
 warning:Line 2:12: evaluation of [LOG(base, value)] failed, treating result as null. Only first 20 failures recorded.
@@ -259,7 +259,7 @@ base: integer | value: double | s:double
 ;
 
 logofBaseOne#[skip:-8.12.99,reason:new scalar function added in 8.13]
-row base = 1, value = 2
+ROW base = 1, value = 2
 | EVAL s = LOG(base, value);
 
 warning:Line 2:12: evaluation of [LOG(base, value)] failed, treating result as null. Only first 20 failures recorded.
@@ -270,7 +270,7 @@ base: integer | value: integer | s:double
 ;
 
 logofZero#[skip:-8.12.99,reason:new scalar function added in 8.13]
-row base = 2.0, value = 0.0
+ROW base = 2.0, value = 0.0
 | EVAL s = LOG(base, value);
 
 warning:Line 2:12: evaluation of [LOG(base, value)] failed, treating result as null. Only first 20 failures recorded.
@@ -281,7 +281,7 @@ base:double | value:double | s:double
 ;
 
 logofNegativeZero#[skip:-8.12.99,reason:new scalar function added in 8.13]
-row base = 2.0, value = -0.0
+ROW base = 2.0, value = -0.0
 | EVAL s = LOG(base, value);
 
 warning:Line 2:12: evaluation of [LOG(base, value)] failed, treating result as null. Only first 20 failures recorded.
@@ -292,95 +292,95 @@ base:double | value:double | s:double
 ;
 
 logofIntLong#[skip:-8.12.99,reason:new scalar function added in 8.13]
-row base = 10, value = to_long(1000000000000)
+ROW base = 10, value = to_long(1000000000000)
 | EVAL s = LOG(base, value);
 
 base:integer | value:long      | s:double
 10           | 1000000000000   | 12
 ;
 
 logofLongInt#[skip:-8.12.99,reason:new scalar function added in 8.13]
-row base = to_long(1000000000000), value = 10
+ROW base = to_long(1000000000000), value = 10
 | EVAL s = LOG(base, value);
 
 base:long             | value:integer | s:double
 1000000000000         | 10            | 0.08333333333333333
 ;
 
 logofLongLong#[skip:-8.12.99,reason:new scalar function added in 8.13]
-row base = to_long(1000000000000), value = to_long(1000000000000)
+ROW base = to_long(1000000000000), value = to_long(1000000000000)
 | EVAL s = LOG(base, value);
 
 base:long      | value:long     | s:double
 1000000000000  | 1000000000000  |1.0
 ;
 
 logofLongDouble#[skip:-8.12.99,reason:new scalar function added in 8.13]
-row base = to_long(1000000000000), value = 10.0
+ROW base = to_long(1000000000000), value = 10.0
 | EVAL s = LOG(base, value);
 
 base:long             | value:double | s:double
 1000000000000         | 10.0         | 0.08333333333333333
 ;
 
 logofDoubleLong#[skip:-8.12.99,reason:new scalar function added in 8.13]
-row base = 10.0, value = to_long(1000000000000)
+ROW base = 10.0, value = to_long(1000000000000)
 | EVAL s = LOG(base, value);
 
 base:double | value:long     | s:double
 10.0        | 1000000000000  | 12
 ;
 
 logofLongUnsignedLong#[skip:-8.12.99,reason:new scalar function added in 8.13]
-row base = to_long(1000000000000), value = to_ul(1000000000000000000)
+ROW base = to_long(1000000000000), value = to_ul(1000000000000000000)
 | EVAL s = LOG(base, value);
 
 base:long     | value:UNSIGNED_LONG | s:double
 1000000000000 | 1000000000000000000 | 1.5
 ;
 
 logofUnsignedLongLong#[skip:-8.12.99,reason:new scalar function added in 8.13]
-row base = to_ul(1000000000000000000), value = to_long(1000000000000)
+ROW base = to_ul(1000000000000000000), value = to_long(1000000000000)
 | EVAL s = LOG(base, value);
 
 base:UNSIGNED_LONG  | value:long     | s:double
 1000000000000000000 | 1000000000000  | 0.6666666666666666
 ;
 
 logofIntUnsignedLong#[skip:-8.12.99,reason:new scalar function added in 8.13]
-row base = 10, value = to_ul(1000000000000000000)
+ROW base = 10, value = to_ul(1000000000000000000)
 | EVAL s = LOG(base, value);
 
 base:integer | value:UNSIGNED_LONG | s:double
 10           | 1000000000000000000 | 18.0
 ;
 
 logofUnsignedLongInt#[skip:-8.12.99,reason:new scalar function added in 8.13]
-row base = to_ul(1000000000000000000), value = 10
+ROW base = to_ul(1000000000000000000), value = 10
 | EVAL s = LOG(base, value);
 
 base:UNSIGNED_LONG  | value:integer | s:double
 1000000000000000000 | 10            | 0.05555555555555555
 ;
 
 logofUnsignedLongUnsignedLong#[skip:-8.12.99,reason:new scalar function added in 8.13]
-row base = to_ul(1000000000000000000), value = to_ul(1000000000000000000)
+ROW base = to_ul(1000000000000000000), value = to_ul(1000000000000000000)
 | EVAL s = LOG(base, value);
 
 base:UNSIGNED_LONG  | value:UNSIGNED_LONG | s:double
 1000000000000000000 | 1000000000000000000 | 1.0
 ;
 
 logofUnsignedLongDouble#[skip:-8.12.99,reason:new scalar function added in 8.13]
-row base = to_ul(1000000000000000000), value = 1000000000.0
+ROW base = to_ul(1000000000000000000), value = 1000000000.0
 | EVAL s = LOG(base, value);
 
 base:UNSIGNED_LONG  | value:double | s:double
 1000000000000000000 | 1.0E9        | 0.5
 ;
 
 logofDoubleUnsignedLong#[skip:-8.12.99,reason:new scalar function added in 8.13]
-row base = 10.0, value = to_ul(1000000000000000000)
+ROW base = 10.0, value = to_ul(1000000000000000000)
 | EVAL s = LOG(base, value);
 
 base:double | value:UNSIGNED_LONG | s:double
@@ -389,7 +389,7 @@ base:double | value:UNSIGNED_LONG | s:double
 
 logofInt#[skip:-8.12.99,reason:new scalar function added in 8.13]
 // tag::logUnary[]
-row value = 100
+ROW value = 100
 | EVAL s = LOG(value);
 // end::logUnary[]
 
@@ -400,23 +400,23 @@ value: integer | s:double
 ;
 
 logofLong#[skip:-8.12.99,reason:new scalar function added in 8.13]
-row value = to_long(1000000000000)
+ROW value = to_long(1000000000000)
 | EVAL s = LOG(value);
 
 value: long   | s:double
 1000000000000 | 27.631021115928547
 ;
 
 logofUnsignedLong#[skip:-8.12.99,reason:new scalar function added in 8.13]
-row value = to_ul(1000000000000000000)
+ROW value = to_ul(1000000000000000000)
 | EVAL s = LOG(value);
 
 value: unsigned_long   | s:double
 1000000000000000000    | 41.44653167389282
 ;
 
 logofDouble#[skip:-8.12.99,reason:new scalar function added in 8.13]
-row value = 1000000000000.0
+ROW value = 1000000000000.0
 | EVAL s = LOG(value);
 
 value: double   | s:double
@@ -1323,7 +1323,7 @@ cbrt
 required_capability: fn_cbrt
 // tag::cbrt[]
 ROW d = 1000.0
-| EVAL c = cbrt(d)
+| EVAL c = CBRT(d)
 // end::cbrt[]
 ;
 

x-pack/plugin/esql/qa/testFixtures/src/main/resources/stats.csv-spec

@@ -2099,8 +2099,8 @@ FROM employees | STATS min = min(salary) by languages | SORT min + CASE(language
 
 weightedAvg
 required_capability: agg_weighted_avg
-from employees
-| stats w_avg_1 = weighted_avg(salary, 1), avg = avg(salary), w_avg_2 = weighted_avg(salary, height)
+FROM employees
+| STATS w_avg_1 = weighted_avg(salary, 1), avg = avg(salary), w_avg_2 = weighted_avg(salary, height)
 | EVAL w_avg_1 = ROUND(w_avg_1), avg = ROUND(avg), w_avg_2 = ROUND(w_avg_2)
 ;
 
@@ -2112,7 +2112,7 @@ weightedAvgGrouping
 required_capability: agg_weighted_avg
 // tag::weighted-avg[]
 FROM employees
-| STATS w_avg = WEIGHTED_AVG(salary, height) by languages
+| STATS w_avg = WEIGHTED_AVG(salary, height) BY languages
 | EVAL w_avg = ROUND(w_avg)
 | KEEP w_avg, languages
 | SORT languages

x-pack/plugin/esql/qa/testFixtures/src/main/resources/string.csv-spec

@@ -1722,9 +1722,9 @@ valuesGrouped
 required_capability: agg_values
 
 // tag::values-grouped[]
-  FROM employees
+FROM employees
 | EVAL first_letter = SUBSTRING(first_name, 0, 1)
-| STATS first_name=MV_SORT(VALUES(first_name)) BY first_letter
+| STATS first_name = MV_SORT(VALUES(first_name)) BY first_letter
 | SORT first_letter
 // end::values-grouped[]
 ;
@@ -1768,8 +1768,8 @@ M              | [foo, bar]
 
 locate#[skip:-8.13.99,reason:new string function added in 8.14]
 // tag::locate[]
-row a = "hello"
-| eval a_ll = locate(a, "ll")
+ROW a = "hello"
+| EVAL a_ll = LOCATE(a, "ll")
 // end::locate[]
 ;
 
@@ -1960,8 +1960,8 @@ base64Encode#[skip:-8.13.99,reason:new base64 function added in 8.14]
 required_capability: base64_decode_encode
 
 // tag::to_base64[]
-row a = "elastic" 
-| eval e = to_base64(a)
+ROW a = "elastic" 
+| EVAL e = TO_BASE64(a)
 // end::to_base64[]
 ;
 
@@ -1975,8 +1975,8 @@ base64Decode#[skip:-8.13.99,reason:new base64 function added in 8.14]
 required_capability: base64_decode_encode
 
 // tag::from_base64[]
-row a = "ZWxhc3RpYw=="
-| eval d = from_base64(a)
+ROW a = "ZWxhc3RpYw=="
+| EVAL d = FROM_BASE64(a)
 // end::from_base64[]
 ;