ES|QL spatial functions

Serverless Stack

ES|QL supports these spatial functions:

• ST_DISTANCE
• ST_INTERSECTS
• ST_DISJOINT
• ST_CONTAINS
• ST_WITHIN
• ST_X
• ST_Y
• ST_ENVELOPE Stack Preview Serverless Preview
  • ST_XMAX Stack Preview Serverless Preview
  • ST_XMIN Stack Preview Serverless Preview
  • ST_YMAX Stack Preview Serverless Preview
  • ST_YMIN Stack Preview Serverless Preview
• ST_GEOTILE Stack Preview Serverless Preview
• ST_GEOHEX Stack Preview Serverless Preview
• ST_GEOHASH Stack Preview Serverless Preview

Syntax

×

Parameters

geomA

Expression of type geo_point or cartesian_point. If null, the function returns null.

geomB

Expression of type geo_point or cartesian_point. If null, the function returns null. The second parameter must also have the same coordinate system as the first. This means it is not possible to combine geo_point and cartesian_point parameters.

Description

Computes the distance between two points. For cartesian geometries, this is the pythagorean distance in the same units as the original coordinates. For geographic geometries, this is the circular distance along the great circle in meters.

Supported types

Example

FROM airports
| WHERE abbrev == "CPH"
| EVAL distance = ST_DISTANCE(location, city_location)
| KEEP abbrev, name, location, city_location, distance
		

Syntax

×

Parameters

geomA

Expression that is either a geometry (geo_point, cartesian_point, geo_shape or cartesian_shape) or a geo-grid value (geohash, geotile, geohex). If null, the function returns null.

geomB

Expression that is either a geometry (geo_point, cartesian_point, geo_shape or cartesian_shape) or a geo-grid value (geohash, geotile, geohex). If null, the function returns null. The second parameter must also have the same coordinate system as the first. This means it is not possible to combine geo_* and cartesian_* parameters.

Description

Returns true if two geometries intersect. They intersect if they have any point in common, including their interior points (points along lines or within polygons). This is the inverse of the ST_DISJOINT function. In mathematical terms: ST_Intersects(A, B) ⇔ A ⋂ B ≠ ∅

Supported types

Example

FROM airports
| WHERE ST_INTERSECTS(location, TO_GEOSHAPE("POLYGON((42 14, 43 14, 43 15, 42 15, 42 14))"))
		

Syntax

×

Parameters

geomA

Expression that is either a geometry (geo_point, cartesian_point, geo_shape or cartesian_shape) or a geo-grid value (geohash, geotile, geohex). If null, the function returns null.

geomB

Expression that is either a geometry (geo_point, cartesian_point, geo_shape or cartesian_shape) or a geo-grid value (geohash, geotile, geohex). If null, the function returns null. The second parameter must also have the same coordinate system as the first. This means it is not possible to combine geo_* and cartesian_* parameters.

Description

Returns whether the two geometries or geometry columns are disjoint. This is the inverse of the ST_INTERSECTS function. In mathematical terms: ST_Disjoint(A, B) ⇔ A ⋂ B = ∅

Supported types

Example

FROM airport_city_boundaries
| WHERE ST_DISJOINT(city_boundary, TO_GEOSHAPE("POLYGON((-10 -60, 120 -60, 120 60, -10 60, -10 -60))"))
| KEEP abbrev, airport, region, city, city_location
		

Syntax

×

Parameters

geomA

Expression of type geo_point, cartesian_point, geo_shape or cartesian_shape. If null, the function returns null.

geomB

Expression of type geo_point, cartesian_point, geo_shape or cartesian_shape. If null, the function returns null. The second parameter must also have the same coordinate system as the first. This means it is not possible to combine geo_* and cartesian_* parameters.

Description

Returns whether the first geometry contains the second geometry. This is the inverse of the ST_WITHIN function.

Supported types

Example

FROM airport_city_boundaries
| WHERE ST_CONTAINS(city_boundary, TO_GEOSHAPE("POLYGON((109.35 18.3, 109.45 18.3, 109.45 18.4, 109.35 18.4, 109.35 18.3))"))
| KEEP abbrev, airport, region, city, city_location
		

