mirror of
https://github.com/honeymoose/OpenSearch.git
synced 2025-02-07 21:48:39 +00:00
ae202fda21
Enables support for Cartesian geometries shape type. We still need to decide how to handle the distance function since it is currently using the haversine distance formula and returns results in meters, which doesn't make any sense for Cartesian geometries. Closes #46412 Relates to #43644
211 lines
4.7 KiB
Plaintext
211 lines
4.7 KiB
Plaintext
[role="xpack"]
|
|
[testenv="basic"]
|
|
[[sql-functions-geo]]
|
|
=== Geo Functions
|
|
|
|
beta[]
|
|
|
|
The geo functions work with geometries stored in `geo_point`, `geo_shape` and `shape` fields, or returned by other geo functions.
|
|
|
|
==== Limitations
|
|
|
|
<<geo-point, `geo_point`>>, <<geo-shape, `geo_shape`>> and <<shape, `shape`>> and types are represented in SQL as
|
|
geometry and can be used interchangeably with the following exceptions:
|
|
|
|
* `geo_shape` and `shape` fields don't have doc values, therefore these fields cannot be used for filtering, grouping
|
|
or sorting.
|
|
|
|
* `geo_points` fields are indexed and have doc values by default, however only latitude and longitude are stored and
|
|
indexed with some loss of precision from the original values (4.190951585769653E-8 for the latitude and
|
|
8.381903171539307E-8 for longitude). The altitude component is accepted but not stored in doc values nor indexed.
|
|
Therefore calling `ST_Z` function in the filtering, grouping or sorting will return `null`.
|
|
|
|
==== Geometry Conversion
|
|
|
|
[[sql-functions-geo-st-as-wkt]]
|
|
===== `ST_AsWKT`
|
|
|
|
.Synopsis:
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
ST_AsWKT(
|
|
geometry <1>
|
|
)
|
|
--------------------------------------------------
|
|
|
|
*Input*:
|
|
|
|
<1> geometry
|
|
|
|
*Output*: string
|
|
|
|
.Description:
|
|
|
|
Returns the WKT representation of the `geometry`.
|
|
|
|
["source","sql",subs="attributes,macros"]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/geo.csv-spec[aswkt]
|
|
--------------------------------------------------
|
|
|
|
|
|
[[sql-functions-geo-st-wkt-to-sql]]
|
|
===== `ST_WKTToSQL`
|
|
|
|
.Synopsis:
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
ST_WKTToSQL(
|
|
string <1>
|
|
)
|
|
--------------------------------------------------
|
|
|
|
*Input*:
|
|
|
|
<1> string WKT representation of geometry
|
|
|
|
*Output*: geometry
|
|
|
|
.Description:
|
|
|
|
Returns the geometry from WKT representation.
|
|
|
|
["source","sql",subs="attributes,macros"]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/geo.csv-spec[wkttosql]
|
|
--------------------------------------------------
|
|
|
|
==== Geometry Properties
|
|
|
|
[[sql-functions-geo-st-geometrytype]]
|
|
===== `ST_GeometryType`
|
|
|
|
.Synopsis:
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
ST_GeometryType(
|
|
geometry <1>
|
|
)
|
|
--------------------------------------------------
|
|
|
|
*Input*:
|
|
|
|
<1> geometry
|
|
|
|
*Output*: string
|
|
|
|
.Description:
|
|
|
|
Returns the type of the `geometry` such as POINT, MULTIPOINT, LINESTRING, MULTILINESTRING, POLYGON, MULTIPOLYGON, GEOMETRYCOLLECTION, ENVELOPE or CIRCLE.
|
|
|
|
["source","sql",subs="attributes,macros"]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/geo.csv-spec[geometrytype]
|
|
--------------------------------------------------
|
|
|
|
[[sql-functions-geo-st-x]]
|
|
===== `ST_X`
|
|
|
|
.Synopsis:
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
ST_X(
|
|
geometry <1>
|
|
)
|
|
--------------------------------------------------
|
|
|
|
*Input*:
|
|
|
|
<1> geometry
|
|
|
|
*Output*: double
|
|
|
|
.Description:
|
|
|
|
Returns the longitude of the first point in the geometry.
|
|
|
|
["source","sql",subs="attributes,macros"]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/geo.csv-spec[x]
|
|
--------------------------------------------------
|
|
|
|
[[sql-functions-geo-st-y]]
|
|
===== `ST_Y`
|
|
|
|
.Synopsis:
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
ST_Y(
|
|
geometry <1>
|
|
)
|
|
--------------------------------------------------
|
|
|
|
*Input*:
|
|
|
|
<1> geometry
|
|
|
|
*Output*: double
|
|
|
|
.Description:
|
|
|
|
Returns the latitude of the first point in the geometry.
|
|
|
|
["source","sql",subs="attributes,macros"]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/geo.csv-spec[y]
|
|
--------------------------------------------------
|
|
|
|
[[sql-functions-geo-st-z]]
|
|
===== `ST_Z`
|
|
|
|
.Synopsis:
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
ST_Z(
|
|
geometry <1>
|
|
)
|
|
--------------------------------------------------
|
|
|
|
*Input*:
|
|
|
|
<1> geometry
|
|
|
|
*Output*: double
|
|
|
|
.Description:
|
|
|
|
Returns the altitude of the first point in the geometry.
|
|
|
|
["source","sql",subs="attributes,macros"]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/geo.csv-spec[z]
|
|
--------------------------------------------------
|
|
|
|
[[sql-functions-geo-st-distance]]
|
|
===== `ST_Distance`
|
|
|
|
.Synopsis:
|
|
[source, sql]
|
|
--------------------------------------------------
|
|
ST_Distance(
|
|
geometry, <1>
|
|
geometry <2>
|
|
)
|
|
--------------------------------------------------
|
|
|
|
*Input*:
|
|
|
|
<1> source geometry
|
|
<2> target geometry
|
|
|
|
*Output*: Double
|
|
|
|
.Description:
|
|
|
|
Returns the distance between geometries in meters. Both geometries have to be points.
|
|
|
|
["source","sql",subs="attributes,macros"]
|
|
--------------------------------------------------
|
|
include-tagged::{sql-specs}/docs/geo.csv-spec[distance]
|
|
--------------------------------------------------
|