Add docs for the conversion functions (ESQL-1217)

Add docs for the `to_xxx()` conversion functions.

---------

Co-authored-by: Abdon Pijpelink <abdon.pijpelink@elastic.co>

docs/reference/esql/esql-functions.asciidoc

@@ -34,6 +34,12 @@ these functions:
 * <<esql-split>>
 * <<esql-starts_with>>
 * <<esql-substring>>
+* <<esql-to_boolean>>
+* <<esql-to_datetime>>
+* <<esql-to_double>>
+* <<esql-to_integer>>
+* <<esql-to_ip>>
+* <<esql-to_long>>
 * <<esql-to_string>>
 
 include::functions/abs.asciidoc[]
@@ -60,4 +66,10 @@ include::functions/round.asciidoc[]
 include::functions/split.asciidoc[]
 include::functions/starts_with.asciidoc[]
 include::functions/substring.asciidoc[]
+include::functions/to_boolean.asciidoc[]
+include::functions/to_datetime.asciidoc[]
+include::functions/to_double.asciidoc[]
+include::functions/to_integer.asciidoc[]
+include::functions/to_ip.asciidoc[]
+include::functions/to_long.asciidoc[]
 include::functions/to_string.asciidoc[]

docs/reference/esql/functions/mv_concat.asciidoc

@@ -18,13 +18,13 @@ include::{esql-specs}/string.csv-spec[tag=mv_concat-result]
 If you want to concat non-string fields call <<esql-to_string>> on them first:
 [source,esql]
 ----
-include::{esql-specs}/ints.csv-spec[tag=mv_concat]
+include::{esql-specs}/string.csv-spec[tag=mv_concat-to_string]
 ----
 
 Returns:
 
 [%header,format=dsv,separator=|]
 |===
-include::{esql-specs}/ints.csv-spec[tag=mv_concat-result]
+include::{esql-specs}/string.csv-spec[tag=mv_concat-to_string-result]
 |===
 

docs/reference/esql/functions/to_boolean.asciidoc

@@ -0,0 +1,27 @@
+[[esql-to_boolean]]
+=== `TO_BOOLEAN`
+Converts an input value to a boolean value.
+
+The input can be a single- or multi-valued field or an expression. The input
+type must be of a string or numeric type.
+
+A string value of *"true"* will be case-insensitive converted to the Boolean
+*true*. For anything else, including the empty string, the function will
+return *false*. For example:
+
+[source,esql]
+----
+include::{esql-specs}/boolean.csv-spec[tag=to_boolean]
+----
+
+returns:
+
+[%header,format=dsv,separator=|]
+|===
+include::{esql-specs}/boolean.csv-spec[tag=to_boolean-result]
+|===
+
+The numerical value of *0* will be converted to *false*, anything else will be
+converted to *true*.
+
+Alias: TO_BOOL

docs/reference/esql/functions/to_datetime.asciidoc

@@ -0,0 +1,52 @@
+[[esql-to_datetime]]
+=== `TO_DATETIME`
+Converts an input value to a date value.
+
+The input can be a single- or multi-valued field or an expression. The input
+type must be of a string or numeric type.
+
+A string will only be successfully converted if it's respecting the format
+`yyyy-MM-dd'T'HH:mm:ss.SSS'Z'`. For example:
+
+[source,esql]
+----
+include::{esql-specs}/date.csv-spec[tag=to_datetime-str]
+----
+
+returns:
+
+[%header,format=dsv,separator=|]
+|===
+include::{esql-specs}/date.csv-spec[tag=to_datetime-str-result]
+|===
+
+Note that in this example, the last value in the source multi-valued
+field has not been converted. The reason being that if the date format is not
+respected, the conversion will result in a *null* value. When this happens a
+_Warning_ header is added to the response. The header will provide information
+on the source of the failure:
+
+`"Line 1:112: evaluation of [TO_DATETIME(string)] failed, treating result as null. Only first 20 failures recorded."`
+
+A following header will contain the failure reason and the offending value:
+
+`"java.lang.IllegalArgumentException: failed to parse date field [1964-06-02 00:00:00] with format [yyyy-MM-dd'T'HH:mm:ss.SSS'Z']"`
+
+
+If the input parameter is of a numeric type, its value will be interpreted as
+milliseconds since the https://en.wikipedia.org/wiki/Unix_time[Unix epoch].
+For example:
+
+[source,esql]
+----
+include::{esql-specs}/date.csv-spec[tag=to_datetime-int]
+----
+
+returns:
+
+[%header,format=dsv,separator=|]
+|===
+include::{esql-specs}/date.csv-spec[tag=to_datetime-int-result]
+|===
+
+Alias: TO_DT

