N1QL features are coming to more and more SDKs– now including Ruby. I'd like to give a quick intro of how structured queries in ruby work. At the moment library does not provide an ODM or some other high-level abstraction atop of it, but pretty much everything is possible otherwise.

Experimental support for N1QL has been added in recent minor release 1.3.12 though it is possible the API will change in final release. In the examples below I will show you how to work with it using new travel dataset, which is in the 4.0 developer preview. In this blog, I am assuming here that you have installed the most recent version of the ruby client (if not, please run “gem install -v 1.3.12“) and have a local Couchbase Server with the query service enabled.

First, lets establish a connection to the bucket:

The entry point for N1QL queries is Couchbase::Bucket#query method, which accepts a string in N1QL, and returns a hash with :rows and :meta keys, where the response from the server delivered. If there is an issue, the library will raise Couchbase::Error::Query exception with attached metadata to analyze the error.

For example, lets create primary index for whole dataset:

With the primary index defined we can fetch the documents by their keys:

To make the examples simpler, we can use the following function to strip :meta field and extract just values.

Lets answer some questions about this sample bucket. As you might remember, previous sample beer data contained about 7k documents, lets see how many this one has:

That's a great sandbox for our experiments. What kind of documents does it contain?

As homework assignment, you can explore the structure of the sample database further.  For now let us answer some more practical questions. What routes are available for someone in Los Angeles, who wants to see the Eiffel Tower in Paris? A straightforward implementation might look like this (assuming you know what LAX and CDG mean).

If you run this code, you will get a nicely formatted time table of all routes to see the famous tower as shown below. 

That is it for the intro at the moment, please leave your feedback about the new query.  In particular, please let us know what kind of Ruby support you'd love to see!

Posted by Sergey Avseyev, SDK Engineer, Couchbase


  1. looks nice, looking forward for a node.js sample 🙂

  2. Practical suggestions . Apropos , if anyone are searching for a service to merge PDF files , my business partner saw a tool here http://www.altomerge.com/.

Leave a reply