Geoshape query

A geo_shape query finds documents whose geo_shape or geo_point field relates to a shape you provide. The same relation names work on cartesian fields; query those with xy_shape as shown on the xy query page.

Relations expanded in 0.13.0

Spatial relations

Set relation to one of the following. The default is intersects. Names are case-insensitive.

Relation	Matches when
intersects	The document and the query share any point. The default.
disjoint	The document and the query share no points.
within	The document lies entirely inside the query, including its boundary.
contains	The document's interior fully encloses the query.
covers	The query lies entirely on the document, including a shared edge. Identical polygons match.
covered_by	The document lies entirely on the query, including a shared edge.
equals	The document and the query occupy the same points.
st_contains	The query lies inside the document and their interiors meet. Shared edges match. Identical polygons match.
st_within	The document lies inside the query and their interiors meet. Shared edges match.
st_touches	The document and the query meet along their boundaries.
st_overlaps	The interiors meet and neither shape contains the other.
st_crosses	A line in the index passes through an area in the query.

geo_point fields support intersects. Shape fields support every relation in the table.

Which relation to use

You want	Use
Any overlap	intersects
The same geometry as the query shape	equals
Documents that contain the query shape, including a shared edge and an identical polygon	covers or st_contains
Documents that meet the query shape along the boundary	st_touches
Documents inside the query shape	covered_by or st_within

contains matches when the document's interior fully encloses the query. covers and st_contains also match a shared boundary and an identical polygon.

Query shapes with area

st_contains, st_within, st_touches, st_overlaps, st_crosses, covers, covered_by, and equals need a query shape with area — a polygon or an envelope. For a point or line query, use intersects, disjoint, within, or contains, as appropriate.

st_crosses is a line in the index against an area in the query.

Example

Create an index with a geo_shape field and index a square:

PUT parcels
{
  "mappings": {
    "properties": {
      "location": { "type": "geo_shape" }
    }
  }
}

PUT parcels/_doc/1
{
  "location": {
    "type": "polygon",
    "coordinates": [[
      [0, 0], [10, 0], [10, 10], [0, 10], [0, 0]
    ]]
  }
}

Find the parcel that is this square (equals):

GET parcels/_search
{
  "query": {
    "geo_shape": {
      "location": {
        "shape": {
          "type": "polygon",
          "coordinates": [[
            [0, 0], [10, 0], [10, 10], [0, 10], [0, 0]
          ]]
        },
        "relation": "equals"
      }
    }
  }
}

Find documents that contain this square, including the square itself (st_contains or covers):

GET parcels/_search
{
  "query": {
    "geo_shape": {
      "location": {
        "shape": {
          "type": "polygon",
          "coordinates": [[
            [0, 0], [10, 0], [10, 10], [0, 10], [0, 0]
          ]]
        },
        "relation": "st_contains"
      }
    }
  }
}

Find documents that meet this neighbouring square along the boundary:

GET parcels/_search
{
  "query": {
    "geo_shape": {
      "location": {
        "shape": {
          "type": "polygon",
          "coordinates": [[
            [10, 0], [20, 0], [20, 10], [10, 10], [10, 0]
          ]]
        },
        "relation": "st_touches"
      }
    }
  }
}

On an xy_shape field, use the xy_shape query with the same relation names. See xy query.

You can also name a shape already stored in another index with indexed_shape. See Using a pre-indexed shape on the xy query page; geo_shape accepts the same indexed_shape object.

Related

• Geoshape field type — mapping and formats.
• xy query — the same relations on cartesian fields.
• Spatial join relations — the same names on a Spark join.