docs/reference/esql/functions/to_double.asciidoc

@@ -0,0 +1,40 @@
+[[esql-to_double]]
+=== `TO_DOUBLE`
+Converts an input value to a double value.
+
+The input can be a single- or multi-valued field or an expression. The input
+type must be of a boolean, date, string or numeric type.
+
+Example:
+
+[source,esql]
+----
+include::{esql-specs}/floats.csv-spec[tag=to_double-str]
+----
+
+returns:
+
+[%header,format=dsv,separator=|]
+|===
+include::{esql-specs}/floats.csv-spec[tag=to_double-str-result]
+|===
+
+Note that in this example, the last conversion of the string isn't
+possible. When this happens, the result is a *null* value. In this case a
+_Warning_ header is added to the response. The header will provide information
+on the source of the failure:
+
+`"Line 1:115: evaluation of [TO_DOUBLE(str2)] failed, treating result as null. Only first 20 failures recorded."`
+
+A following header will contain the failure reason and the offending value:
+
+`"java.lang.NumberFormatException: For input string: \"foo\""`
+
+
+If the input parameter is of a date type, its value will be interpreted as
+milliseconds since the https://en.wikipedia.org/wiki/Unix_time[Unix epoch],
+converted to double.
+
+Boolean *true* will be converted to double *1.0*, *false* to *0.0*.
+
+Alias: TO_DBL

docs/reference/esql/functions/to_integer.asciidoc

@@ -0,0 +1,40 @@
+[[esql-to_integer]]
+=== `TO_INTEGER`
+Converts an input value to an integer  value.
+
+The input can be a single- or multi-valued field or an expression. The input
+type must be of a boolean, date, string or numeric type.
+
+Example:
+
+[source,esql]
+----
+include::{esql-specs}/ints.csv-spec[tag=to_int-long]
+----
+
+returns:
+
+[%header,format=dsv,separator=|]
+|===
+include::{esql-specs}/ints.csv-spec[tag=to_int-long-result]
+|===
+
+Note that in this example, the last value of the multi-valued field cannot
+be converted as an integer. When this happens, the result is a *null* value.
+In this case a _Warning_ header is added to the response. The header will
+provide information on the source of the failure:
+
+`"Line 1:61: evaluation of [TO_INTEGER(long)] failed, treating result as null. Only first 20 failures recorded."`
+
+A following header will contain the failure reason and the offending value:
+
+`"org.elasticsearch.xpack.ql.QlIllegalArgumentException: [501379200000] out of [integer] range"`
+
+
+If the input parameter is of a date type, its value will be interpreted as
+milliseconds since the https://en.wikipedia.org/wiki/Unix_time[Unix epoch],
+converted to integer.
+
+Boolean *true* will be converted to integer *1*, *false* to *0*.
+
+Alias: TO_INT

docs/reference/esql/functions/to_ip.asciidoc

@@ -0,0 +1,30 @@
+[[esql-to_ip]]
+=== `TO_IP`
+Converts an input string to an IP value.
+
+The input can be a single- or multi-valued field or an expression.
+
+Example:
+
+[source,esql]
+----
+include::{esql-specs}/ip.csv-spec[tag=to_ip]
+----
+
+which returns:
+
+[%header,format=dsv,separator=|]
+|===
+include::{esql-specs}/ip.csv-spec[tag=to_ip-result]
+|===
+
+Note that in the example above the last conversion of the string isn't
+possible. When this happens, the result is a *null* value. In this case a
+_Warning_ header is added to the response. The header will provide information
+on the source of the failure:
+
+`"Line 1:68: evaluation of [TO_IP(str2)] failed, treating result as null. Only first 20 failures recorded."`
+
+A following header will contain the failure reason and the offending value:
+
+`"java.lang.IllegalArgumentException: 'foo' is not an IP string literal."`

