IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.
Elasticsearch Guide [7.7] » Query DSL » Geo queries » Geo-shape query
« Geo-polygon query Shape queries »

Geo-shape queryedit

Filter documents indexed using the geo_shape or geo_point type.

Requires the geo_shape Mapping or the geo_point Mapping.

The geo_shape query uses the same grid square representation as the geo_shape mapping to find documents that have a shape that intersects with the query shape. It will also use the same Prefix Tree configuration as defined for the field mapping.

The query supports two ways of defining the query shape, either by providing a whole shape definition, or by referencing the name of a shape pre-indexed in another index. Both formats are defined below with examples.

Inline Shape Definitionedit

Similar to the geo_shape type, the geo_shape query uses GeoJSON to represent shapes.

Given the following index with locations as geo_shape fields:

PUT /example
{
    "mappings": {
        "properties": {
            "location": {
                "type": "geo_shape"
            }
        }
    }
}

POST /example/_doc?refresh
{
    "name": "Wind & Wetter, Berlin, Germany",
    "location": {
        "type": "point",
        "coordinates": [13.400544, 52.530286]
    }
}

The following query will find the point using Elasticsearch’s envelope GeoJSON extension:

GET /example/_search
{
    "query":{
        "bool": {
            "must": {
                "match_all": {}
            },
            "filter": {
                "geo_shape": {
                    "location": {
                        "shape": {
                            "type": "envelope",
                            "coordinates" : [[13.0, 53.0], [14.0, 52.0]]
                        },
                        "relation": "within"
                    }
                }
            }
        }
    }
}

The above query can, similarly, be queried on geo_point fields.

PUT /example_points
{
    "mappings": {
        "properties": {
            "location": {
                "type": "geo_point"
            }
        }
    }
}

PUT /example_points/_doc/1?refresh
{
    "name": "Wind & Wetter, Berlin, Germany",
    "location": [13.400544, 52.530286]
}

Using the same query, the documents with matching geo_point fields are returned.

GET /example_points/_search
{
    "query":{
        "bool": {
            "must": {
                "match_all": {}
            },
            "filter": {
                "geo_shape": {
                    "location": {
                        "shape": {
                            "type": "envelope",
                            "coordinates" : [[13.0, 53.0], [14.0, 52.0]]
                        },
                        "relation": "intersects"
                    }
                }
            }
        }
    }
}
{
  "took" : 17,
  "timed_out" : false,
  "_shards" : {
    "total" : 1,
    "successful" : 1,
    "skipped" : 0,
    "failed" : 0
  },
  "hits" : {
    "total" : {
      "value" : 1,
      "relation" : "eq"
    },
    "max_score" : 1.0,
    "hits" : [
      {
        "_index" : "example_points",
        "_type" : "_doc",
        "_id" : "1",
        "_score" : 1.0,
        "_source" : {
          "name": "Wind & Wetter, Berlin, Germany",
          "location": [13.400544, 52.530286]
        }
      }
    ]
  }
}

Pre-Indexed Shapeedit

The query also supports using a shape which has already been indexed in another index. This is particularly useful for when you have a pre-defined list of shapes and you want to reference the list using a logical name (for example New Zealand) rather than having to provide coordinates each time. In this situation, it is only necessary to provide:

  • id - The ID of the document that containing the pre-indexed shape.
  • index - Name of the index where the pre-indexed shape is. Defaults to shapes.
  • path - The field specified as path containing the pre-indexed shape. Defaults to shape.
  • routing - The routing of the shape document if required.

The following is an example of using the Filter with a pre-indexed shape:

PUT /shapes
{
    "mappings": {
        "properties": {
            "location": {
                "type": "geo_shape"
            }
        }
    }
}

PUT /shapes/_doc/deu
{
    "location": {
        "type": "envelope",
        "coordinates" : [[13.0, 53.0], [14.0, 52.0]]
    }
}

GET /example/_search
{
    "query": {
        "bool": {
            "filter": {
                "geo_shape": {
                    "location": {
                        "indexed_shape": {
                            "index": "shapes",
                            "id": "deu",
                            "path": "location"
                        }
                    }
                }
            }
        }
    }
}

Spatial Relationsedit

The geo_shape strategy mapping parameter determines which spatial relation operators may be used at search time.

The following is a complete list of spatial relation operators available when searching a field of type geo_shape:

  • INTERSECTS - (default) Return all documents whose geo_shape field intersects the query geometry.
  • DISJOINT - Return all documents whose geo_shape field has nothing in common with the query geometry.
  • WITHIN - Return all documents whose geo_shape field is within the query geometry.
  • CONTAINS - Return all documents whose geo_shape field contains the query geometry.

When searching a field of type geo_point there is a single supported spatial relation operator:

  • INTERSECTS - (default) Return all documents whose geo_point field intersects the query geometry.

Ignore Unmappededit

When set to true the ignore_unmapped option will ignore an unmapped field and will not match any documents for this query. This can be useful when querying multiple indexes which might have different mappings. When set to false (the default value) the query will throw an exception if the field is not mapped.

Shape Types supported for Geo-Pointedit

When searching a field of type geo_point the following shape types are not supported:

  • POINT
  • LINE
  • MULTIPOINT
  • MULTILINE

Notesedit

  • Geo-shape queries on geo-shapes implemented with PrefixTrees will not be executed if search.allow_expensive_queries is set to false.
  • When data is indexed in a geo_shape field as an array of shapes, the arrays are treated as one shape. For this reason, the following requests are equivalent. 
PUT /test/_doc/1
{
  "location": [
    {
      "coordinates": [46.25,20.14],
      "type": "point"
    },
    {
      "coordinates": [47.49,19.04],
      "type": "point"
    }
  ]
}
PUT /test/_doc/1
{
  "location":
    {
      "coordinates": [[46.25,20.14],[47.49,19.04]],
      "type": "multipoint"
    }
}
« Geo-polygon query Shape queries »