Querying Spatial Views

Spatial views are retrieved with the REST API GET /[bucket-name]/_design/[design-doc]/_spatial/[spatial-name] HTTP method and URI.

HTTP method and URI

GET /[bucket-name]/_design/[design-doc]/_spatial/[spatial-name]

HTTP Description

HTTP	Description
Method and URI	`GET /[bucket-name]/_design/[design-doc]/_spatial/[spatial-name]`
Request Data	None
Response Data	JSON of the documents returned by the view
Authentication Required	no

Method and URI

GET /[bucket-name]/_design/[design-doc]/_spatial/[spatial-name]

Request Data

None

Response Data

JSON of the documents returned by the view

Authentication Required

The start_range and end_range parameters take a JSON array and are preferred over the bbox parameter.

Table 1. Query parameters
Parameter	Type	Description
`start_range`	Array of numeric or null; optional	The number of elements must match the number of dimensions of the index.
`end_range`	Array of numeric or null; optional	The number of elements must match the number of dimensions of the index.
`bbox`	String; optional	Specify the bounding box for a spatial query.
`limit`	Numeric; optional	Limit the number of the returned documents to the specified number.
`skip`	Numeric; optional	Skip this number of records before starting to return the results.
`stale`	String; optional	Specifies the level of data freshness. Supported values: `false` The server waits for the indexer to finish the changes that correspond to the current key-value document set and then returns the latest entries from the view file. `ok` The server returns the current entries from the view file. `update_after` The server returns the current entries from the view file, and then initiates an view file update.

When submitting a view query, the stale parameter is used to specify the data freshness. The stale parameter the following values:

ok—The server returns the current entries from the index file.
update_after—The server returns the current entries from the index, and then initiates an index update.
false—The server waits for the indexer to finish the changes that correspond to the current key-value document set and then returns the latest entries from the view index.

Every 5 seconds the automatic update process checks whether 5000 changes have occurred. If a minimum of 5000 changes occurred, an view file update is triggered. Otherwise, no update is triggered. When triggered, the indexer requests from DCP all changes since it was last run. The default number of changes to check for is 5000, but that number can be configured by setting the updateMinChanges option. The update interval can also be configured by setting the updateInterval option.

The stale=false view query argument has been enhanced. When an application sends a query that has the stale parameter set to false, the application receives all recent changes to the documents, including changes that haven’t yet been persisted to disk. It considers all document changes that have been received at the time the query was received.

You can issue the stale=false view query anytime and results will fetch all changes that have been made when the query was issued.

For better scalability and throughput, set the value of the stale parameter to ok. With the stream-based views, data returned when stale is set to ok is closer to the key-value data, even though it might not include all of it.

Responses

The standard response includes total_rows, id, key, value, and geometry. The total_rows item is always zero. The geometry item is not shown if no geometry was emitted. If a geometry was emitted, the key contains the ranges of the calculated bounding box.

{"total_rows":0, "rows": [{
    "id":"id-name"
    "key": [[value, value], [value, value]],
    "value": null,
    "geometry": {"type": "Point", "coordinates": [value, value]}
}]}

Example response if geometry was emitted:

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

Example response if geometry was not emitted:

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

Open Range Queries

Open range queries specify null as a value on either one or both sides of the range.

For example, to query shops in Germany that are open between 10:00 and 20:00.

In this case, the emit could be:

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

To query for shops in Germany with an opening time of 10:00 and no closing time:

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

To query for shops in Germany with no opening time and a closing time of 20:00:

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

To query for shops in Germany with no opening or closing time:

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

To query for shops anywhere (no location specified) with an opening time of 10:00 and a closing time of 20:00:

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

Closed Range Queries

Closed range queries use the start_range and end_range parameters with the bounds specified.

Closed range queries are used to query items with a certain range. If no range is supplied, the full data set is returned. For example, if only the longitude (1st dimension) and the latitude (2nd dimension) is emitted, the bounds of a country could be queried.

For example, to query shops in Germany that are open between 10:00 and 20:00.

In this case, the emit could be:

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

This emit cannot be a query with a bounding box because it contains three dimensions.

The query for the shop emit could be:

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

Bounding Box Queries

Bounding box queries are implemented via HTTP method and URI.

Use of the bounding box parameter is discouraged. Use the start_range and end_range parameters instead. Every bounding box can be expressed with start_range and end_range parameters.

If a bounding box is not supplied, the full data set is returned. When querying a spatial index, use the bounding box to specify the boundaries of the query lookup on a given value. The specification should be in the form of a comma-separated list of the coordinates to use during the query.

These coordinates are specified as in the GeoJSON specification, so the first two numbers are the lower left coordinates, and the last two numbers are the upper right coordinates.

A bounding box can be expressed as with start_range and end_range parameters. Example:

bbox=0,0,180,90

start_range=[0,0]&end_range[180,90]

Syntax

GET http://[localhost]:8092/places/_design/[design-doc]/_spatial/points?bbox=-180,-90,0,0
        Content-Type: application/json

Example

HTTP request example:

GET http://127.0.0.1:8092/places/_design/main/_spatial/points?bbox=-180,-90,0,0
        Content-Type: application/json

Response

Example response:

{
        "total_rows": 0,
        "rows": [
        {
        "id": "oakland",
        "key": [
        [
        -122.270833,
        -122.270833
        ],
        [
        37.804444,
        37.804444
        ]
        ],
        "value": [
        "oakland",
        [
        -122.270833,
        37.804444
        ]
        ]
        }
        ]
        }