Syntax

×

Parameters

geomA

Expression of type geo_point, cartesian_point, geo_shape or cartesian_shape. If null, the function returns null.

geomB

Expression of type geo_point, cartesian_point, geo_shape or cartesian_shape. If null, the function returns null. The second parameter must also have the same coordinate system as the first. This means it is not possible to combine geo_* and cartesian_* parameters.

Description

Returns whether the first geometry is within the second geometry. This is the inverse of the ST_CONTAINS function.

Supported types

Example

FROM airport_city_boundaries
| WHERE ST_WITHIN(city_boundary, TO_GEOSHAPE("POLYGON((109.1 18.15, 109.6 18.15, 109.6 18.65, 109.1 18.65, 109.1 18.15))"))
| KEEP abbrev, airport, region, city, city_location
		

Syntax

×

Parameters

point

Expression of type geo_point or cartesian_point. If null, the function returns null.

Description

Extracts the x coordinate from the supplied point. If the points is of type geo_point this is equivalent to extracting the longitude value.

Supported types

Example

ROW point = TO_GEOPOINT("POINT(42.97109629958868 14.7552534006536)")
| EVAL x =  ST_X(point), y = ST_Y(point)
		

Syntax

×

Parameters

point

Expression of type geo_point or cartesian_point. If null, the function returns null.

Description

Extracts the y coordinate from the supplied point. If the points is of type geo_point this is equivalent to extracting the latitude value.

Supported types

Example

ROW point = TO_GEOPOINT("POINT(42.97109629958868 14.7552534006536)")
| EVAL x =  ST_X(point), y = ST_Y(point)
		

Serverless Preview Stack Preview

Syntax

×

Parameters

geometry

Expression of type geo_point, geo_shape, cartesian_point or cartesian_shape. If null, the function returns null.

Description

Determines the minimum bounding box of the supplied geometry.

Supported types

Example

FROM airport_city_boundaries
| WHERE abbrev == "CPH"
| EVAL envelope = ST_ENVELOPE(city_boundary)
| KEEP abbrev, airport, envelope
		

Serverless Preview Stack Preview

Syntax

×

Parameters

point

Expression of type geo_point, geo_shape, cartesian_point or cartesian_shape. If null, the function returns null.

Description

Extracts the maximum value of the x coordinates from the supplied geometry. If the geometry is of type geo_point or geo_shape this is equivalent to extracting the maximum longitude value.

Supported types

Example

FROM airport_city_boundaries
| WHERE abbrev == "CPH"
| EVAL envelope = ST_ENVELOPE(city_boundary)
| EVAL xmin = ST_XMIN(envelope), xmax = ST_XMAX(envelope), ymin = ST_YMIN(envelope), ymax = ST_YMAX(envelope)
| KEEP abbrev, airport, xmin, xmax, ymin, ymax
		

Serverless Preview Stack Preview

Syntax

×

Parameters

point

Expression of type geo_point, geo_shape, cartesian_point or cartesian_shape. If null, the function returns null.

Description

Extracts the minimum value of the x coordinates from the supplied geometry. If the geometry is of type geo_point or geo_shape this is equivalent to extracting the minimum longitude value.

Supported types

Example

FROM airport_city_boundaries
| WHERE abbrev == "CPH"
| EVAL envelope = ST_ENVELOPE(city_boundary)
| EVAL xmin = ST_XMIN(envelope), xmax = ST_XMAX(envelope), ymin = ST_YMIN(envelope), ymax = ST_YMAX(envelope)
| KEEP abbrev, airport, xmin, xmax, ymin, ymax
		

Serverless Preview Stack Preview

Syntax

×

Parameters

point

Expression of type geo_point, geo_shape, cartesian_point or cartesian_shape. If null, the function returns null.

Description

Extracts the maximum value of the y coordinates from the supplied geometry. If the geometry is of type geo_point or geo_shape this is equivalent to extracting the maximum latitude value.

Supported types

Example

