Working with views

Working with views

This section describes how to query views in a design document.

Anatomy of a view query

When you query a view you need to provide both the name of the Design Document and the name of the View. If you do not provide any further options, the SDK assumes you want to query a published view (so it is not in development mode) and also will not set any query options.

This example queries a view with the name myview , which lives in the Design Document designdoc . If no further arguments are provided, it is assumed that the design document is published.

// Perform the ViewQuery
ViewResult result = bucket.query(ViewQuery.from("designdoc", "myview"));

// Iterate through the returned ViewRows
for (ViewRow row : result) {
    System.out.println(row);
}

You can provide optional parameters at query time that alter the returned row set. For example, you can limit the returned rows to a maximum of 10 and also query a view that is not published yet (still in development mode):

// Perform the Query with more options
bucket.query(ViewQuery.from("designdoc", "myview").development(false).limit(10));

If you want to query a geospatial view, you just need to use a different query builder:

Note: Geospatial queries are supported only against Couchbase Server 3.0.1 or later and are currently experimental. If going as planned, the next major release will provide stable support. It is not expected that the client API will change, because it is very similar to what is provided against regular views.
// Perform the SpatialViewQuery
SpatialViewResult result = bucket.query(SpatialViewQuery.from("designdoc", "myview"));

// Iterate through the returned SpatialViewRows
for (SpatialViewRow row : result) {
    System.out.println(row);
}

For all types of views, a *ViewResult is always returned, which contains zero to many *ViewRows . In addition to iterative row access, more methods are available on the result:

Method Description
List<ViewRow> allRows() Accumulates all returned rows in a List and returns it.
Iterator<ViewRow> rows() Provides iterative access to rows as they arrive.
int totalRows() The total number of rows in the index, can be greater than the number of rows() returned.
boolean success() True if the query was successful, false otherwise. Check error() if so.
JsonObject error() Contains the error if the query was not successfull, null otherwise.
JsonObject debug() Contains debug information if debug() was enabled on the query, null otherwise.

The only difference between regular and spatial view results is the fact that spatial ones do not expose the number of totalRows .

Regular View Options

All options shown here are available on the ViewQuery in a fluent API manner. All of them are optional, so only when they are explicitly provided they will alter the behavior of the query.

As a general note, all arguments that accept JSON are provided with a higher number of method overloads to accommodate all combinations in a type-safe manner.

Method Accepted Types Description
development boolean When true queries the development view, false by default.
reduce boolean Explicitly enables/disables the reduce function on the query. If not provided and the view has a reduce function, it will be used.
limit int Limits the number of the returned documents to the specified number.
skip int Skips the given number of records before starting to return the results.
group boolean Groups the results using the reduce function to a group or single row.
groupLevel int Specifies the group level to be used.
inclusiveEnd boolean Whether the specified end key should be included in the result.
stale Stale.TRUE, Stale.FALSE, Stale.UPDATE_AFTER (default) Defines how stale the view results are allowed to be on query.
debug boolean Enabled debugging on view queries.
onError OnError.STOP (default), OnError.CONTINUE Sets the response in the event of an error.
descending boolean Returns the documents in descending by key order if true, default is false.
key JSON The exact key to return from the query.
keys JsonArray Only the given matching keys will be returned.
startKeyDocId String Where to start searching for the key range. Can be used for efficient pagination.
endKeyDocId String Where to stop searching for the key range.
startKey JSON The key where the row return range should start.
endKey JSON The key where the row return range should end.
Note: Important when using Grouping: group(boolean) and groupLevel(int) should not be used together in the same view query. It is sufficient to only set the grouping level only and use this setter in cases where you always want the highest group level implicitly.

Geospatial View Options

All options shown here are available on the SpatialViewQuery in a fluent API manner. All of them are optional, so only when they are explicitly provided they will alter the behaviour of the query.

Method Accepted Types Description
development boolean When true queries the development view, false by default.
limit int Limits the number of the returned documents to the specified number.
skip int Skips the given number of records before starting to return the results.
stale Stale.TRUE, Stale.FALSE, Stale.UPDATE_AFTER (default) Defines how stale the view results are allowed to be on query.
debug boolean Enabled debugging on view queries.
onError OnError.STOP (default), OnError.CONTINUE Sets the response in the event of an error.
startRange JsonArray Where the spatial range should start. Can be multidimensial.
endRange JsonArray Where the spatial range should end. Can be multidimensial.
range JsonArray, JsonArray Convenience method to combine start and endrange in one argument.