Envelope Query

March 23, 2025

+ 12

A GeoJSON Envelope Query against any GeoJSON type.

QueryShape for an Envelope Query

A GeoJSON query via a GeoShape of Envelope to find GeoJSON types in a Search index using the 3 relations intersects, contains, and within.

Also called a bounded rectangle query by specifying [[minLon, maxLat], [maxLon, minLat]]. This is a Couchbase extension to GeoJSON.

Envelope `Intersects` Query

An intersect query for the envelope returns all the matched documents with shapes that overlap with the area of the rectangle shape in the query.

A envelope intersection query sample is given below.

json
Copy
{
  "query": {
    "field": "<<fieldName>>",
    "geometry": {
      "shape": {
        "type": "Envelope",
        "coordinates": [
          [-2.235143, 53.482358],
          [28.955043, 40.991862]
        ]
      },
      "relation": "intersects"
    }
  }
}

Intersection rules for the Envelope Query with other indexed GeoJSON shapes in the document set are given below.

Intersects (relation)
Document Shape

Envelope (GeoShape)

Point

Matches if the point lies within the query rectangle region.

LineString

Matches if the linestring intersects or lies within the query rectangle.

Polygon

Matches if the polygon area is overlapping the query rectangle.

MultiPoint

Matches if any of the points in the array lie within the rectangle region.

MultiLineString

Matches if any of the linestrings intersect or lie within the rectangle area.

MultiPolygon

Matches if any of the polygon areas is overlapping the rectangle region.

GeometryCollection

Matches if there is an overlap between any heterogeneous (above 6) shapes in the geometrycollection array in the document and the query rectangle.

Circle

Matches if the area of the query rectangle overlaps the document circle.

Envelope

Matches if the query rectangle overlaps the document rectangle area.

Envelope `Contains` Query

A contains query for the envelope returns all the matched documents with shapes that contain the area of the rectangle shape in the query.

A envelope contains query sample is given below.

json
Copy
{
  "query": {
    "field": "<<fieldName>>",
    "geometry": {
      "shape": {
        "type": "Polygon",
        "coordinates": [
          [-2.235143, 53.482358],
          [28.955043, 40.991862]
        ]
      },
      "relation": "contains"
    }
  }
}

Containment rules for the Envelope Query with other indexed GeoJSON shapes in the document set are given below.

Contains (relation)
Document Shape

Envelope (GeoShape)

Point

NA, Point can’t contain an envelope.

LineString

NA, LineString can’t contain an envelope.

Polygon

Matches if the polygon area is containing the rectangle region in the query.

MultiPoint

NA, MultiPoint can’t contain an envelope.

MultiLineString

NA, MultiLineString can’t contain an envelope.

MultiPolygon

Matches if any of the polygon areas contains the entire rectangle region.

GeometryCollection

Matches if there is a containment between any heterogeneous (above 6) shapes in the geometrycollection array in the document and the query rectangle.

Circle

Matches if the query rectangle resides within the document circle.

Envelope

Matches if the query rectangle resides within the document rectangle.

Envelope `WithIn` Query

The Within query is not supported by line geometries.

A within query for the envelope returns all the matched documents with shapes that are contained within the area of the rectangle shape in the query.

A envelope contains query sample is given below.

json
Copy
{
  "query": {
    "field": "<<fieldName>>",
    "geometry": {
      "shape": {
        "type": "Polygon",
        "coordinates": [
          [-2.235143, 53.482358],
          [28.955043, 40.991862]
        ]
      },
      "relation": "within"
    }
  }
}

WithIn rules for the Envelope Query with other indexed GeoJSON shapes in the document set are given below.

Contains (relation)
Document Shape

Envelope (GeoShape)

Point

Matches if the point lies within the query rectangle region.

LineString

Matches if the linestring resides completely within the query rectangle.

Polygon

Matches if the polygon resides completely within the query rectangle.

MultiPoint

Matches if all the points in the array lie within the query rectangle.

MultiLineString

Matches if all the linestrings lie within the query rectangle area.

MultiPolygon

Matches if all the polygons reside within the query rectangle region.

GeometryCollection

Matches if there is within relation between all the heterogeneous (above 6) shapes in the geometrycollection array in the document and the query rectangle.

Circle

Matches if the document circle resides within the query rectangle.

Envelope

Matches if the document rectangle resides within the query rectangle.

Example Envelope Query (against Points)

It is assumed that you your cluster has 1) a modified travel-sample with GeoJSON data and 2) a Search index as per Creating a GeoJSON Index via the REST API prior to running this example.

Matches if the point lies within the query rectangle region.

The results are specified to be sorted on name. Note type hotel and landmark have a name field and type airport has an airportname field all these values are analyzed as a keyword (exposed as name).

command
Copy
curl -s -XPOST -H "Content-Type: application/json" \
-u ${CB_USERNAME}:${CB_PASSWORD} http://${CB_HOSTNAME}:8094/api/index/test_geojson/query \
-d '{
  "query": {
    "field": "geojson",
    "geometry": {
      "shape": {
        "type": "Envelope",
        "coordinates": [
          [-2.235143, 53.482358],
          [28.955043, 40.991862]
        ]
      },
      "relation": "within"
    }
  },
  "size": 5,
  "from": 0,
  "sort": ["name"]
}' |  jq .

