Sunday, December 30, 2012

When you are developing a new applications with Couchbase 2.0, you sometimes need to create view dynamically from your code. For example you may need this when you are installing your application, writing some test, or you can also use that when you are building frameworks, and wants to dynamically create views to query data. This post shows how to do it.

Let's now talk about Couchbase views. You use views/map-reduce functions to index and query data from Couchbase Server based on the content of the JSON document you store inside Couchbase. For more information about views you can look at the "view basics" chapter of the Couchbase Server Manual.

Create Views from Java

Creating a view from Java is really easy : the Java Client Library contains all the classes and methods to do it. As a concrete use case we will use the Application that is described in the Couchbase Java Tutorial.

When you follow this tutorial, you need to manually create some views, as you can see here. In this example, we will create our map function and directly in our Java code and then store it to Couchbase Server. The tutorial asks you to create the following artifacts:

Create a design document using the com.couchbase.client.protocol.views.DesignDocument class - line 4.

Create a view using com.couchbase.client.protocol.views.ViewDesign class with a name and the map function - line 14.

You can add this view to a design document - line 15

Finally save the document into the cluster using the CouchbaseClient.createDesignDoc method.

If you need to use a reduce function (built-in or custom) you just need to pass to the ViewDesign constructor as 3rd parameter.

When developing view, from Java or from any other tool/language be sure you understand what are the best practices, and the life cycle of the index. This is why I am inviting you to take a look to the following chapters in the Couchbase documentation:

Development and Production Views : in the view above, I have created the view in the development environment (dev_ prefix) allowing me to test and use it on a subset of the data (cluster/index)

Using the view

First of all, the view that you just created is in "development mode", and by default the Java client SDK will only access the view when it is in "production mode". This means that when you are calling a view from your application it will search it into the production environment. So before connecting to Couchbase cluster you need to setup the viewmode to development.

This is done using the viewmode environment variable from the Java SDK, that could be set using the following methods:

In your code, add this line before the client connects to the cluster : System.setProperty("viewmode", "development");

This code queries the view you just created. This means Couchbase Server will generate an index based on your map function, will query the server for results. In this case, we specifically want to set a limit of 20 results and also get the most current results by setting Stale.FALSE.

Set the viewmode to development - line 4

Get the view using the CouchbaseClient.getView() method -line 6-. As you can see I just use the name beer for the design document (and not dev_beer, Couchbase will know where to search since I am in development mode)

Create a query and set a limit (20) and ask the SDK to return the document itselfsetIncludeDocs(true) -line 8- The document will be returned from Couchbase server in the most efficient way

Ask the system to update the index before returning the result using query.setStale( Stale.FALSE ); -line 9-. Once again be careful when you use setStale method. Just to be sure here is the documentation about it : Index Updates and the stale Parameter

Execute the query - line 10

And use the result - lines 11-13

Conclusion

This example is limited to the creation of a view, you can take a look to the other methods related to design documents and views if you want to manage your design documents : getDesignDocument(), deleteDesignDocument(), ... .

11 comments:

Great post! But will be nice if couchbase client has a more type-safe and generificated API as all java-world apis. F.e. as http://code.google.com/p/async-couchdb-client/source/browse/trunk/acc/src/test/java/com/n1global/acc/examples/booksdb/. And how can I create map/reduce function in pure Java? F.e. http://code.google.com/p/async-couchdb-client/source/browse/trunk/acc/src/test/java/com/n1global/acc/examples/javamr ?

Today Couchbase does not have a supported API with Java "strong types/mapping". We let the developer chose how he wants to acheeve thisYou can use any JSON/Java Mapping tool to achieve this, for example GSON, Jackson, ...

I have started to work on the Hibernate OGM Data Provider for Couchbase:https://github.com/tgrall/hibernate-ogm/tree/couchbase-support

I am currently stucked on the association part and need more time to finish this.

Also I am working on a more simple (without class mapping) API to manipulate Document easily:https://github.com/tgrall/couchbase-document-api

Finally to answer your question about MapReduce in Java, same we do not have that yet.

Obviously the framework that you are exposing could be easily moved to Couchbase API.

I am doing the same thing on my machine, but the design document is not being created. In fact, client.createDesignDoc() is returning false (well, since it is HttpFuture, that value doesn't mean too much).

Is there any special settings to go along with design document creation?