= Rhino - a Ruby ORM for HBase

Rhino is a Ruby object-relational mapping (ORM) for HBase[http://www.hbase.org].

=== Support & contact

Author: Quinn Slack qslack@qslack.com[mailto:qslack@qslack.com]

Contributors: Dru Jensen

== Getting started

=== Download Rhino

  git clone git://github.com/sqs/rhino.git

=== Installing HBase and Thrift

Since Rhino uses the HBase Thrift API, you must first install both HBase and Thrift. Downloading the latest trunk revisions of each is recommended, but if you encounter problems, try using the latest stable release instead. Here are the basic steps for installing both.

==== Installing HBase
  
  svn co http://svn.apache.org/repos/asf/hadoop/hbase/trunk hbase-core-trunk
  cd hbase-core-trunk
  ant
  
{More installation instructions}[http://wiki.apache.org/hadoop/Hbase/10Minutes] are available on the HBase Wiki.

==== Installing Thrift

Thrift[http://developers.facebook.com/thrift/] also requires the Boost C++ libraries; you'll have to get those on your own if your system does not have them.

  svn co http://svn.facebook.com/svnroot/thrift/trunk/ thrift-trunk
  cd thrift-trunk
  ./bootstrap.sh
  ./configure && make && sudo make install
  cd lib/rb
  sudo ruby setup.rb

==== Starting the HBase and Thrift servers

Once you have installed HBase and Thrift, start HBase, then start the Thrift server. From the root HBase directory, run these commands:

  bin/start-hbase.sh
  bin/hbase thrift start
  
Both servers need to be running to use Rhino. Occasionally, the Thrift server will be unable to connect to HBase. In that case, stop the Thrift server (ctrl-C), stop the HBase server (<tt>bin/stop-hbase.sh</tt>), and then rerun the above commands to restart both. To verify that HBase is running, try running the HBase shell (<tt>bin/hbase shell</tt>).

==== Loading Rhino

Since Rhino is not yet packaged as a gem, you will have to <tt>require 'PATH_TO_RHINO/lib/rhino.rb'</tt> in your scripts.
  
== Usage  

=== Connect to HBase

The following code points Rhino to the Thrift server you just started (which by default listens on localhost:9090).
  
  Rhino::Model.connect('localhost', 9090)
  
=== Describe your table

A class definition like:

  class Page < Rhino::Model
    include Rhino::Constraints

    column_family :title
    column_family :contents
    column_family :links
    column_family :meta
    column_family :images
    
    alias_attribute :author, 'meta:author'

    has_many :links, Link
    has_many :images, Image

    constraint(:title_required) { |page| page.title and !page.title.empty? }
  end

...is mapped to the following HBase table (described in {HBase Query Language}[http://wiki.apache.org/lucene-hadoop/HBase/HBaseShell]

  CREATE TABLE pages(title:, contents:, links:, meta:, images:);
  
Or, in version 0.2's JRuby shell language:
  
  create 'pages', 'title', 'contents', 'links', 'meta', 'images'

=== Basic operations

==== Getting records

  page = Page.get('some-page')
  all_pages = Page.get_all()
  
==== Creating new records

  # data can be specified in the second argument of Page.new...
  page = Page.new('the-row-key', {:title=>"my title"})
  # ...or as attributes on the model
  page.contents = "<p>welcome</p>"
  page.save

==== Reading and updating attributes

  page = Page.get('some-key')
  puts "the old title is: #{page.title}"
  page.title = "another title"
  page.save
  puts "the new title is: #{page.title}"

You can also read from and write to specific columns in a column family.
Since we already defined the <tt>meta:</tt> column family, Rhino knows we want to set the <tt>meta:author</tt> column:

  page = Page.get('some-key')
  page.meta_author = "John Doe"
  page.save
  puts "the author is: #{page.meta_author}"
  
=== has_many and belongs_to

In the model definition above, we stated that a Page <tt>has_many :links</tt> and <tt>has_many :images</tt>. We can 
define what a Link and an Image is with greater detail now.

  class Link < Rhino::Cell
    belongs_to :page
  
    def url
      url_parts = key.split('/')
      backwards_host = url_parts.shift
      path = url_parts.join('/')
      host = backwards_host.split('.').reverse.join('.')
      "http://#{host}/#{path}"
    end
  end

  class Image < Rhino::Cell
    belongs_to :page
  end
  
Now that we've defined <tt>Link</tt> and <tt>Image</tt>, we can work with them easily. The following code adds a link to the page <tt>com.example</tt>, which when written to HBase becomes a cell in the <tt>links:</tt> column family named <tt>links:com.google</tt> with the contents <tt>search engine</tt>.

  page = Page.get('com.example')
  page.links.create('com.google', 'search engine')
  
You can also iterate over the collection of links. In this example, we use <tt>Link#url</tt>, a method we defined on the Link class
to convert from the common <tt>com.example/path</tt> URL storage style to <tt>example.com/path</tt>.

  page.links.each do |link|
    puts "Link to #{link.url} with text: '#{link.contents}'"
  end
  
You can also get a specific link.

  google_link_text = page.get('com.google').contents

=== Setting timestamps and retrieving by timestamp
  
First, let's create some Pages with different timestamps.

  a_week_ago = Time.now - 7 * 24 * 3600
  a_month_ago = Time.now - 30 * 24 * 3600
  
  newer_page = Page.create('google.com', {:title=>'newer google'}, {:timestamp=>a_week_ago})
  older_page = Page.create('google.com', {:title=>'older google'}, {:timestamp=>a_month_ago})
  
Now you can <tt>get</tt> by the timestamps you just set.

  Page.get('google.com', :timestamp=>a_week_ago).title # => "newer google"
  Page.get('google.com', :timestamp=>a_month_ago).title # => "older google"
  
If you call <tt>get</tt> with no arguments, you will get the most recent Page.

  Page.get('google.com').title # => "newer google"
  
== More information

Read the specs in the spec/ directory to see more usage examples. Also look at the spec models in spec/spec_helper.rb.