Shape query

Shape query

Queries documents that contain fields indexed using the shape type.

Requires the shape Mapping.

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

Inline Shape Definition

Similar to the geo_shape query, the shape query uses GeoJSON or Well Known Text (WKT) to represent shapes.

Given the following index:

  1. resp = client.indices.create(
  2.     index="example",
  3.     mappings={
  4.         "properties": {
  5.             "geometry": {
  6.                 "type": "shape"
  7.             }
  8.         }
  9.     },
  10. )
  11. print(resp)
  13. resp1 = client.index(
  14.     index="example",
  15.     id="1",
  16.     refresh="wait_for",
  17.     document={
  18.         "name": "Lucky Landing",
  19.         "geometry": {
  20.             "type": "point",
  21.             "coordinates": [
  22.                 1355.400544,
  23.                 5255.530286
  24.             ]
  25.         }
  26.     },
  27. )
  28. print(resp1)
  1. response = client.indices.create(
  2.   index: 'example',
  3.   body: {
  4.     mappings: {
  5.       properties: {
  6.         geometry: {
  7.           type: 'shape'
  8.         }
  9.       }
  10.     }
  11.   }
  12. )
  13. puts response
  15. response = client.index(
  16.   index: 'example',
  17.   id: 1,
  18.   refresh: 'wait_for',
  19.   body: {
  20.     name: 'Lucky Landing',
  21.     geometry: {
  22.       type: 'point',
  23.       coordinates: [
  24.         1355.400544,
  25.         5255.530286
  26.       ]
  27.     }
  28.   }
  29. )
  30. puts response
  1. const response = await client.indices.create({
  2.   index: "example",
  3.   mappings: {
  4.     properties: {
  5.       geometry: {
  6.         type: "shape",
  7.       },
  8.     },
  9.   },
  10. });
  11. console.log(response);
  13. const response1 = await client.index({
  14.   index: "example",
  15.   id: 1,
  16.   refresh: "wait_for",
  17.   document: {
  18.     name: "Lucky Landing",
  19.     geometry: {
  20.       type: "point",
  21.       coordinates: [1355.400544, 5255.530286],
  22.     },
  23.   },
  24. });
  25. console.log(response1);
  1. PUT /example
  2. {
  3.   "mappings": {
  4.     "properties": {
  5.       "geometry": {
  6.         "type": "shape"
  7.       }
  8.     }
  9.   }
  10. }
  12. PUT /example/_doc/1?refresh=wait_for
  13. {
  14.   "name": "Lucky Landing",
  15.   "geometry": {
  16.     "type": "point",
  17.     "coordinates": [ 1355.400544, 5255.530286 ]
  18.   }
  19. }

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

  1. resp = client.search(
  2.     index="example",
  3.     query={
  4.         "shape": {
  5.             "geometry": {
  6.                 "shape": {
  7.                     "type": "envelope",
  8.                     "coordinates": [
  9.                         [
  10.                             1355,
  11.                             5355
  12.                         ],
  13.                         [
  14.                             1400,
  15.                             5200
  16.                         ]
  17.                     ]
  18.                 },
  19.                 "relation": "within"
  20.             }
  21.         }
  22.     },
  23. )
  24. print(resp)
  1. const response = await client.search({
  2.   index: "example",
  3.   query: {
  4.     shape: {
  5.       geometry: {
  6.         shape: {
  7.           type: "envelope",
  8.           coordinates: [
  9.             [1355, 5355],
  10.             [1400, 5200],
  11.           ],
  12.         },
  13.         relation: "within",
  14.       },
  15.     },
  16.   },
  17. });
  18. console.log(response);
  1. GET /example/_search
  2. {
  3.   "query": {
  4.     "shape": {
  5.       "geometry": {
  6.         "shape": {
  7.           "type": "envelope",
  8.           "coordinates": [ [ 1355.0, 5355.0 ], [ 1400.0, 5200.0 ] ]
  9.         },
  10.         "relation": "within"
  11.       }
  12.     }
  13.   }
  14. }

