ホーム / Ruby Client Library

Ruby Client Library

Couchbase Server for Ruby Development

The Ruby client library provides fast access to documents in Couchbase Server 2.0. With JSON documents and Couchbase server 2.0 you have new ways to index and query data stored in the cluster through views. These view(s) can be accessed using the newly defined View class objects.

You can provide different perspectives to the data. For example, on the sample beer data, you can sort by category, ABV and so on depending on your taste!

Step 0: Get a Server

Get & Install Couchbase Server. Come back here when you're done.

Step 1: Get a Client Library

Step 1.0: Get libcouchbase

Before installing the the Ruby gem, the preview release of the Couchbase C Client Library (libcouchbase) will need to be installed for Linux and Mac OS X platforms. Windows dependencies are included in the gem, so this step maybe skipped. See the installation instructions for each platform for details.

Step 1.1: Install the Ruby Gem

The library can be run on MRI ruby version 1.8.7 up to 2.0.0. Installation is generally done through the gem command:

shell> gem install couchbase

Note that this version builds upon the libcouchbase 2.x release, which isn't backward compatible with 1.x.

To verify library version, run this command in your shell:

shell> ruby -rrubygems -rcouchbase -e 'puts Couchbase::VERSION'
1.3.1

Step 2: Try it out!

Hello Couchbase

To follow the tradition of programming tutorials, we’ll start with "Hello Couchbase". In the first example, we’ll connect to the Cluster, retrieve the document, print it out and modify it. This first example contains the full sourcecode, but in later example we’ll omit the preambula and assume we’re already connected to the cluster.

require 'rubygems'
require 'couchbase'

client = Couchbase.connect(:bucket => "beer-sample",
                           :hostname => "localhost")

beer = client.get("aass_brewery-juleol")
puts "#{beer['name']}, ABV: #{beer['abv']}"

beer['comment'] = "Random beer from Norway"
client.replace("aass_brewery-juleol", beer)

client.disconnect

Enter this listing in file hello.rband run it as follows:

shell> ruby hello.rb
Juleøl, ABV: 5.9

Working with Views

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 Ruby 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 two steps. First, you grab the design document definition from the cluster, second query view with options you need and use results. In its simplest form, it looks like this:

# 1: Get design document definition
ddoc = client.design_docs["beer"]
ddoc.views      #=> ["brewery_beers", "by_location"]

# 2: Query the view and use results
ddoc.brewery_beers.each do |row|
  puts row.key
  puts row.value
  puts row.id
  puts row.doc
end

This view contains only map function and it looks like

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

Note that the view request won’t be executed until you try to access the results. This means that you can pass view object (ddoc.brewery_beers here) without executing it.

See the tutorial for more on Views, including more examples of indexing and querying data.

Update Notes

Note that as of the 1.2.0+ release, you will need to update to libcouchbase version 2.0.0 or later.

Further Information

You will find additional documentation links above right and please provide any additional feedback on the Couchbase SDK Forums.

Then Learn More:

The full getting started guide will cover additional getting started information. From there, move on to the tutorial, which will show how to build a full application on Couchbase Server with a JSON dataset, sample views, and modifying data.