docs/reference/esql/functions/to_long.asciidoc

@@ -0,0 +1,38 @@
+[[esql-to_long]]
+=== `TO_LONG`
+Converts an input value to a long value.
+
+The input can be a single- or multi-valued field or an expression. The input
+type must be of a boolean, date, string or numeric type.
+
+Example:
+
+[source,esql]
+----
+include::{esql-specs}/ints.csv-spec[tag=to_long-str]
+----
+
+returns:
+
+[%header,format=dsv,separator=|]
+|===
+include::{esql-specs}/ints.csv-spec[tag=to_long-str-result]
+|===
+
+Note that in this example, the last conversion of the string isn't
+possible. When this happens, the result is a *null* value. In this case a
+_Warning_ header is added to the response. The header will provide information
+on the source of the failure:
+
+`"Line 1:113: evaluation of [TO_LONG(str3)] failed, treating result as null. Only first 20 failures recorded."`
+
+A following header will contain the failure reason and the offending value:
+
+`"java.lang.NumberFormatException: For input string: \"foo\""`
+
+
+If the input parameter is of a date type, its value will be interpreted as
+milliseconds since the https://en.wikipedia.org/wiki/Unix_time[Unix epoch],
+converted to long.
+
+Boolean *true* will be converted to long *1*, *false* to *0*.

docs/reference/esql/functions/to_string.asciidoc

@@ -4,26 +4,28 @@ Converts a field into a string. For example:
 
 [source,esql]
 ----
-include::{esql-specs}/ints.csv-spec[tag=to_string]
+include::{esql-specs}/string.csv-spec[tag=to_string]
 ----
 
 which returns:
 
 [%header,format=dsv,separator=|]
 |===
-include::{esql-specs}/ints.csv-spec[tag=to_string-result]
+include::{esql-specs}/string.csv-spec[tag=to_string-result]
 |===
 
 It also works fine on multivalued fields:
 
 [source,esql]
 ----
-include::{esql-specs}/ints.csv-spec[tag=to_string_multivalue]
+include::{esql-specs}/string.csv-spec[tag=to_string_multivalue]
 ----
 
 which returns:
 
 [%header,format=dsv,separator=|]
 |===
-include::{esql-specs}/ints.csv-spec[tag=to_string_multivalue-result]
+include::{esql-specs}/string.csv-spec[tag=to_string_multivalue-result]
 |===
+
+Alias: TO_STR

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

@@ -159,6 +159,19 @@ emp_no:integer |is_rehired:boolean         |rehired_str:keyword        |rehired_
 10005          |[false, false, false, true]|[false, false, false, true]|[false, false, false, true] |false
 ;
 
+convertFromStringForDocs
+// tag::to_boolean[]
+ROW str = ["true", "TRuE", "false", "", "yes", "1"]
+| EVAL bool = TO_BOOLEAN(str)
+// end::to_boolean[]
+;
+
+// tag::to_boolean-result[]
+str:keyword                                | bool:boolean
+["true", "TRuE", "false", "", "yes", "1"] | [true, true, false, false, false, false]
+// end::to_boolean-result[]
+;
+
 convertFromDouble
 from employees | eval h_2 = height - 2.0, double2bool = to_boolean(h_2) | where emp_no in (10036, 10037, 10038) | project emp_no, height, *2bool;
 

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

@@ -166,11 +166,17 @@ birth_date:date         |bd:date
 1964-06-02T00:00:00.000Z|1964-06-02T00:00:00.000Z
 ;
 
-convertFromString
-row string = ["1953-09-02T00:00:00.000Z", "1964-06-02T00:00:00.000Z"] | eval datetime = to_datetime(string);
+convertFromString-IgnoreWarnings
+// tag::to_datetime-str[]
+ROW string = ["1953-09-02T00:00:00.000Z", "1964-06-02T00:00:00.000Z", "1964-06-02 00:00:00"]
+| EVAL datetime = TO_DATETIME(string)
+// end::to_datetime-str[]
+;
 
