Blog Post

I've installed Couchbase Server 2.0, now what?

Published

Setting up Couchbase Server can be really easy but if you haven’t installed it yet, here are  step-by-step instructions. If you’re new to Couchbase Server 2.0 and are wondering what’s new, this blog will give you a quick tour of the product and explain a few key concepts. So let’s get started.

Once you’ve installed Couchbase Server 2.0, you should login to the couchbase admin UI and check it out. The ‘Cluster Overview’ tab gives you a high-level view of your cluster resources including the amount of RAM and disk used, cluster throughput, disk fetches per second and status of the servers in the cluster - number of servers failed over, pending rebalance or down.

Cluster overview in Couchbase Server Admin Console

Data in Couchbase Server is stored in logical containers called ‘buckets’. For those of you familiar with relational databases, you can think of buckets as similar to databases. In the screenshot below, to create a new bucket, go to the ‘Data Buckets’ tab, click the ‘Create New Data Bucket’ button and follow the instructions here. In case your RAM quota is already used by existing buckets, you may need to go to the existing bucket and create some room.

Creating a new bucket in Couchbase Server

For the rest of this blog, we’ll focus on the beer-sample bucket that includes documents about beers and breweries. You might come across some interesting beers. As shown in Figure 2, if you have installed the beer-sample bucket, you will notice that this sample bucket has 7303 documents. If you haven’t installed the beer-sample bucket yet, you can still install it through the admin console - go to the ‘Settings’ tab, click on ‘Sample Buckets’ and select ‘beer-sample’ to install it.

Installing sample buckets in Couchbase Server

The beer-sample bucket contains many JSON documents - let’s explore these documents and take a closer peek at a couple of them. To view the documents in any Couchbase bucket (the beer-sample bucket in this case), click the ‘Documents’ button as shown below. 

 

Data Buckets in Couchbase Server

By choosing the name of the bucket from the dropdown list, you can navigate between documents in different buckets. You can also page through documents, create new documents or edit and delete current documents. Additionally, you can filter documents by key range or lookup a particular document by id. (Some screenshots below)

List of documents in the beer-sample bucket

Filtering documents and looking up documents by ID

Now, let’s try to edit the 2nd document with key ‘21st_amendment_brewery_cafe-21a_ipa’ - click the ‘Edit’ button corresponding to the 2nd document. This takes us to Couchbase’s document editor as shown below.

Editing a particular JSON document

Couchbase’s document editor allows you to delete a document, save any changes to the current document or save the doc with a different document ID. The document shown in the figure above has id ‘21st_amendment_brewery_cafe-21a_ipa’. The 'type' attribute shows that the document type is a beer document and it has various different JSON fields including the name, alcohol by volume (abv) and other categorization data.

Now, let’s find out more about the brewery this beer was made. The brewery_id can be obtained from the beer document (‘21st_amendment_brewery_cafe’ in this case ). To search for a document with a particular id, type the id in the textbox as shown in the figure below and it will automatically filter the results for you. You will see all the docs with keys starting with ‘21st_amendment_brewery_cafe’. 

Looking up documents based on documentID

Brewery document with different schema than Beer document

Now let’s talk about indexing and querying. With Couchbase Server 2.0, you can easily index and query JSON documents. Indexes are defined using design documents and views. You create design documents on a per-bucket basis. Each design document can contain multiple views. Each view includes a Map and optionally a Reduce function, both written in Javascript.

Views in Couchbase are built asynchronously and hence are eventually indexed. By default, queries on these views are eventually consistent with respect to document updates. However, if your application requires data to be indexed immediately, Couchbase SDKs offer an option to control this behavior on a per operation basis.

 

The beer-sample bucket comes with some predefined production views as below  - these views are defined inside the 'beer' design document. Typically, when writing a new Couchbase view, you will start with a development view and then will move it to production once you have tested it. Production views cannot be edited - they need to be copied to dev before any changes can be made. 

 

Views in the beer-sample bucket

Now, let’s take a look at what do each of these views mean. By clicking the ‘Show’ button corresponding to each view, you can look at the view definition. First, let’s look at the ‘brewery_beers’ view.

View definition and results of the query on ‘brewery_beers’ view

The brewery_beers view outputs a key and value list of breweries and beers. Each key is a complex key. You can query the view by clicking the ‘Show Results’ button. Since this is a production view, Couchbase Server applies the mapreduce javascript function to all the documents in the Couchbase cluster.

The map function takes as input the doc and meta objects. The doc object can be used for accessing the fields in the document. The meta field can be used for accessing metadata associated with the document containing document ID, expiry time, revision and other information. In the example above, if the document is of type ‘brewery’, we emit a single value that has the brewery name (meta.id). If the document is of type ‘beer’, we test whether the beer document has a brewery_id and emit a list that contains two values:  the brewery name (doc.brewery_id) and the beer name (meta.id).

So Couchbase outputs the brewery ID for brewery document types, and the brewery ID and beer ID for beer document types. Once a view is defined in Couchbase Server, you can query data using this materialized view and lookup information based on various filters. 

Definition of the by_location view

The second view ‘by_location’ outputs the brewery location, accounting for missing fields in the source data. The output creates information either by country, by country and state, or by country, state and city. The view also includes the built-in reduce ‘_count’ function in the reduce portion of the view to count the number of returned results. You can also use this view to count by county, country and state, etc using grouping.

Now, let’s try to create another view to list beers sorted by alcohol by volume (abv) ratings. To create the view, click on the ‘Create Development View’ button in the ‘Views’ tab as shown below. Don’t forget to select the 'beer-sample' bucket.

Creating a new view in Couchbase Server

Design document ‘dev_beers’ and ‘alcoholByVolume’ view

After clicking ‘Save’ you can edit the view by clicking the ‘Edit’ button.

 

Development Views in Couchbase Server

This will take you to the view editor as shown below. Type in your Map function in javascript, and then click the ‘Save’ button to save the view definition and the ‘Show Results’ button to show view results.

 

View editor to edit the view

If we take a closer look at the view Map function, it emits the ‘abv’ attribute and the name of the beer. We emit these values only for beer type documents. Based on Couchbase’s view writing best practices, you should always test for null field values before emitting them in a view. You can also filter and aggregate your view results in Couchbase server - in this case we are sorting the view by descending order.

View beersbyvolume with subset results

And finally, now that you have tried out your view and are ready to use it, you can ‘Publish’ it to production. 

In addition to indexing and querying, another exciting feature in Couchbase Server 2.0 is the addition of Cross Data Center Replication (XDCR). Using this feature you can replicate active data to multiple, geographically diverse datacenters either for disaster recovery or to bring data closer to its users for faster data access. I won’t go into too much detail about cross datacenter replication in this blog, but you can read more about how it works and how to set it up here.

What's next?

Quiet frankly, exploring the beer-sample bucket and writing a simple Couchbase view is pretty easy. Now that you’ve gotten started, try to build a rich app with the power of Couchbase Server 2.0. From here we recommend you take a look at the developer section of our website to learn more and our developer guide.

We expect to see a lot more applications using Couchbase Server 2.0 in the coming months, especially now that the Couchbase Ribbon has been announced. Hopefully this blog will inspire you to build a new 2.0 based app and show it off. Enjoy and happy coding with Couchbase Server 2.0! 

Some additional resources for you.