A newer version of this documentation is available.

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,
}]}