--- title: Circle 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-circle.adoc xref: xref:7.2@server:fts:fts-queryshape-circle.adoc[] --- [Consult the llms.txt file for a full list of contents](/llms.txt) [View original HTML](/server/7.2/fts/fts-queryshape-circle.html) # Circle Query > A GeoJSON Circle Query against any GeoJSON type. ## [](#queryshape-for-a-circle-query)QueryShape for a Circle Query A GeoJSON query via a GeoShape of Circle to find GeoJSON types in a Search index using the 3 relations intersects, contains, and within. A Circle represents a disc shape on the earth's spherical surface. This is a Couchbase extension to GeoJSON. For full details on formats for the radius refer to [Distances](fts-supported-queries-geojson-spatial.md#specifying-distances) ### [](#circle-intersects-query)Circle `Intersects` Query An `intersect` query for the circle returns all the matched documents with shapes that overlap with the area of the circular shape in the query. A circle `intersection` query sample is given below. ```json { "query": { "field": "<>", "geometry": { "shape": { "coordinates": [ -2.235143, 53.482358 ], "type": "circle", "radius": "100mi" }, "relation": "intersects" } } } ``` Intersection rules for the Circle Query with other indexed GeoJSON shapes in the document set are given below. | Intersects (relation)Document Shape | Circle (GeoShape) | | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | Point | Intersects if the point lies within the circular region. | | LineString | Intersects if the line cuts/goes through anywhere within the circular region. | | Polygon | Intersects if there is an area overlap between the polygon and the circular region in the query. | | MultiPoint | Intersects if any of the points lie within the circular region. | | MultiLineString | Intersects if any of the lines cut/go through anywhere within the circular region. | | MultiPolygon | Intersects if there is an area overlap between any of the polygons in the multipolygon array and the circular region in the query. | | GeometryCollection | Intersects if there is an overlap between any of the heterogeneous (above 6) shapes in the geometrycollection array in the document with the query circle. | | Circle | Intersects if the area of the circle intersects with the query circle. | | Envelope | Intersects if the area of the rectangle intersects with the query circle. | ### [](#circle-contains-query)Circle `Contains` Query A `contain` query for the circle returns all the matched documents with shapes that completely contain the area of the circular shape in the query. A circle `contains` query sample is given below. ```json { "query": { "field": "<>", "geometry": { "shape": { "coordinates": [ -2.235143, 53.482358 ], "type": "circle", "radius": "100mi" }, "relation": "contains" } } } ``` Containment rules for the Circle Query with other indexed GeoJSON shapes in the document set are given below. | Contains (relation)Document Shape | Circle (GeoShape) | | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | Point | NA. Points can't cover a circle. | | LineString | NA. LineStrings can't cover a circle. | | Polygon | Matches if the polygon area contains the circular region in the query. | | MultiPoint | NA. MultiPoints can't cover a circle. | | MultiLineString | NA. MultiLineStrings can't cover a circle. | | MultiPolygon | Matches if any of the polygons in the multipolygon array contains the circular region in the query. | | GeometryCollection | Matches if there is a containment between any of the heterogeneous (above 6) shapes in the geometrycollection array in the document with the query circle. | | Circle | Matches if the area of the document circle contains the query circle. | | Envelope | Matches if the area of the document rectangle contains the query circle. | ### [](#circle-within-query)Circle `WithIn` Query The Within query is not supported by line geometries. A `within` query for the circle returns all the matched documents with shapes that are completely residing within the area of the circular shape in the query. A circle `contains` query sample is given below. ```json { "query": { "field": "<>", "geometry": { "shape": { "coordinates": [ -2.235143, 53.482358 ], "type": "circle", "radius": "100mi" }, "relation": "within" } } } ``` WithIn rules for the Circle Query with other indexed GeoJSON shapes in the document set are given below. | Contains (relation)Document Shape | Circle (GeoShape) | | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Point | Matches if the point lies within the circular region. | | LineString | Matches if the linestring lies within the circular region. | | Polygon | Matches if the polygon area is residing within the query circle. | | MultiPoint | Matches if all the points in the array lie within the circular region. | | MultiLineString | Matches if all the linestrings in the array lie within the circular region. | | MultiPolygon | Matches if every polygon area is residing completely within the circular region in the query. | | GeometryCollection | Matches if there is a complete containment between every heterogeneous (above 6) shapes in the geometrycollection array in the document and the query circle. | | Circle | Matches if the document circle resides within the query circle. | | Envelope | Matches if the document rectangle resides within the query circle. | ## [](#example-circle-query-against-points)Example Circle 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. Intersects if the point lies within the circular 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": { "geometry": { "shape": { "coordinates": [ -2.235143, 53.482358 ], "type": "circle", "radius": "100mi" }, "relation": "intersects" }, "field": "geojson" }, "size": 10, "from": 0, "sort": [ { "by": "geo_distance", "field": "geojson", "unit": "mi", "location": { "lon": -2.235143, "lat": 53.482358 } } ], "size": 5, "from": 0, "sort": ["name"] }' | jq . ``` The output of five (5) hits (from a total of 842 matching docs) is as follows ```json { "status": { "total": 1, "failed": 0, "successful": 1 }, "request": { "query": { "geometry": { "shape": { "type": "circle", "coordinates": [ -2.235143, 53.482358 ], "radiusInMeters": 160934.4 }, "relation": "intersects" }, "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_15466", "score": 0.48460386356013374, "sort": [ "8 Clarendon Crescent" ] }, { "index": "test_geojson_3397081757afba65_4c1c5584", "id": "landmark_3548", "score": 0.2153234885704102, "sort": [ "AMC" ] }, { "index": "test_geojson_3397081757afba65_4c1c5584", "id": "landmark_570", "score": 0.12120554320433605, "sort": [ "Abacus Books" ] }, { "index": "test_geojson_3397081757afba65_4c1c5584", "id": "landmark_6350", "score": 0.27197802451106445, "sort": [ "Aberconwy House" ] }, { "index": "test_geojson_3397081757afba65_4c1c5584", "id": "hotel_40", "score": 0.2929891838246811, "sort": [ "Aberdovey Hillside Village" ] } ], "total_hits": 842, "max_score": 0.5928042064997198, "took": 24655382, "facets": null } ``` ## [](#example-circle-query-against-circles)Example Circle 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 document circle resides within the query 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": { "geometry": { "shape": { "coordinates": [ -2.235143, 53.482358 ], "type": "circle", "radius": "100mi" }, "relation": "within" }, "field": "geoarea" }, "size": 10, "from": 0, "sort": [ { "by": "geo_distance", "field": "geojson", "unit": "mi", "location": { "lon": -2.235143, "lat": 53.482358 } } ], "size": 5, "from": 0, "sort": ["name"] }' | jq . ``` The output of five (5) hits (from a total of 36 matching docs) is as follows ```json { "status": { "total": 1, "failed": 0, "successful": 1 }, "request": { "query": { "geometry": { "shape": { "type": "circle", "coordinates": [ -2.235143, 53.482358 ], "radiusInMeters": 160934.4 }, "relation": "within" }, "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_577", "score": 0.1543972016608065, "sort": [ "Barkston Heath" ] }, { "index": "test_geojson_3397081757afba65_4c1c5584", "id": "airport_469", "score": 0.5853253239353176, "sort": [ "Birmingham" ] }, { "index": "test_geojson_3397081757afba65_4c1c5584", "id": "airport_514", "score": 0.14663352685195305, "sort": [ "Blackpool" ] }, { "index": "test_geojson_3397081757afba65_4c1c5584", "id": "airport_511", "score": 0.19445510224080859, "sort": [ "Brough" ] }, { "index": "test_geojson_3397081757afba65_4c1c5584", "id": "airport_568", "score": 0.1561033061076272, "sort": [ "Church Fenton" ] } ], "total_hits": 36, "max_score": 1.015720869823755, "took": 8549509, "facets": null } ```