mirror of https://github.com/elastic/elasticsearch.git synced 2025-06-28 09:28:55 -04:00

Restructure query-languages docs files for clarity (#124797 )

In a few previous PR's we restructured the ES|QL docs to make it possible to generate them dynamically.

This PR just moves a few files around to make the query languages docs easier to work with, and a little more organized like the ES|QL docs.

A bit part of this was setting up redirects to the new locations, so other repo's could correctly link to the elasticsearch docs.

2025-03-17 17:58:58 +01:00

3.6 KiB

Raw Blame History

navigation_title

mapped_pages

Shape

https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-shape-query.html

Shape query [query-dsl-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 [_inline_shape_definition_2]

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

Given the following index:

PUT /example
{
  "mappings": {
    "properties": {
      "geometry": {
        "type": "shape"
      }
    }
  }
}

PUT /example/_doc/1?refresh=wait_for
{
  "name": "Lucky Landing",
  "geometry": {
    "type": "point",
    "coordinates": [ 1355.400544, 5255.530286 ]
  }
}

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

GET /example/_search
{
  "query": {
    "shape": {
      "geometry": {
        "shape": {
          "type": "envelope",
          "coordinates": [ [ 1355.0, 5355.0 ], [ 1400.0, 5200.0 ] ]
        },
        "relation": "within"
      }
    }
  }
}

Pre-Indexed Shape [_pre_indexed_shape_2]

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:

PUT /shapes
{
  "mappings": {
    "properties": {
      "geometry": {
        "type": "shape"
      }
    }
  }
}

PUT /shapes/_doc/footprint
{
  "geometry": {
    "type": "envelope",
    "coordinates": [ [ 1355.0, 5355.0 ], [ 1400.0, 5200.0 ] ]
  }
}

GET /example/_search
{
  "query": {
    "shape": {
      "geometry": {
        "indexed_shape": {
          "index": "shapes",
          "id": "footprint",
          "path": "geometry"
        }
      }
    }
  }
}

Spatial Relations [_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 [_ignore_unmapped_5]

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.

3.6 KiB Raw Blame History Unescape Escape