Version: 0.13.0

xy query

To search for documents that contain xy point and xy shape fields, use an xy query.

Spatial relations

When you provide an xy shape to the xy query, the xy fields are matched using the following spatial relations to the provided shape.

Relation	Description	Supporting xy Field Type
`intersects`	(Default) The document and the query share any point.	`xy_point`, `xy_shape`
`disjoint`	The document and the query share no points.	`xy_shape`
`within`	The document lies entirely inside the query, including its boundary.	`xy_shape`
`contains`	The document's interior fully encloses the query.	`xy_shape`
`covers`	The query lies entirely on the document, including a shared edge.	`xy_shape`
`covered_by`	The document lies entirely on the query, including a shared edge.	`xy_shape`
`equals`	The document and the query cover the same points.	`xy_shape`
`st_contains`	The query lies inside the document and their interiors meet.	`xy_shape`
`st_within`	The document lies inside the query and their interiors meet.	`xy_shape`
`st_touches`	They meet only along their boundaries.	`xy_shape`
`st_overlaps`	The interiors meet and neither shape contains the other.	`xy_shape`
`st_crosses`	A line in the index passes through an area in the query.	`xy_shape`

Names are case-insensitive. For when to use each relation, see Geoshape query. covers, st_contains, st_touches, and the other 0.13.0 relations need a query shape with area (a polygon or envelope).

The following examples illustrate searching for documents that contain xy shapes. To learn how to search for documents that contain xy points, see the Querying xy points section.

Defining the shape in an xy query

You can define the shape in an xy query either by providing a new shape definition at query time or by referencing the name of a shape pre-indexed in another index.

Using a new shape definition

To provide a new shape to an xy query, define it in the xy_shape field.

The following example illustrates searching for documents with xy shapes that match an xy shape defined at query time.

First, create an index and map the geometry field as an xy_shape:

PUT testindex
{
  "mappings": {
    "properties": {
      "geometry": {
        "type": "xy_shape"
      }
    }
  }
}

Index a document with a point and a document with a polygon:

PUT testindex/_doc/1
{
  "geometry": { 
    "type": "point",
    "coordinates": [0.5, 3.0]
  }
}

PUT testindex/_doc/2
{
  "geometry" : {
    "type" : "polygon",
    "coordinates" : [
      [[2.5, 6.0],
      [0.5, 4.5], 
      [1.5, 2.0], 
      [3.5, 3.5],
      [2.5, 6.0]]
    ]
  }
}

Define an envelope—a bounding rectangle in the [[minX, maxY], [maxX, minY]] format. Search for documents with xy points or shapes that intersect that envelope:

GET testindex/_search
{
  "query": {
    "xy_shape": {
      "geometry": {
        "shape": {
          "type": "envelope",
          "coordinates": [ [ 0.0, 6.0], [ 4.0, 2.0] ]
        },
        "relation": "WITHIN"
      }
    }
  }
}

The following image depicts the example. Both the point and the polygon are within the bounding envelope.

The response contains both documents:

{
  "took" : 363,
  "timed_out" : false,
  "_shards" : {
    "total" : 1,
    "successful" : 1,
    "skipped" : 0,
    "failed" : 0
  },
  "hits" : {
    "total" : {
      "value" : 2,
      "relation" : "eq"
    },
    "max_score" : 0.0,
    "hits" : [
      {
        "_index" : "testindex",
        "_id" : "1",
        "_score" : 0.0,
        "_source" : {
          "geometry" : {
            "type" : "point",
            "coordinates" : [
              0.5,
              3.0
            ]
          }
        }
      },
      {
        "_index" : "testindex",
        "_id" : "2",
        "_score" : 0.0,
        "_source" : {
          "geometry" : {
            "type" : "polygon",
            "coordinates" : [
              [
                [
                  2.5,
                  6.0
                ],
                [
                  0.5,
                  4.5
                ],
                [
                  1.5,
                  2.0
                ],
                [
                  3.5,
                  3.5
                ],
                [
                  2.5,
                  6.0
                ]
              ]
            ]
          }
        }
      }
    ]
  }
}

Using a pre-indexed shape definition

When constructing an xy query, you can also reference the name of a shape pre-indexed in another index. Using this method, you can define an xy shape at index time and refer to it by name, providing the following parameters in the indexed_shape object.

Parameter	Description
`index`	The name of the index that contains the pre-indexed shape.
`id`	The document ID of the document that contains the pre-indexed shape.
`path`	The field name of the field that contains the pre-indexed shape as a path.

The following example illustrates referencing the name of a shape pre-indexed in another index. In this example, the index pre-indexed-shapes contains the shape that defines the boundaries, and the index testindex contains the shapes whose locations are checked against those boundaries.