FROM airport_city_boundaries
| WHERE abbrev == "CPH"
| EVAL envelope = ST_ENVELOPE(city_boundary)
| EVAL xmin = ST_XMIN(envelope), xmax = ST_XMAX(envelope), ymin = ST_YMIN(envelope), ymax = ST_YMAX(envelope)
| KEEP abbrev, airport, xmin, xmax, ymin, ymax
		

Serverless Preview Stack Preview

Syntax

×

Parameters

point

Expression of type geo_point, geo_shape, cartesian_point or cartesian_shape. If null, the function returns null.

Description

Extracts the minimum value of the y coordinates from the supplied geometry. If the geometry is of type geo_point or geo_shape this is equivalent to extracting the minimum latitude value.

Supported types

Example

FROM airport_city_boundaries
| WHERE abbrev == "CPH"
| EVAL envelope = ST_ENVELOPE(city_boundary)
| EVAL xmin = ST_XMIN(envelope), xmax = ST_XMAX(envelope), ymin = ST_YMIN(envelope), ymax = ST_YMAX(envelope)
| KEEP abbrev, airport, xmin, xmax, ymin, ymax
		

Serverless Preview Stack Preview

Syntax

×

Parameters

geometry

Expression of type geo_point. If null, the function returns null.

precision

Expression of type integer. If null, the function returns null. Valid values are between 0 and 29.

bounds

Optional bounds to filter the grid tiles, a geo_shape of type BBOX. Use ST_ENVELOPE if the geo_shape is of any other type.

Description

Calculates the geotile of the supplied geo_point at the specified precision. The result is long encoded. Use TO_STRING to convert the result to a string, TO_LONG to convert it to a long, or TO_GEOSHAPE to calculate the geo_shape bounding geometry. These functions are related to the geo_grid query and the geotile_grid aggregation.

Supported types

Example

FROM airports
| EVAL geotile = ST_GEOTILE(location, 2)
| STATS
    count = COUNT(geotile),
    centroid = ST_CENTROID_AGG(location)
      BY geotile
| EVAL geotileString = TO_STRING(geotile)
| SORT count DESC, geotileString ASC
| KEEP count, centroid, geotileString
		

Serverless Preview Stack Preview

Syntax

×

Parameters

geometry

Expression of type geo_point. If null, the function returns null.

precision

Expression of type integer. If null, the function returns null. Valid values are between 0 and 15.

bounds

Optional bounds to filter the grid tiles, a geo_shape of type BBOX. Use ST_ENVELOPE if the geo_shape is of any other type.

Description

Calculates the geohex, the H3 cell-id, of the supplied geo_point at the specified precision. The result is long encoded. Use TO_STRING to convert the result to a string, TO_LONG to convert it to a long, or TO_GEOSHAPE to calculate the geo_shape bounding geometry. These functions are related to the geo_grid query and the geohex_grid aggregation.

Supported types

Example

FROM airports
| EVAL geohex = ST_GEOHEX(location, 1)
| STATS
    count = COUNT(geohex),
    centroid = ST_CENTROID_AGG(location)
      BY geohex
| WHERE count >= 10
| EVAL geohexString = TO_STRING(geohex)
| KEEP count, centroid, geohexString
| SORT count DESC, geohexString ASC
		

Serverless Preview Stack Preview

Syntax

×

Parameters

geometry

Expression of type geo_point. If null, the function returns null.

precision

Expression of type integer. If null, the function returns null. Valid values are between 1 and 12.

bounds

Optional bounds to filter the grid tiles, a geo_shape of type BBOX. Use ST_ENVELOPE if the geo_shape is of any other type.

Description

Calculates the geohash of the supplied geo_point at the specified precision. The result is long encoded. Use TO_STRING to convert the result to a string, TO_LONG to convert it to a long, or TO_GEOSHAPE to calculate the geo_shape bounding geometry. These functions are related to the geo_grid query and the geohash_grid aggregation.

Supported types

Example

FROM airports
| EVAL geohash = ST_GEOHASH(location, 1)
| STATS
    count = COUNT(geohash),
    centroid = ST_CENTROID_AGG(location)
      BY geohash
| WHERE count >= 10
| EVAL geohashString = TO_STRING(geohash)
| KEEP count, centroid, geohashString
| SORT count DESC, geohashString ASC