Please use the form below to provide your feedback. Because your feedback is valuable to us, the information you submit in this form is recorded in our issue tracking system (JIRA), which is publicly available. You can track the status of your feedback using the ticket number displayed in the dialog once you submit the form.

A newer version of this documentation is available.

View Latest

Circle Query

      +
      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.

      {
  "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.

      {
  "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.

      {
  "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).

      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

      {
  "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.

      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).

      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

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