The output of five (5) hits (from a total of 2024 matching docs) is as follows

json
Copy
{
  "status": {
    "total": 1,
    "failed": 0,
    "successful": 1
  },
  "request": {
    "query": {
      "geometry": {
        "shape": {
          "type": "Envelope",
          "coordinates": [
            [
              -2.235143,
              53.482358
            ],
            [
              28.955043,
              40.991862
            ]
          ]
        },
        "relation": "within"
      },
      "field": "geojson"
    },
    "size": 5,
    "from": 0,
    "highlight": null,
    "fields": null,
    "facets": null,
    "explain": false,
    "sort": [
      "name"
    ],
    "includeLocations": false,
    "search_after": null,
    "search_before": null
  },
  "hits": [
    {
      "index": "test_geojson_3397081757afba65_4c1c5584",
      "id": "hotel_1364",
      "score": 0.05896334942635901,
      "sort": [
        "'La Mirande Hotel"
      ]
    },
    {
      "index": "test_geojson_3397081757afba65_4c1c5584",
      "id": "landmark_16144",
      "score": 0.004703467956838207,
      "sort": [
        "02 Shepherd's Bush Empire"
      ]
    },
    {
      "index": "test_geojson_3397081757afba65_4c1c5584",
      "id": "landmark_16181",
      "score": 0.004703467956838207,
      "sort": [
        "2 Willow Road"
      ]
    },
    {
      "index": "test_geojson_3397081757afba65_4c1c5584",
      "id": "landmark_16079",
      "score": 0.004703467956838207,
      "sort": [
        "20 Fenchurch Street"
      ]
    },
    {
      "index": "test_geojson_3397081757afba65_4c1c5584",
      "id": "landmark_40437",
      "score": 0.004703467956838207,
      "sort": [
        "30 St. Mary Axe"
      ]
    }
  ],
  "total_hits": 2024,
  "max_score": 0.12470500060351324,
  "took": 17259514,
  "facets": null
}

Example Envelope Query (against Circles)

It is assumed that you your cluster has 1) a modified travel-sample with GeoJSON data and 2) a Search index as per Creating a GeoJSON Index via the REST API prior to running this example.

Matches if the area of the query rectangle overlaps the document circle.

command
Copy
curl -s -XPOST -H "Content-Type: application/json" \
-u ${CB_USERNAME}:${CB_PASSWORD} http://${CB_HOSTNAME}:8094/api/index/test_geojson/query \
-d '{
  "query": {
    "field": "geoarea",
    "geometry": {
      "shape": {
        "type": "Envelope",
        "coordinates": [
          [-2.235143, 53.482358],
          [28.955043, 40.991862]
        ]
      },
      "relation": "intersects"
    }
  },
  "size": 5,
  "from": 0,
  "sort": ["name"]
}' |  jq .

The output of five (5) hits (from a total of 293 matching docs) is as follows

json
Copy
{
  "status": {
    "total": 1,
    "failed": 0,
    "successful": 1
  },
  "request": {
    "query": {
      "geometry": {
        "shape": {
          "type": "Envelope",
          "coordinates": [
            [
              -2.235143,
              53.482358
            ],
            [
              28.955043,
              40.991862
            ]
          ]
        },
        "relation": "intersects"
      },
      "field": "geoarea"
    },
    "size": 5,
    "from": 0,
    "highlight": null,
    "fields": null,
    "facets": null,
    "explain": false,
    "sort": [
      "name"
    ],
    "includeLocations": false,
    "search_after": null,
    "search_before": null
  },
  "hits": [
    {
      "index": "test_geojson_3397081757afba65_4c1c5584",
      "id": "airport_1372",
      "score": 0.008758192642105457,
      "sort": [
        "Abbeville"
      ]
    },
    {
      "index": "test_geojson_3397081757afba65_4c1c5584",
      "id": "airport_1294",
      "score": 0.07778849955604289,
      "sort": [
        "Aire Sur L Adour"
      ]
    },
    {
      "index": "test_geojson_3397081757afba65_4c1c5584",
      "id": "airport_1329",
      "score": 0.009493654411662942,
      "sort": [
        "Aix Les Bains"
      ]
    },
    {
      "index": "test_geojson_3397081757afba65_4c1c5584",
      "id": "airport_1347",
      "score": 0.06002598189280991,
      "sort": [
        "Aix Les Milles"
      ]
    },
    {
      "index": "test_geojson_3397081757afba65_4c1c5584",
      "id": "airport_8588",
      "score": 0.010149143194537646,
      "sort": [
        "All Airports"
      ]
    }
  ],
  "total_hits": 293,
  "max_score": 0.4253566663133814,
  "took": 13358586,
  "facets": null
}

Envelope Query

QueryShape for an Envelope Query

Envelope Intersects Query

Envelope Contains Query

Envelope WithIn Query

Example Envelope Query (against Points)

Example Envelope Query (against Circles)

Envelope `Intersects` Query

Envelope `Contains` Query

Envelope `WithIn` Query