Pre-Indexed Shape

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 which are useful to your application and you want to reference this using a logical name (for example New Zealand) rather than having to provide their 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:

  1. resp = client.indices.create(
  2.     index="shapes",
  3.     mappings={
  4.         "properties": {
  5.             "geometry": {
  6.                 "type": "shape"
  7.             }
  8.         }
  9.     },
  10. )
  11. print(resp)
  13. resp1 = client.index(
  14.     index="shapes",
  15.     id="footprint",
  16.     document={
  17.         "geometry": {
  18.             "type": "envelope",
  19.             "coordinates": [
  20.                 [
  21.                     1355,
  22.                     5355
  23.                 ],
  24.                 [
  25.                     1400,
  26.                     5200
  27.                 ]
  28.             ]
  29.         }
  30.     },
  31. )
  32. print(resp1)
  34. resp2 = client.search(
  35.     index="example",
  36.     query={
  37.         "shape": {
  38.             "geometry": {
  39.                 "indexed_shape": {
  40.                     "index": "shapes",
  41.                     "id": "footprint",
  42.                     "path": "geometry"
  43.                 }
  44.             }
  45.         }
  46.     },
  47. )
  48. print(resp2)
  1. response = client.indices.create(
  2.   index: 'shapes',
  3.   body: {
  4.     mappings: {
  5.       properties: {
  6.         geometry: {
  7.           type: 'shape'
  8.         }
  9.       }
  10.     }
  11.   }
  12. )
  13. puts response
  15. response = client.index(
  16.   index: 'shapes',
  17.   id: 'footprint',
  18.   body: {
  19.     geometry: {
  20.       type: 'envelope',
  21.       coordinates: [
  22.         [
  23.           1355,
  24.           5355
  25.         ],
  26.         [
  27.           1400,
  28.           5200
  29.         ]
  30.       ]
  31.     }
  32.   }
  33. )
  34. puts response
  36. response = client.search(
  37.   index: 'example',
  38.   body: {
  39.     query: {
  40.       shape: {
  41.         geometry: {
  42.           indexed_shape: {
  43.             index: 'shapes',
  44.             id: 'footprint',
  45.             path: 'geometry'
  46.           }
  47.         }
  48.       }
  49.     }
  50.   }
  51. )
  52. puts response
  1. const response = await client.indices.create({
  2.   index: "shapes",
  3.   mappings: {
  4.     properties: {
  5.       geometry: {
  6.         type: "shape",
  7.       },
  8.     },
  9.   },
  10. });
  11. console.log(response);
  13. const response1 = await client.index({
  14.   index: "shapes",
  15.   id: "footprint",
  16.   document: {
  17.     geometry: {
  18.       type: "envelope",
  19.       coordinates: [
  20.         [1355, 5355],
  21.         [1400, 5200],
  22.       ],
  23.     },
  24.   },
  25. });
  26. console.log(response1);
  28. const response2 = await client.search({
  29.   index: "example",
  30.   query: {
  31.     shape: {
  32.       geometry: {
  33.         indexed_shape: {
  34.           index: "shapes",
  35.           id: "footprint",
  36.           path: "geometry",
  37.         },
  38.       },
  39.     },
  40.   },
  41. });
  42. console.log(response2);
  1. PUT /shapes
  2. {
  3.   "mappings": {
  4.     "properties": {
  5.       "geometry": {
  6.         "type": "shape"
  7.       }
  8.     }
  9.   }
  10. }
  12. PUT /shapes/_doc/footprint
  13. {
  14.   "geometry": {
  15.     "type": "envelope",
  16.     "coordinates": [ [ 1355.0, 5355.0 ], [ 1400.0, 5200.0 ] ]
  17.   }
  18. }
  20. GET /example/_search
  21. {
  22.   "query": {
  23.     "shape": {
  24.       "geometry": {
  25.         "indexed_shape": {
  26.           "index": "shapes",
  27.           "id": "footprint",
  28.           "path": "geometry"
  29.         }
  30.       }
  31.     }
  32.   }
  33. }

Spatial Relations

The following is a complete list of spatial relation operators available:

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

Ignore Unmapped

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.