[DOCS] ES|QL implicit casting (#108618)

* implicit casting doc

docs/reference/esql/esql-language.asciidoc

@@ -14,6 +14,7 @@ Detailed reference documentation for the {esql} language:
 * <<esql-multivalued-fields>>
 * <<esql-enrich-data>>
 * <<esql-process-data-with-dissect-and-grok>>
+* <<esql-implicit-casting>>
 
 include::esql-syntax.asciidoc[]
 include::esql-commands.asciidoc[]
@@ -23,3 +24,4 @@ include::esql-index-options.asciidoc[]
 include::multivalued-fields.asciidoc[]
 include::esql-process-data-with-dissect-grok.asciidoc[]
 include::esql-enrich-data.asciidoc[]
+include::implicit-casting.asciidoc[]

docs/reference/esql/functions/type-conversion-functions.asciidoc

@@ -5,6 +5,11 @@
 <titleabbrev>Type conversion functions</titleabbrev>
 ++++
 
+[TIP]
+====
+{esql} supports implicit casting from string literals to certain data types. Refer to <<esql-implicit-casting,implicit casting>> for details.
+====
+
 {esql} supports these type conversion functions:
 
 // tag::type_list[]

docs/reference/esql/implicit-casting.asciidoc

@@ -0,0 +1,53 @@
+[[esql-implicit-casting]]
+=== {esql} implicit casting
+
+++++
+<titleabbrev>Implicit casting</titleabbrev>
+++++
+
+Often users will input `datetime`, `ip`, `version`, or geospatial objects as simple strings in their queries for use in predicates, functions, or expressions. {esql} provides <<esql-type-conversion-functions, type conversion functions>> to explicitly convert these strings into the desired data types.
+
+Without implicit casting users must explicitly code these `to_X` functions in their queries, when string literals don't match the target data types they are assigned or compared to. Here is an example of using `to_datetime` to explicitly perform a data type conversion.
+
+[source.merge.styled,esql]
+----
+FROM employees
+| EVAL dd_ns1=date_diff("day", to_datetime("2023-12-02T11:00:00.00Z"), birth_date)
+| SORT emp_no
+| KEEP dd_ns1
+| LIMIT 1
+----
+
+Implicit casting improves usability, by automatically converting string literals to the target data type. This is most useful when the target data type is `datetime`, `ip`, `version` or a geo spatial. It is natural to specify these as a string in queries.
+
+The first query can be coded without calling the `to_datetime` function, as follows:
+
+[source.merge.styled,esql]
+----
+FROM employees
+| EVAL dd_ns1=date_diff("day", "2023-12-02T11:00:00.00Z", birth_date)
+| SORT emp_no
+| KEEP dd_ns1
+| LIMIT 1
+----
+
+[float]
+=== Implicit casting support
+
+The following table details which {esql} operations support implicit casting for different data types.
+
+[%header.monospaced.styled,format=dsv,separator=|]
+|===
+||ScalarFunction|BinaryComparison|ArithmeticOperation|InListPredicate|AggregateFunction
+|DATETIME|Y|Y|Y|Y|N
+|DOUBLE|Y|N|N|N|N
+|LONG|Y|N|N|N|N
+|INTEGER|Y|N|N|N|N
+|IP|Y|Y|Y|Y|N
+|VERSION|Y|Y|Y|Y|N
+|GEO_POINT|Y|N|N|N|N
+|GEO_SHAPE|Y|N|N|N|N
+|CARTESIAN_POINT|Y|N|N|N|N
+|CARTESIAN_SHAPE|Y|N|N|N|N
+|BOOLEAN|Y|Y|Y|Y|N
+|===