The Couchbase Search service is introducing higher dimensional geospatial indexing and querying capabilities with the Couchbase Server release 7.1.2.
Until this new feature, the Search service was limited to indexing single dimensional geopoint/location fields. Queries were limited to bounding queries like point-distance, bounded-rectangle and bounded-polygon against the indexed geopoint field. But we know that geopoints alone won’t be effective in representing the various spatial details of real life shapes or structures.
Support of such higher dimensional spatial structures enables users to approximate a large variety of real life shapes like postal or jurisdictional region boundaries, routes for delivery vehicles or an airline carrier or the boundaries of various water bodies like a river, lake, stream etc.
Search service will now support the GeoJSON spatial data formats on spherical geodesics in this release. This enable users to address use cases such as finding all the documents with any GeoJSON shapes that:
-
- contain the query shape
- reside within the query shape
- intersect with the query shape
The supported GeoJSON shapes are:
In addition to the above shapes, Search also supports a couple additional custom shapes to make the spatial approximations easy for users. The extra shapes supported are:
-
- Circle
- Envelope
The new GeoJSON types
Let’s have a quick glance over all these various shape types.
All simple geometries in GeoJSON consist of a type and a collection of coordinates.
Point
The following specifies a GeoJSON Point field in a document:
|
1 2 3 4 |
{ "type": "Point", "coordinates": [75.05687713623047,22.53539059204079] } |
A point is a single geographic coordinate, such as the location of a building or the current position given by any Geolocation API.
Note : The standard only supports a single way of specifying the coordinates like an array format of longitude followed by latitude. ie: [lng, lat].
Linestring
The following specifies a GeoJSON Linestring field in a document:
|
1 2 3 4 5 6 7 |
{ "type": "LineString", "coordinates": [ [ 77.01416015625, 23.0797317624497], [ 78.134765625, 20.385825381874263] ] } |
A linestring is defined by an array of two or more positions. By specifying only two points, the linestring will represent a straight line. Specifying more than two points creates an arbitrary path.
Polygon
The following specifies a GeoJSON Polygon field in a document:
|
1 2 3 4 5 6 7 8 9 |
{ "type": "Polygon", "coordinates": [ [ [ 85.605, 57.207], [ 86.396, 55.998], [ 87.033, 56.716], [ 85.605, 57.207] ] ] } |
A polygon is defined by a list of a list of points. The first and last points in each (outer) list must be the same (i.e., the polygon must be closed). And the exterior coordinates have to be in Counter Clockwise Order (CCW) in a polygon.
Polygons with holes are also supported. The holes have to follow Clockwise Order for the boundary vertices.
For Polygons with a single ring, the ring cannot self-intersect.
NOTE: The CCW order of vertices is strictly mandated for the geoshapes in the Couchbase Server release 7.1.2 and any violation of this requirement would result in unexpected search results.
MultiPoint
The following specifies a GeoJSON Multipoint field in a document:
|
1 2 3 4 5 6 7 8 9 |
{ "type": "MultiPoint", "coordinates": [ [ -115.8343505859375, 38.45789034424927], [ -115.81237792968749, 38.19502155795575], [ -120.80017089843749, 36.54053616262899], [ -120.67932128906249, 36.33725319397006] ] } |
MultiLineString
The following specifies a GeoJSON MultiLineString field in a document:
|
1 2 3 4 5 6 7 8 |
{ "type": "MultiLineString", "coordinates": [ [ [ -118.31726074, 35.250105158],[ -117.509765624, 35.3756141] ], [ [ -118.6962890, 34.624167789],[ -118.317260742, 35.03899204] ], [ [ -117.9492187, 35.146862906], [ -117.6745605, 34.41144164] ] ] } |
MultiPolygon
The following specifies a GeoJSON MultiPolygon field in a document:
|
1 2 3 4 5 6 7 8 9 10 |
{ "type": "MultiPolygon", "coordinates": [ [ [ [ -73.958, 40.8003 ], [ -73.9498, 40.7968 ], [ -73.9737, 40.7648 ], [ -73.9814, 40.7681 ], [ -73.958, 40.8003 ] ] ], [ [ [ -73.958, 40.8003 ], [ -73.9498, 40.7968 ], [ -73.9737, 40.7648 ], [ -73.958, 40.8003 ] ] ] ] } |
GeometryCollection
The following specifies a GeoJSON GeometryCollection field in a document:
A GeometryCollection has a member with the name “geometries”. The value of “geometries” is an array. Each element of this array is a GeoJSON Geometry object. It is possible for this array to be empty.
Unlike the other geometry types described above, a GeometryCollection can be a heterogeneous composition of smaller Geometry objects. For example, a Geometry object in the shape of a lowercase roman “i” can be composed of one point and one LineString.
Nested GeometryCollections are invalid.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 |
{ "type": "GeometryCollection", "geometries": [ { "type": "MultiPoint", "coordinates": [ [ -73.9580, 40.8003 ], [ -73.9498, 40.7968 ], [ -73.9737, 40.7648 ], [ -73.9814, 40.7681 ] ] }, { "type": "MultiLineString", "coordinates": [ [ [ -73.96943, 40.78519 ], [ -73.96082, 40.78095 ] ], [ [ -73.96415, 40.79229 ], [ -73.95544, 40.78854 ] ], [ [ -73.97162, 40.78205 ], [ -73.96374, 40.77715 ] ], [ [ -73.97880, 40.77247 ], [ -73.97036, 40.76811 ] ] ] }, { "type" : "Polygon", "coordinates" : [ [ [ 0 , 0 ] , [ 3 , 6 ] , [ 6 , 1 ] , [ 0 , 0 ] ], [ [ 2 , 2 ] , [ 3 , 3 ] , [ 4 , 2 ] , [ 2 , 2 ] ] ] } ] } |
Circle
If the users wishes to cover a circular region over earth’s surface, then they could use this shape.
A sample circular shape is as below.
|
1 2 3 4 5 |
{ "type": "circle", "coordinates": [75.05687713623047,22.53539059204079], "radius": "1000m" } |
Circle is specified over the center point coordinates along with the radius.
Example formats supported for radius are:
“5in” , “5inch” , “7yd” , “7yards”, “9ft” , “9feet”, “11km”, “11kilometers”, “3nm” “3nauticalmiles”, “13mm” , “13millimeters”, “15cm”, “15centimeters”, “17mi”, “17miles” “19m” or “19meters”.
If the unit cannot be determined, the entire string is parsed and the unit of meters is assumed.
Envelope
Envelope type, which consists of coordinates for upper left and lower right points of the shape to represent a bounding rectangle in the format [[minLon, maxLat], [maxLon, minLat]].
|
1 2 3 4 5 6 7 |
{ "type": "envelope", "coordinates": [ [72.83, 18.979], [78.508,17.4555] ] } |
Indexing the spatial fields – new geoshape fieldtype
Search has introduced a field type named geoshape for representing the aforementioned spatial shapes.
If you have a field named “geometry” in the document which contains the geo shape information adhering to geoJSON format, then first you can include the geospatial field under the type mappings in the index definition like below.
Finally, click on the Create Index button and you are set for querying your geospatial data.
Note: The geoshape field type is capable of indexing any of the earlier mentioned spatial types including Point, LineString, Polygon, MultiPoint, MultiLineString, MultiPolygon, GeometryCollection, Circle and Envelope.
Querying the spatial fields – new GeoShape Query
Search primarily supports three types of spatial querying capability across those heterogeneous types of geoshapes indexed.
Query Structure:
|
1 2 3 4 5 6 7 8 9 10 11 12 |
{ "query": { "field": " << fieldName >> ", "geometry": { "shape": { "type": " << shapeDesc >> ", "coordinates": [[[ ]]] }, "relation": " << relation >> " } } } |
Details:
-
- shapeDesc – Can be any of the 9 types like Point, LineString, Polygon, MultiPoint, MultiLineString, MultiPolygon, GeometryCollection, Circle and Envelope.
- relation – Can be any of the 3 types like intersects , contains and within.
| Relation | Result |
| INTERSECTS | Return all documents whose spatial field intersects the query geometry. |
| CONTAINS | Return all documents whose spatial field contains the query geometry |
| WITHIN | Return all documents whose spatial field is within the query geometry. |
Let’s explore a few query samples.
A point contains query returns all the matched documents with shapes that contain the given point in the query:
|
1 2 3 4 5 6 7 8 9 10 11 12 |
{ "query": { "field": "<<fieldName>>", "geometry": { "shape": { "type": "point", "coordinates": [75.05687713623047, 22.53539059204079] }, "relation": "contains" } } } |
lineString intersects query returns all the matched documents with shapes that intersects with the linestring in the query:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
{ "query": { "field": "<<fieldName>>", "geometry": { "shape": { "type": "linestring", "coordinates": [ [77.01416015625, 23.079731762449878], [78.134765625, 20.385825381874263] ] }, "relation": "intersects" } } } |
Polygon withIn query returns all the matched documents with shapes that are residing completely within the area of the polygon in the query:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
{ "query": { "field": "<<fieldName>>", "geometry": { "shape": { "type": "polygon", "coordinates": [ [ [77.59012699127197, 12.959853852513307], [77.59836673736572, 12.959853852513307], [77.59836673736572, 12.965541604118611], [77.59012699127197, 12.965541604118611], [77.59012699127197, 12.959853852513307] ] ] }, "relation": "within" } } } |
Additional Tips
The Search service uses geodesics or spherical geometry to support the advanced spatial features. That means the curvature of earth’s surface is taken into account while performing spatial filters. Please keep this in mind while observing any differences in the boundary alignment of the given shape.
These resources are available to help you understand and validate geometries in your test data:
-
- Reference for the spherical mapper – gcmap
- Reference for checking the geojson shapes – geojson.io
- Reference for validating the vertex order or the correctness of GeoJSON – geojsonlint