-string:keyword                                      |datetime:date
-[1953-09-02T00:00:00.000Z, 1964-06-02T00:00:00.000Z]|[1953-09-02T00:00:00.000Z, 1964-06-02T00:00:00.000Z]
+// tag::to_datetime-str-result[]
+string:keyword                                          |datetime:date
+["1953-09-02T00:00:00.000Z", "1964-06-02T00:00:00.000Z", "1964-06-02 00:00:00"]|[1953-09-02T00:00:00.000Z, 1964-06-02T00:00:00.000Z]
+// end::to_datetime-str-result[]
 ;
 
 convertFromLong
@@ -194,6 +200,20 @@ int:integer           |dt:date
 [501379200, 520128000]|[1970-01-06T19:16:19.200Z, 1970-01-07T00:28:48.000Z]
 ;
 
+// TODO: add a -1, once https://github.com/elastic/elasticsearch-internal/issues/1203 is fixed
+convertFromIntForDocs
+// tag::to_datetime-int[]
+ROW int = [0, 1]
+| EVAL dt = TO_DATETIME(int)
+// end::to_datetime-int[]
+;
+
+// tag::to_datetime-int-result[]
+int:integer |dt:date
+[0, 1]     |[1970-01-01T00:00:00.000Z, 1970-01-01T00:00:00.001Z]
+// end::to_datetime-int-result[]
+;
+
 autoBucketSimpleMonth
 // tag::auto_bucket_month[]
 ROW date=TO_DATETIME("1985-07-09T00:00:00.000Z")

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

@@ -56,10 +56,16 @@ emp_no:integer |hire_date:date          |hire_double:double
 ;
 
 convertFromString-IgnoreWarnings
-row dbl_str = "5.20128E11" | eval dbl = to_double(dbl_str), dbl2 = to_double("520128000000"), no_number = to_double("foo");
+// tag::to_double-str[]
+ROW str1 = "5.20128E11", str2 = "foo"
+| EVAL dbl = TO_DOUBLE("520128000000"), dbl1 = TO_DOUBLE(str1), dbl2 = TO_DOUBLE(str2)
+// end::to_double-str[]
+;
 
-dbl_str:keyword|dbl:double     |dbl2:double    |no_number:double 
-5.20128E11     |5.20128E11     |5.20128E11     |null
+// tag::to_double-str-result[]
+str1:keyword |str2:keyword |dbl:double |dbl1:double |dbl2:double
+5.20128E11   |foo          |5.20128E11 |5.20128E11  |null
+// end::to_double-str-result[]
 ;
 
 convertFromLong

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

@@ -70,10 +70,16 @@ tf:boolean     |t2l:long       |f2l:long       |tf2l:long
 ;
 
 convertStringToLong-IgnoreWarnings
-row long_str = "2147483648", long_dbl_str = "2147483648.2" | eval ls2l = to_long(long_str), lds2l = to_long(long_dbl_str), no_number = to_long("foo");
+// tag::to_long-str[]
+ROW str1 = "2147483648", str2 = "2147483648.2", str3 = "foo"
+| EVAL long1 = TO_LONG(str1), long2 = TO_LONG(str2), long3 = TO_LONG(str3)
+// end::to_long-str[]
+;
 
-long_str:keyword |long_dbl_str:keyword |ls2l:long   |lds2l:long     |no_number:long
-2147483648       |2147483648.2         |2147483648  |2147483648     |null
+// tag::to_long-str-result[]
+str1:keyword |str2:keyword |str3:keyword |long1:long  |long2:long |long3:long
+2147483648   |2147483648.2 |foo          |2147483648  |2147483648 |null
+// end::to_long-str-result[]
 ;
 
 convertDoubleToLong-IgnoreWarnings
@@ -93,10 +99,16 @@ int:integer       |ii:integer
 ;
 
 convertLongToInt-IgnoreWarnings
-row int = [5013792, 520128] | eval long = to_long(int) | eval ii = to_integer(long), not_int = to_integer(501379200000) | project long, ii, not_int;
+// tag::to_int-long[]
+ROW long = [5013792, 2147483647, 501379200000]
+| EVAL int = TO_INTEGER(long)
+// end::to_int-long[]
+;
 
