A newer version of this documentation is available.

View Latest

Polygon Query

      +
      A GeoJSON Polygon Query against any GeoJSON type.

      Couchbase Server 7.1.2

      QueryShape for a Polygon Query

      A GeoJSON query via a GeoShape of Polygon to find GeoJSON types in a Search index using the 3 relations intersects, contains, and within.

      Polygon Intersects Query

      An intersect query for polygon returns all the matched documents with shapes that overlap with the area of the polygon within the query.

      A polygon intersection query sample is given below.

      {
        "query": {
          "field": "<<fieldName>>",
          "geometry": {
            "shape": {
              "type": "Polygon",
              "coordinates": [
                [
                  [-114.027099609375, 42.00848901572399],
                  [-114.04907226562499, 36.99377838872517],
                  [-109.05029296875, 36.99377838872517],
                  [-109.05029296875, 40.98819156349393],
                  [-111.060791015625, 40.98819156349393],
                  [-111.02783203125, 42.00848901572399],
                  [-114.027099609375, 42.00848901572399]
                ]
              ]
            },
            "relation": "intersects"
          }
        }
      }

      Intersection rules for the Polygon Query with other indexed GeoJSON shapes in the document set are given below.

      Intersects (relation)
      Document Shape

       
      Polygon (GeoShape)

      Point

      Intersects when the polygon area contains the point in the document.

      LineString

      Intersects when one of the polygon edges in the query intersects the linestring in the document.

      Polygon

      Intersects when the polygon area in the query intersects the polygon in the document.

      MultiPoint

      Intersects when the polygon area contains any of the points in the multipoint array in the document.

      MultiLineString

      Intersects when the polygon area in the query intersects any of the linestring in the multilinestring array in the document.

      MultiPolygon

      Intersects when the polygon in the query intersects any of the polygons in the multipolygon array in the document.

      GeometryCollection

      Matches when the query polygon intersects with any of the heterogeneous (above 6) shapes in the geometrycollection array in the document.

      Circle

      Intersects when the query polygon intersects the circular region in the document.

      Envelope

      Intersects when the query polygon intersects the area of the rectangular/bounded box region in the document.

      Polygon Contains Query

      A contains query for polygon returns all the matched documents with shapes that contain the polygon within the query.

      A polygon contains query sample is given below.

      {
        "query": {
          "field": "<<fieldName>>",
          "geometry": {
            "shape": {
              "type": "Polygon",
              "coordinates": [
                [
                  [-114.027099609375, 42.00848901572399],
                  [-114.04907226562499, 36.99377838872517],
                  [-109.05029296875, 36.99377838872517],
                  [-109.05029296875, 40.98819156349393],
                  [-111.060791015625, 40.98819156349393],
                  [-111.02783203125, 42.00848901572399],
                  [-114.027099609375, 42.00848901572399]
                ]
              ]
            },
            "relation": "contains"
          }
        }
      }

      Containment rules for the polygon query with other indexed shapes are given below.

      Contains (relation)
      Document Shape

       
      Polygon (GeoShape)

      Point

      NA. Point is a non-closed shape.

      LineString

      NA. Linestring is a non-closed shape.

      Polygon

      Contains when the polygon in the query resides completely within the polygon in the document.

      MultiPoint

      NA. MultiPoint is a non-closed shape.

      MultiLineString

      NA. MultiLineString is a non-closed shape.

      MultiPolygon

      Contains when the polygon in the query resides completely within any of the polygons in the multipolygon array in the document.

      GeometryCollection

      Matches when the query polygon is contained within any of the heterogeneous (above 6) shapes in the geometrycollection array in the document.

      Circle

      Contains when the query polygon resides completely within the circular region in the document.

      Envelope

      Contains when the query polygon resides completely within the rectangular/bounded box region in the document.

      Polygon WithIn Query

      The Within query is not supported by line geometries.

      A within query for polygon returns all the matched documents with shapes that contain the polygon within the query.

      A polygon contains query sample is given below.

      {
        "query": {
          "field": "<<fieldName>>",
          "geometry": {
            "shape": {
              "type": "Polygon",
              "coordinates": [
                [
                  [-114.027099609375, 42.00848901572399],
                  [-114.04907226562499, 36.99377838872517],
                  [-109.05029296875, 36.99377838872517],
                  [-109.05029296875, 40.98819156349393],
                  [-111.060791015625, 40.98819156349393],
                  [-111.02783203125, 42.00848901572399],
                  [-114.027099609375, 42.00848901572399]
                ]
              ]
            },
            "relation": "within"
          }
        }
      }

      WithIn rules for the polygon query with other indexed shapes are given below.

      Contains (relation)
      Document Shape

       
      Polygon (GeoShape)

      Point

      Matches when the polygon in the query contains the point in the document including points on the edge or coinciding with the vertices of the polygon.

      LineString

      Matches when the polygon in the query contains both the endpoints of the linestring in the document.

      Polygon

      Matches when the polygon in the query contains the polygon in the document completely.

      MultiPoint

      Matches when the polygon in the query contains every point in the multipoint array in the document.

      MultiLineString

      Matches when the polygon in the query contains every linestring in the multilinestring array in the document.

      MultiPolygon

      Matches when the polygon in the query contains every polygon in the multipolygon array in the document completely.

      GeometryCollection

      Matches when the query polygon contains every heterogeneous (above 6) shapes in the geometrycollection array in the document.

      Circle

      Matches when the polygon in the query contains the circle in the document completely.

      Envelope

      Matches when the polygon in the query contains the rectangle/envelope in the document completely.

      Example Polygon 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 when the polygon in the query contains the point in the document including points on the edge or coinciding with the vertices of the polygon.

      The Polygon below is Utah. 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": "Polygon",
              "coordinates": [
                [
                  [-114.027099609375, 42.00848901572399],
                  [-114.04907226562499, 36.99377838872517],
                  [-109.05029296875, 36.99377838872517],
                  [-109.05029296875, 40.98819156349393],
                  [-111.060791015625, 40.98819156349393],
                  [-111.02783203125, 42.00848901572399],
                  [-114.027099609375, 42.00848901572399]
                ]
              ]
            },
            "relation": "within"
          }
        },
        "size": 5,
        "from": 0,
        "sort": ["name"]
      }' |  jq .

      The output of five (5) hits (from a total of 18 matching docs) is as follows

      {
        "status": {
          "total": 1,
          "failed": 0,
          "successful": 1
        },
        "request": {
          "query": {
            "geometry": {
              "shape": {
                "type": "Polygon",
                "coordinates": [
                  [
                    [
                      -114.027099609375,
                      42.00848901572399
                    ],
                    [
                      -114.04907226562499,
                      36.99377838872517
                    ],
                    [
                      -109.05029296875,
                      36.99377838872517
                    ],
                    [
                      -109.05029296875,
                      40.98819156349393
                    ],
                    [
                      -111.060791015625,
                      40.98819156349393
                    ],
                    [
                      -111.02783203125,
                      42.00848901572399
                    ],
                    [
                      -114.027099609375,
                      42.00848901572399
                    ]
                  ]
                ]
              },
              "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": "airport_6999",
            "score": 0.13231342774148913,
            "sort": [
              "Brigham City"
            ]
          },
          {
            "index": "test_geojson_3397081757afba65_4c1c5584",
            "id": "airport_7857",
            "score": 0.27669394470240527,
            "sort": [
              "Bryce Canyon"
            ]
          },
          {
            "index": "test_geojson_3397081757afba65_4c1c5584",
            "id": "airport_7074",
            "score": 0.13231342774148913,
            "sort": [
              "Canyonlands Field"
            ]
          },
          {
            "index": "test_geojson_3397081757afba65_4c1c5584",
            "id": "airport_7583",
            "score": 0.13231342774148913,
            "sort": [
              "Carbon County Regional-Buck Davis Field"
            ]
          },
          {
            "index": "test_geojson_3397081757afba65_4c1c5584",
            "id": "airport_3824",
            "score": 0.24860341896785076,
            "sort": [
              "Cedar City Rgnl"
            ]
          }
        ],
        "total_hits": 18,
        "max_score": 0.27669394470240527,
        "took": 16364364,
        "facets": null
      }

      Example Polygon 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.

      Intersects when the query polygon intersects the circular region in the document.

      The Polygon below is Utah. 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": "Polygon",
              "coordinates": [
                [
                  [-114.027099609375, 42.00848901572399],
                  [-114.04907226562499, 36.99377838872517],
                  [-109.05029296875, 36.99377838872517],
                  [-109.05029296875, 40.98819156349393],
                  [-111.060791015625, 40.98819156349393],
                  [-111.02783203125, 42.00848901572399],
                  [-114.027099609375, 42.00848901572399]
                ]
              ]
            },
            "relation": "intersects"
          }
        },
        "size": 5,
        "from": 0,
        "sort": ["name"]
      }' |  jq .

      The output of five (5) hits (from a total of 20 matching docs) is as follows

      {
        "status": {
          "total": 1,
          "failed": 0,
          "successful": 1
        },
        "request": {
          "query": {
            "geometry": {
              "shape": {
                "type": "Polygon",
                "coordinates": [
                  [
                    [
                      -114.027099609375,
                      42.00848901572399
                    ],
                    [
                      -114.04907226562499,
                      36.99377838872517
                    ],
                    [
                      -109.05029296875,
                      36.99377838872517
                    ],
                    [
                      -109.05029296875,
                      40.98819156349393
                    ],
                    [
                      -111.060791015625,
                      40.98819156349393
                    ],
                    [
                      -111.02783203125,
                      42.00848901572399
                    ],
                    [
                      -114.027099609375,
                      42.00848901572399
                    ]
                  ]
                ]
              },
              "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_6999",
            "score": 0.07521314153068777,
            "sort": [
              "Brigham City"
            ]
          },
          {
            "index": "test_geojson_3397081757afba65_4c1c5584",
            "id": "airport_7857",
            "score": 0.2608486787753336,
            "sort": [
              "Bryce Canyon"
            ]
          },
          {
            "index": "test_geojson_3397081757afba65_4c1c5584",
            "id": "airport_7074",
            "score": 0.08184801789845488,
            "sort": [
              "Canyonlands Field"
            ]
          },
          {
            "index": "test_geojson_3397081757afba65_4c1c5584",
            "id": "airport_7583",
            "score": 0.08652876583277351,
            "sort": [
              "Carbon County Regional-Buck Davis Field"
            ]
          },
          {
            "index": "test_geojson_3397081757afba65_4c1c5584",
            "id": "airport_3824",
            "score": 0.4282420802218974,
            "sort": [
              "Cedar City Rgnl"
            ]
          }
        ],
        "total_hits": 20,
        "max_score": 0.5252881608935254,
        "took": 12509460,
        "facets": null
      }