ESQL: Documentation for support for geo_point and point (elastic#103207)

* Start working on geo_point and point docs for ESQL

* Added to_cartesianpoint and includes

* Sub-headings for easier reading

* Improve sub-headings

* Hide to_long and support for longs in to_geopoint and to_cartesianpoint

docs/reference/esql/esql-functions.asciidoc

@@ -127,9 +127,11 @@ include::functions/tan.asciidoc[]
 include::functions/tanh.asciidoc[]
 include::functions/tau.asciidoc[]
 include::functions/to_boolean.asciidoc[]
+include::functions/to_cartesianpoint.asciidoc[]
 include::functions/to_datetime.asciidoc[]
 include::functions/to_degrees.asciidoc[]
 include::functions/to_double.asciidoc[]
+include::functions/to_geopoint.asciidoc[]
 include::functions/to_integer.asciidoc[]
 include::functions/to_ip.asciidoc[]
 include::functions/to_long.asciidoc[]

docs/reference/esql/esql-limitations.asciidoc

@@ -34,6 +34,9 @@ include::processing-commands/limit.asciidoc[tag=limitation]
 * `text`
 * `unsigned_long`
 * `version`
+* Spatial types
+** `geo_point`
+** `point`
 
 [discrete]
 ==== Unsupported types
@@ -44,10 +47,8 @@ include::processing-commands/limit.asciidoc[tag=limitation]
 ** `counter`
 ** `position`
 ** `aggregate_metric_double`
-* Geo/spatial
-** `geo_point`
+* Spatial types
 ** `geo_shape`
-** `point`
 ** `shape`
 * Date/time
 ** `date_nanos`
@@ -119,7 +120,7 @@ consequences. An {esql} query on a `text` field is case-sensitive. Furthermore,
 a subfield may have been mapped with a <<normalizer,normalizer>>, which can
 transform the original string. Or it may have been mapped with <<ignore-above>>,
 which can truncate the string. None of these mapping operations are applied to
-an {esql} query, which may lead to false positives or negatives. 
+an {esql} query, which may lead to false positives or negatives.
 
 To avoid these issues, a best practice is to be explicit about the field that
 you query, and query `keyword` sub-fields instead of `text` fields.
@@ -197,4 +198,4 @@ the <<esql-mv-functions,multivalue functions>>.
 [[esql-limitations-kibana]]
 === Kibana limitations
 
-include::esql-kibana.asciidoc[tag=limitations]
+include::esql-kibana.asciidoc[tag=limitations]

docs/reference/esql/functions/to_cartesianpoint.asciidoc

@@ -0,0 +1,19 @@
+[discrete]
+[[esql-to_cartesianpoint]]
+=== `TO_CARTESIANPOINT`
+Converts an input value to a `point` value.
+
+The input can be a single- or multi-valued field or an expression.
+The input type must be a string or a cartesian `point`.
+
+A string will only be successfully converted if it respects the
+https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry[WKT Point] format:
+
+[source.merge.styled,esql]
+----
+include::{esql-specs}/spatial.csv-spec[tag=to_cartesianpoint-str]
+----
+[%header.monospaced.styled,format=dsv,separator=|]
+|===
+include::{esql-specs}/spatial.csv-spec[tag=to_cartesianpoint-str-result]
+|===

docs/reference/esql/functions/to_geopoint.asciidoc

@@ -0,0 +1,19 @@
+[discrete]
+[[esql-to_geopoint]]
+=== `TO_GEOPOINT`
+Converts an input value to a `geo_point` value.
+
+The input can be a single- or multi-valued field or an expression.
+The input type must be a string or a `geo_point`.
+
+A string will only be successfully converted if it respects the
+https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry[WKT Point] format:
+
+[source.merge.styled,esql]
+----
+include::{esql-specs}/spatial.csv-spec[tag=to_geopoint-str]
+----
+[%header.monospaced.styled,format=dsv,separator=|]
+|===
+include::{esql-specs}/spatial.csv-spec[tag=to_geopoint-str-result]
+|===

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

@@ -9,9 +9,11 @@
 
 // tag::type_list[]
 * <<esql-to_boolean>>
+* <<esql-to_cartesianpoint>>
 * <<esql-to_datetime>>
 * <<esql-to_degrees>>
 * <<esql-to_double>>
+* <<esql-to_geopoint>>
 * <<esql-to_integer>>
 * <<esql-to_ip>>
 * <<esql-to_long>>
@@ -22,9 +24,11 @@
 // end::type_list[]
 
 include::to_boolean.asciidoc[]
+include::to_cartesianpoint.asciidoc[]
 include::to_datetime.asciidoc[]
 include::to_degrees.asciidoc[]
 include::to_double.asciidoc[]
+include::to_geopoint.asciidoc[]
 include::to_integer.asciidoc[]
 include::to_ip.asciidoc[]
 include::to_long.asciidoc[]

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

@@ -7,11 +7,16 @@ long:long           |pt:geo_point
 ;
 
 convertFromString#[skip:-8.11.99, reason:spatial type geo_point only added in 8.12]
+// tag::to_geopoint-str[]
 row wkt = "POINT(42.97109630194 14.7552534413725)"
-| eval pt = to_geopoint(wkt);
+| eval pt = to_geopoint(wkt)
+// end::to_geopoint-str[]
+;
 
+// tag::to_geopoint-str-result[]
 wkt:keyword                              |pt:geo_point
 "POINT(42.97109630194 14.7552534413725)" |POINT(42.97109630194 14.7552534413725)
+// end::to_geopoint-str-result[]
 ;
 
 convertFromLongArray#[skip:-8.11.99, reason:spatial type geo_point only added in 8.12]
@@ -57,14 +62,18 @@ long:long           |pt:cartesian_point
 ;
 
 convertCartesianFromString#[skip:-8.11.99, reason:spatial type cartesian_point only added in 8.12]
+// tag::to_cartesianpoint-str[]
 row wkt = ["POINT(4297.11 -1475.53)", "POINT(7580.93 2272.77)"]
 | mv_expand wkt
 | eval pt = to_cartesianpoint(wkt)
-| eval l = to_long(pt);
+// end::to_cartesianpoint-str[]
+;
 
-wkt:keyword               |pt:cartesian_point      |l:long
-"POINT(4297.11 -1475.53)" |POINT(4297.11 -1475.53) |5009771769843126025
-"POINT(7580.93 2272.77)"  |POINT(7580.93 2272.77)  |5038656556796611666
+// tag::to_cartesianpoint-str-result[]
+wkt:keyword               |pt:cartesian_point 
+"POINT(4297.11 -1475.53)" |POINT(4297.11 -1475.53)
+"POINT(7580.93 2272.77)"  |POINT(7580.93 2272.77)
+// end::to_cartesianpoint-str-result[]
 ;
 
 convertCartesianFromLongArray#[skip:-8.11.99, reason:spatial type cartesian_point only added in 8.12]