-long:long         |ii:integer        |not_int:integer
-[5013792, 520128] |[5013792, 520128] |null
+// tag::to_int-long-result[]
+long:long                           |int:integer
+[5013792, 2147483647, 501379200000] |[5013792, 2147483647]
+// end::to_int-long-result[]
 ;
 
 convertDatetimeToInt
@@ -127,45 +139,6 @@ d:double       |d2i:integer   |overflow:integer
 123.4          |123           |null    
 ;
 
-convertToStringSimple
-// tag::to_string[]
-ROW a=10
-| EVAL j = TO_STRING(a)
-// end::to_string[]
-;
-
-// tag::to_string-result[]
-a:integer | j:keyword
-       10 | "10"
-// end::to_string-result[]
-;
-
-convertToStringMultivalue
-// tag::to_string_multivalue[]
-ROW a=[10, 9, 8]
-| EVAL j = TO_STRING(a)
-// end::to_string_multivalue[]
-;
-
-// tag::to_string_multivalue-result[]
- a:integer | j:keyword
-[10, 9, 8] | ["10", "9", "8"]
-// end::to_string_multivalue-result[]
-;
-
-mvJoin
-// tag::mv_concat[]
-ROW a=[10, 9, 8]
-| EVAL j = MV_CONCAT(TO_STRING(a), ", ")
-// end::mv_concat[]
-;
-
-// tag::mv_concat-result[]
- a:integer | j:keyword
-[10, 9, 8] | "10, 9, 8"
-// end::mv_concat-result[]
-;
-
 lessThanMultivalue
 from employees | where salary_change.int < 1 | project emp_no, salary_change.int | sort emp_no | limit 5;
 

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

@@ -187,8 +187,15 @@ null                                                  |null
 ;
 
 convertFromString-IgnoreWarnings
-row ip_str = "1.1.1.1" | eval ip = to_ip(ip_str), not_ip = to_ip("blah") | where cidr_match(ip, "1.0.0.0/8");
+// tag::to_ip[]
+ROW str1 = "1.1.1.1", str2 = "foo"
+| EVAL ip1 = TO_IP(str1), ip2 = TO_IP(str2)
+| WHERE CIDR_MATCH(ip1, "1.0.0.0/8")
+// end::to_ip[]
+;
 
-ip_str:keyword    |ip:ip   |not_ip:ip
-1.1.1.1           |1.1.1.1 |null
+// tag::to_ip-result[]
+str1:keyword |str2:keyword |ip1:ip  |ip2:ip
+1.1.1.1      |foo          |1.1.1.1 |null
+// end::to_ip-result[]
 ;

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

@@ -382,3 +382,42 @@ emp_no:integer |byte:keyword   |short:keyword  |long:keyword |int:keyword |langu
 10001          |2              |2              |2            |2           |2
 10002          |5              |5              |5            |5           |5
 ;
+
+convertFromIntSimple
+// tag::to_string[]
+ROW a=10
+| EVAL j = TO_STRING(a)
+// end::to_string[]
+;
+
+// tag::to_string-result[]
+a:integer | j:keyword
+       10 | "10"
+// end::to_string-result[]
+;
+
+convertFromIntMultivalue
+// tag::to_string_multivalue[]
+ROW a=[10, 9, 8]
+| EVAL j = TO_STRING(a)
+// end::to_string_multivalue[]
+;
+
+// tag::to_string_multivalue-result[]
+ a:integer | j:keyword
+[10, 9, 8] | ["10", "9", "8"]
+// end::to_string_multivalue-result[]
+;
+
+mvConcatToString
+// tag::mv_concat-to_string[]
+ROW a=[10, 9, 8]
+| EVAL j = MV_CONCAT(TO_STRING(a), ", ")
+// end::mv_concat-to_string[]
+;
+
+// tag::mv_concat-to_string-result[]
+ a:integer | j:keyword
+[10, 9, 8] | "10, 9, 8"
+// end::mv_concat-to_string-result[]
+;