diff --git a/docs/reference/esql/esql-functions.asciidoc b/docs/reference/esql/esql-functions.asciidoc index b921719fc097b..c463c13a34e74 100644 --- a/docs/reference/esql/esql-functions.asciidoc +++ b/docs/reference/esql/esql-functions.asciidoc @@ -61,9 +61,11 @@ these functions: * <> * <> * <> +* <> * <> * <> * <> +* <> * <> * <> * <> @@ -127,9 +129,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[] diff --git a/docs/reference/esql/esql-limitations.asciidoc b/docs/reference/esql/esql-limitations.asciidoc index f1971fd409754..00f5b056c7ebe 100644 --- a/docs/reference/esql/esql-limitations.asciidoc +++ b/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 <>, which can transform the original string. Or it may have been mapped with <>, 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-limitations-kibana]] === Kibana limitations -include::esql-kibana.asciidoc[tag=limitations] \ No newline at end of file +include::esql-kibana.asciidoc[tag=limitations] diff --git a/docs/reference/esql/functions/to_cartesianpoint.asciidoc b/docs/reference/esql/functions/to_cartesianpoint.asciidoc new file mode 100644 index 0000000000000..1fb64542681e2 --- /dev/null +++ b/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] +|=== diff --git a/docs/reference/esql/functions/to_geopoint.asciidoc b/docs/reference/esql/functions/to_geopoint.asciidoc new file mode 100644 index 0000000000000..83936af0c71b3 --- /dev/null +++ b/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] +|=== diff --git a/docs/reference/esql/functions/type-conversion-functions.asciidoc b/docs/reference/esql/functions/type-conversion-functions.asciidoc index 640006c936526..48a9b175d3d65 100644 --- a/docs/reference/esql/functions/type-conversion-functions.asciidoc +++ b/docs/reference/esql/functions/type-conversion-functions.asciidoc @@ -9,9 +9,11 @@ // tag::type_list[] * <> +* <> * <> * <> * <> +* <> * <> * <> * <> @@ -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[] diff --git a/x-pack/plugin/esql/qa/testFixtures/src/main/resources/spatial.csv-spec b/x-pack/plugin/esql/qa/testFixtures/src/main/resources/spatial.csv-spec index 0ec7c2d6f84e8..e5039377b4a40 100644 --- a/x-pack/plugin/esql/qa/testFixtures/src/main/resources/spatial.csv-spec +++ b/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]