Spatial Views API

This is a description of the spatial views API in Couchbase >3.0.1. For creating and querying spatial views the API is backwards compatible to Couchbase 2.x. Only the responses changed a bit.

Emit

Emitting keys and values is the basis to create an index. The value can be any JSON. The key has certain constraints.

Key

GeoJSON geometry

The key can be a GeoJSON geometry. Example:

emit({
    "type": "Point",
    "coordinates":[10.9, 48.4]
}, null);

This is mainly for backwards compatibility with Couchbase 2.x. It's recommend to use one of the other ways to specify a key. The bounding box of the geometry will automatically be calculated and used as ranges. The key will internally be stored as [[10.9, 10.9], [48.4, 48.4]].

Array

As the spatial views are now multi-dimensional, you specify the key as array where every element is one dimension. Every dimension can either be a single value or a range. Only numbers supported (there's one special case for GeoJSON geometries, see below).

Single values

When you use a single in the key, it will be expanded to a collapsed range. This means that if you have a key like [1, 2], it will be stored as [[1, 1], [2, 2]]]. Example:

emit([10.9, 48.4], null);

Ranges

It's also possible to use ranges for the key. Let's say you have shops with certain opening hours, e.g. from 10:00 - 20:00:

emit([[1000, 2000]], null);

You can of course also mix it with single values. So in case you also have the shop location you can do:

emit([10.9, 48.4, [1000, 2000]], null);

GeoJSON geometry

You can have a GeoJSON geometry as the first element of the array. The bounding box will then be automatically be calculated and used as range. Example:

emit([{
    "type": "Point",
    "coordinates":[10.9, 48.4]
}], null);

Internally the key will be stored as [[10.9, 10.9], [48.4, 48.4]].

Using a GeoJSON geometry in the key can also be combined with single values or ranges. Let's say you also store shop categries and category 5 means "cloths". Your emit could be:

emit([{
    "type": "Point",
    "coordinates":[10.9, 48.4]
}, [1000, 2000], 5], null);

Queries

The queries for the spatial view have two new query parameters (start_range and end_range) which are preferred over the bbox parameter.

The start_range and end_range parameters take a JSON array. The array members must be either numbers or nulls, no other types are permitted. The number of elements must match the number of dimensions of your index. Please remember that an emitted geometry contains two dimensions.

Closed ranges

When you want to query things within a certain range, you specify the bounds. For example if only the longitude (1st dimension) and the latitude (2nd dimension) was emitted, you could query with the bounds of Germany:

Given the emit from the shop above a query might be:

?start_range=[5.87,47.27]&end_range=[15.04,55.06]

This equals a bounding box of:

?bbox=5.87,47.27,15.04,55.06

Open ranges

It's now also possible to specify open ranges, either on one side or both sides. This is done by specifying null as value.

Let's say you want to return all shops in Germany that open at 10:00 and you don't care when they close:

?start_range=[5.87,47.27,1000]&end_range=[15.04,55.06,null]

You can of course also query for all shops that are opened till 20:00 and you don't care when they open:

?start_range=[5.87,47.27,null]&end_range=[15.04,55.06,2000]

Or you don't care at all about the opening times at all:

?start_range=[5.87,47.27,null]&end_range=[15.04,55.06,null]

And finally you don't care about the location but about the opening times:

?start_range=[null,null,1000]&end_range=[null,null,2000]

Other query parameters

As the spatial views use mostly the same code path as the mapreduce views, there are query parameters that work equally with both.

limit

• any positive integer number (0 works, but doesn't make much sense)

skip

• any positive integer number and 0

stale

• update_after (default)
• false
• ok

debug

Not sure if that's public API, it should be whatever it is for mapreduce views.

• false (default)
• true

Responses

The responses from Couchbase >3.0.1 are not backwards compatible to 2.x. The id, value and geometry are still the same. Though the geometry might be omitted if there wasn't emitted one.

The incompatible change is the removal of the bbox property. Instead of the bounding box there's now the key returned. Note that the key is not the one that was emitted, but the one that was stored. In case you emitted a geometry, it contains the ranges of the calculated bounding box.

The total_rows is always 0 for now.

If a geometry was emitted it is included in the response:

{"total_rows":0, "rows": [{
    "id":"Augsburg",
    "key": [[10.9, 10.9], [48.4, 48.4]],
    "value": null,
    "geometry": {"type": "Point", "coordinates": [10.9, 48.4]}
}]}

A response where no geometry was emitted looks like:

{"total_rows":0, "rows": [{
    "id":"Augsburg",
    "key": [[10.9, 10.9], [48.4, 48.4], [1000, 2000]],
    "value": null
}]}