--- title: Envelope Query pubDate: 2026-08-17T09:53:44.266Z antora: editUrl: https://github.com/couchbase/docs-server/edit/release/7.2/modules/fts/pages/fts-queryshape-envelope.adoc xref: xref:7.2@server:fts:fts-queryshape-envelope.adoc[] --- [Consult the llms.txt file for a full list of contents](/llms.txt) [View original HTML](/server/7.2/fts/fts-queryshape-envelope.html) # Envelope Query > A GeoJSON Envelope Query against any GeoJSON type. ## [](#queryshape-for-an-envelope-query)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)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 { "query": { "field": "<>", "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)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 { "query": { "field": "<>", "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)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 { "query": { "field": "<>", "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)Example Envelope Query (against Points) > [!NOTE] > It is assumed that you your cluster has 1) a modified [travel-sample with GeoJSON data](fts-supported-queries-geojson-spatial.md#prerequisites-dataset) and 2) a Search index as per [Creating a GeoJSON Index via the REST API](fts-creating-index-from-REST-geojson.md) 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 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 { "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)Example Envelope Query (against Circles) > [!NOTE] > It is assumed that you your cluster has 1) a modified [travel-sample with GeoJSON data](fts-supported-queries-geojson-spatial.md#prerequisites-dataset) and 2) a Search index as per [Creating a GeoJSON Index via the REST API](fts-creating-index-from-REST-geojson.md) prior to running this example. Matches if the area of the query rectangle overlaps the document circle. 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 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 { "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 } ```