First, create an index pre-indexed-shapes and map the geometry field for this index as an xy_shape:

PUT pre-indexed-shapes
{
  "mappings": {
    "properties": {
      "geometry": {
        "type": "xy_shape"
      }
    }
  }
}

Index an envelope that specifies the boundaries and name it rectangle:

PUT pre-indexed-shapes/_doc/rectangle
{
  "geometry": {
    "type": "envelope",
    "coordinates" : [ [ 0.0, 6.0], [ 4.0, 2.0] ]
  }
}

Index a document with a point and a document with a polygon into the index testindex:

PUT testindex/_doc/1
{
  "geometry": { 
    "type": "point",
    "coordinates": [0.5, 3.0]
  }
}

PUT testindex/_doc/2
{
  "geometry" : {
    "type" : "polygon",
    "coordinates" : [
      [[2.5, 6.0],
      [0.5, 4.5], 
      [1.5, 2.0], 
      [3.5, 3.5],
      [2.5, 6.0]]
    ]
  }
}

Search for documents with shapes that intersect rectangle in the index testindex using a filter:

GET testindex/_search
{
  "query": {
    "bool": {
      "filter": {
        "xy_shape": {
          "geometry": {
            "indexed_shape": {
              "index": "pre-indexed-shapes",
              "id": "rectangle",
              "path": "geometry"
            }
          }
        }
      }
    }
  }
}

The preceding query uses the default spatial relation INTERSECTS and returns both the point and the polygon:

{
  "took" : 26,
  "timed_out" : false,
  "_shards" : {
    "total" : 1,
    "successful" : 1,
    "skipped" : 0,
    "failed" : 0
  },
  "hits" : {
    "total" : {
      "value" : 2,
      "relation" : "eq"
    },
    "max_score" : 0.0,
    "hits" : [
      {
        "_index" : "testindex",
        "_id" : "1",
        "_score" : 0.0,
        "_source" : {
          "geometry" : {
            "type" : "point",
            "coordinates" : [
              0.5,
              3.0
            ]
          }
        }
      },
      {
        "_index" : "testindex",
        "_id" : "2",
        "_score" : 0.0,
        "_source" : {
          "geometry" : {
            "type" : "polygon",
            "coordinates" : [
              [
                [
                  2.5,
                  6.0
                ],
                [
                  0.5,
                  4.5
                ],
                [
                  1.5,
                  2.0
                ],
                [
                  3.5,
                  3.5
                ],
                [
                  2.5,
                  6.0
                ]
              ]
            ]
          }
        }
      }
    ]
  }
}

Querying xy points

You can also use an xy query to search for documents that contain xy points.

Create a mapping with point as xy_point:

PUT testindex1
{
  "mappings": {
    "properties": {
      "point": {
        "type": "xy_point"
      }
    }
  }
}

Index three points:

PUT testindex1/_doc/1
{
  "point": "1.0, 1.0" 
}

PUT testindex1/_doc/2
{
  "point": "2.0, 0.0" 
}

PUT testindex1/_doc/3
{
  "point": "-2.0, 2.0" 
}

Search for points that lie within the circle with the center at (0, 0) and a radius of 2:

GET testindex1/_search
{
  "query": {
    "xy_shape": {
      "point": {
        "shape": {
          "type": "circle",
          "coordinates": [0.0, 0.0],
          "radius": 2
        }
      }
    }
  }
}

note

xy point only supports the default INTERSECTS spatial relation, so you don't need to provide the relation parameter.

The following image depicts the example. Points 1 and 2 are within the circle, and point 3 is outside the circle.

The response returns documents 1 and 2:

{
  "took" : 575,
  "timed_out" : false,
  "_shards" : {
    "total" : 1,
    "successful" : 1,
    "skipped" : 0,
    "failed" : 0
  },
  "hits" : {
    "total" : {
      "value" : 2,
      "relation" : "eq"
    },
    "max_score" : 0.0,
    "hits" : [
      {
        "_index" : "testindex1",
        "_id" : "1",
        "_score" : 0.0,
        "_source" : {
          "point" : "1.0, 1.0"
        }
      },
      {
        "_index" : "testindex1",
        "_id" : "2",
        "_score" : 0.0,
        "_source" : {
          "point" : "2.0, 0.0"
        }
      }
    ]
  }
}

Spatial relations​

Defining the shape in an xy query​

Using a new shape definition​

Using a pre-indexed shape definition​

Querying xy points​

Spatial relations

Defining the shape in an xy query

Using a new shape definition

Using a pre-indexed shape definition

Querying xy points