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

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

Note: 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.

Best practice: 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.

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.

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.

Note: 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: