Circle Query

March 23, 2025

+ 12

A GeoJSON Circle Query against any GeoJSON type.

Couchbase Server 7.1.2

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

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
Copy
{
  "query": {
    "field": "<<fieldName>>",
    "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

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
Copy
{
  "query": {
    "field": "<<fieldName>>",
    "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

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
Copy
{
  "query": {
    "field": "<<fieldName>>",
    "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)

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.

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
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": {
    "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
Copy
{
  "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)

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 document circle resides within the query 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": {
    "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
Copy
{
  "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
}

Circle Query

QueryShape for a Circle Query

Circle Intersects Query

Circle Contains Query

Circle WithIn Query

Example Circle Query (against Points)

Example Circle Query (against Circles)

Circle `Intersects` Query

Circle `Contains` Query

Circle `WithIn` Query