A newer version of this documentation is available.

View Latest

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

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