A newer version of this documentation is available.

View Latest

Working with view queries

You can use MapReduce views to create queryable secondary and composite indexes in Couchbase Server.

The Couchbase .NET SDK offers access to all features of the Couchbase View API. Note that before working with the API, a design document and View must exist on the Couchbase Server you are targeting.

For these examples, we will use the design documents and views that come with the beer-sample sample bucket that can be installed directly from the Couchbase Management Console. To install the sample buiket, navigate to the console, log in, and click the Settings tab. After you have done this, click Sample Buckets. Under Available Samples, select the beer-sample check box. Then click Create.

installing beer sample

After you have the beer-sample sample data and bucket installed, you can run some queries. The beer-sample comes with a design document called beer and some views defined: brewery_beers, by_country, and by_location. We use these in the next several examples.

First a very simple query that fetches the results of the brewery_beers view. The view definition looks like this:

brewery_beers view
function(doc, meta) {
	switch (doc.type) {
		case "brewery":
		case "beer":
			if (doc.brewery_id) {
				emit([doc.brewery_id, meta.id]);

What this does is create secondary indexes for every document with a type of brewery and a composite index for every document of type beer. When this map function runs, it returns a list of all of these keys. Here is an example of querying this view using the Couchbase .NET SDK:

 var query = bucket.CreateQuery("beer", "brewery_beers", false).

 var result = bucket.Query<dynamic>(query);
 foreach (var row in result.Rows)

First, an IViewQuery object is created by calling the factory method IBucket.CreateQuery() and passing in false to indicate that we want to target a production view. Then we specify the design document to use, the view on the design document that we want to query, and the limit on the number of rows to return. We then use the IBucket.Query() method to execute the query and then iterate through the results.

IViewQuery is a fluent interface that allows a series of methods to be chained together. Internally, it’s creating the HTTP request URL that will be sent the server and executed. Besides the methods defined in the query above, which are the minimal set of methods you must call to make a query, there are several others. The following table lists select IViewQuery methods. For a complete list of IViewQuery methods, the parameters they take and their return types, refer to the API Reference.

Table 1. SelectedIVQuery methods
Name Description


Specify the bucket and the design document to query


Specify the bucket to query


Specify the design document to query


Specify the view to query


The number of records to skip


Whether or not to return stale data or force an index: StaleMode.False | Ok | UpdateAfter


Sort in ascending order by key


Sort in descending order by key


Groups the results from the reduce function into a single row


Specify the level of grouping to use


The maximum number of rows to return


True to use the reduce method


The number of seconds to wait before timing out a request


Returns the internally created HTTP request URL

The IBucket.Query() method returns an object implementing the IViewResult<T> interface. The following table lists some of the members of the IViewResult<T> interface.

Table 2. Selected IViewResult<T> interface methods
Name Description


The error message returned by the View engine


If the query failed as the result of a server error, a message indicating the reason why


A List<T> of T, which is the result of the query


true if the query completed successfully


The HTTP status code returned by the server


The total rows available; may not match the exact rows returned if Limit is called.

You can iterate over the Rows property if the query was successful or check the Message and Error properties if Success returns false to determine the reason why the query failed.