Link Search Menu Expand Document Documentation Menu

You're viewing version 2.16 of the OpenSearch documentation. This version is no longer maintained. For the latest version, see the current documentation. For information about OpenSearch version maintenance, see Release Schedule and Maintenance Policy.

xy query

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

Spatial relations

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

Relation Description Supporting xy field type
INTERSECTS (Default) Matches documents whose xy point or xy shape intersects the shape provided in the query. xy_point, xy_shape
DISJOINT Matches documents whose xy shape does not intersect with the shape provided in the query. xy_shape
WITHIN Matches documents whose xy shape is completely within the shape provided in the query. xy_shape
CONTAINS Matches documents whose xy shape completely contains the shape provided in the query. xy_shape

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 how to search for documents containing 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.

xy shape query

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
        }
      }
    }
  }
}

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.

xy point query

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"
        }
      }
    ]
  }
}
350 characters left

Have a question? .

Want to contribute? or .