A newer version of this documentation is available.

View Latest

Envelope Query

      +
      A GeoJSON Envelope Query against any GeoJSON type.

      Couchbase Server 7.1.2

      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.

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

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

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

      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

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

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

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