With Couchbase Server 2.0, you have two ways of fetching your documents: either by the unique key through the get method, or through Views. Since Views are more complex, let's tackle get first:

Object get = client.get("mykey");

Since Couchbase doesn't really know what you've stored as a document, you get a Object back. If you store JSON documents, the actual document will be a String, so you can safely convert it to a string:

String json = (String) client.get("mykey");

If no document was found, null is returned. It is important to check for null, to prevent NullPointerExceptions later down the stack.

With Couchbase Server 2.0, the very powerful ability to query your documents through secondary indexes (Views) has been added to your toolbelt. This guide gets you started on how to use them through the Java SDK, if you want to learn more please refer to the chapter in the Couchbase Server 2.0 documentation.

Once you created your View in the UI, you can query it from the SDK in three steps. First, you grab the View definition from the cluster, second you create a Query object and third, you query the cluster with both the View and the Query objects. In its simplest form, it looks like this:

// 1: Get the View definition from the cluster
View view = client.getView("beer", "brewery_beers");

// 2: Create the query object
Query query = new Query();

// 3: Query the cluster with the view and query information
ViewResponse result = client.query(view, query);

The getView() method needs both the name of the Design Document and the View to load up the proper definition from the cluster. This is needed to determine if there is a view with the given information and also if it contains a reduce function (or is even a spatial view).

Views can be queried with a large amount of options. All supported options are available as setter methods on the Query object. Here are some of them:

Now that we have our View information and the Query object in place, we can issue the query command, which actually triggers the scatter-gather data loading process on the Cluster. The resulting information is encapsulated inside the ViewResponse object. We can use it to iterate over the results and print out some details (here is a more complete example which also includes the full documents and only fetches the first five results):

View view = client.getView("beer", "brewery_beers");
Query query = new Query();
query.setIncludeDocs(true).setLimit(5); // include all docs and limit to 5
ViewResponse result = client.query(view, query);

// Iterate over the result and print the key of each document:
for(ViewRow row : result) {
  System.out.println(row.getId());
  // The full document (as String) is available through row.getDocument();
}

In the logs, you can see the corresponding document keys automatically sorted (ascending):

21st_amendment_brewery_cafe
21st_amendment_brewery_cafe-21a_ipa
21st_amendment_brewery_cafe-563_stout
21st_amendment_brewery_cafe-amendment_pale_ale
21st_amendment_brewery_cafe-bitter_american