Geo Bounded Polygon Query
The ability to perform text search with geospatial query capabilities is a very powerful and effective feature from full text search(FTS). And we are bringing the more flexible geo bounded polygon query feature to FTS in the upcoming releases.
Until now, FTS supports two types of geo queries. ie Point Distance queries and Bounded rectangle queries. Point Distance query helps you in serving searches like – finding all points of interest near you in their sorted order of distance, whereas the Bounded Rectangle query helps in finding all points of interest within the given rectangle boundary specified over the top_left and bottom_right corners.
We know that in most real life use cases the geospatial boundaries come in all random shapes. ie they don’t just show up like simple rectangular or square regions. Certainly, rectangles/squares could be used as a first-hand approximation for the given spatial query. But for better precision results, we should be able to specify the region boundaries in a more granular way.
And that leads to the introduction of geo bounded polygon queries in full text search.
Essentials
This feature adds the capability to perform a random bounding polygon query to select documents falling within that polygon area. Input parameters would be an array of coordinate pairs representing bounding polygon vertices that define the polygon area. (preferably in an anticlockwise direction). Results should be a list of documents that lies within the area.
A few considerations for bounded polygon queries are:
- The orientation of polygon coordinates is governed by the geoJSON standard. ref – geojson
- Coordinates could be specified in a closed format (giving the last coordinate same as the first one) as well, but not necessary.
- It uses the ray casting technique for finding the point inclusivity in the polygon.
- No holes in the polygons are supported now. But there is a way users may perform such queries using boolean queries. (must_not clause for the inner polygons for querying shapes like donuts).
- The searchable geolocation field in the document needs to be indexed using the prebuilt “geopoint” type.
Modus Operandi
Let’s quickly explore how easy it is to try out a bounded polygon query with FTS. It is just a 3 step process:
- Index the documents the same as we do for bounded rectangle/point distance query.
- Identify a polygon area (vertices) you need to query within.
- Try the query in any of the geojson formats mentioned in the example below.
For example, if you have a field named “geo” in the document which contains the geographic location information, then first you need to include it in the index definition like below.
Once the indexing is completed, you are ready to try your searches!
Let’s say you are interested in finding documents within a given region.
You may try the polygon queries like below.
curl -XPOST -H "Content-Type: application/json"
-u <username>:<password> http://<node>:<port>/api/index/<indexName>/query -d '
{
"query": {
"field": "geo",
"polygon_points": [
"37.79393211306212,-122.44234633404847",
"37.77995881733997,-122.43977141339417",
"37.788031092020155,-122.42925715405579",
"37.79026946582319,-122.41149020154114",
"37.79571192027403,-122.40735054016113",
"37.79393211306212,-122.44234633404847"
]
}
}'
All the geo queries in FTS supports geoJSON formats and hence any of the below polygon coordinate formats can be used in addition to the above sample
"polygon_points": [
{“lat”: 37.79393211306212, “lon”: -122.44234633404847},
{ “lat”: 37.77995881733997, “lon”: -122.43977141339417},
{ “lat”: 37.788031092020155, “lon”: -122.4292571540557},
{ “lat”: 37.79026946582319,“lon”: -122.41149020154114},
{ “lat”: 37.79571192027403,“lon”: -122.40735054016113},
{ “lat”: 37.79393211306212, “lon”: -122.44234633404847}
]
Or
"polygon_points": [
[ -122.44234633404847, 37.79393211306212],
[ -122.43977141339417, 37.77995881733997],
[ -122.42925715405579, 37.78803109202015],
[ -122.41149020154114, 37.79026946582319],
[ -122.40735054016113, 37.79571192027403],
[ -122.44234633404847,37.79393211306212]
]
Or
"polygon_points": [“9q8zjbkp”, “9q8yvvdh”, “9q8yyp1e”, “9q8yyrw8”, “9q8zn83x”, “9q8zjb0j”]
Eager to get your hands dirty with bounded polygon queries? Please pay heed to the upcoming Couchbase server releases.
