Requirements

• Database installed, configured and running.  See HBase Getting Started or Cassandra Getting Started.

Installation

Method 1 (recommended): Install as a gem

1. Before proceeding with installation of the BigRecord gem or plugin, install the Bigrecord Driver gem and its dependencies, then start up a DRb server.  You may also wish to install BigIndex for Solr.
2. Add the following line into the Rails::Initializer.run do |config| block:

     config.gem "bigrecord", :source => "http://gemcutter.org"

3. Run the following command to install all the gems listed for your Rails app:

     [sudo] rake gems:install

4. Bootstrap Bigrecord into your project:

     script/generate bigrecord

5. Edit the config/bigrecord.yml[.sample] file (in Rails root) to match your database and BigRecord driver settings.

Method 2: Install as a plugin

1. Before proceeding with installation of the BigRecord gem or plugin, install the Bigrecord Driver gem and its dependencies, then start up a DRb server.  You may also wish to install BigIndex for Solr.
2. Run the following command to install it as a plugin:

      script/plugin install git://github.com/openplaces/bigrecord.git

3. Edit the config/bigrecord.yml[.sample] file (in Rails root) to match your database and BigRecord driver settings.

Usage

Generators

Once Bigrecord is working in your Rails project, you can use the following generators:

  script/generate bigrecord_model ModelName

This will add a model in app/models and a migration file in db/bigrecord_migrate. Note: This generator does not accept attributes.

  script/generate bigrecord_migration MigrationName

Creates a Bigrecord specific migration and adds it into db/bigrecord_migrate

Migration File

Although column-oriented databases are generally schema-less, certain ones (like Hbase) require the creation of tables and column families ahead of time. The individual columns, however, are defined in the model itself and can be modified dynamically without the need for migrations.

Unless you’re familiar with column families, the majority of use cases work perfectly fine within one column family. When you generate a bigrecord_model, it will create the :attribute column family by default.

The following is a standard migration file that creates a table called “Books” with the default column family :attribute that has a maximum of 100 versions and uses the ‘lzo’ compression scheme. Leave any options blank for the default value.

  class CreateBooks < BigRecord::Migration
    def self.up
      create_table :books, :force => true do |t|
        t.family :attribute, :versions => 100, :compression => 'lzo'
      end
    end

    def self.down
      drop_table :books
    end
  end

HBase column family options (HBase specific)

• versions: integer. By default, Hbase will store 3 versions of changes for any column family. Changing this value on the creation will change this behavior.
• compression: ‘none’, ‘gz’, ‘lzo’. Defaults to ‘none’. Since Hbase 0.20, column families can be stored using compression. The compression scheme you define here must be installed on the Hbase servers!

bigrecord:migrate

Run the following rake task to migrate your tables and column families up to the latest version:

  rake bigrecord:migrate

Column and Attribute Definitions

Now that you have your tables and column families all set up, you can begin adding columns to your model. The following is an example of a model named book.rb

  class Book < BigRecord::Base
    column 'attribute:title',   :string
    column :author,             :string
    column :description,        :string
    column :links,              :string,  :collection => true
  end

This simple model defines 4 columns of type string. An important thing to note: the first column ‘attribute:title’ has the column family prepended to it. This is identical to just passing the symbol :title to the column method, since the default behaviour is to prepend the default column family (attribute:) if one is not specified.

With BigRecord you can store collections in a column.  In the above example, the database will return an array for the links attribute.

Associations

BigRecord supports ActiveRecord-style associations, including associations with Activerecord models. Here are some examples:

  class Animal < BigRecord::Base
    # Standard attributes
    column :name,         :string
    column :type,         :integer
    column :description,  :string

    # Association attributes (note the _id)
    column :zoo_id,       :string
    column :trainer_id,   :integer

    # Associations
    belongs_to_big_record :zoo, :foreign_key => :zoo_id
    belongs_to :trainer,        :foreign_key => :trainer_id
  end

In this example, an Animal is related to Zoo and Trainer. Both Animal and Zoo are Bigrecord models, whereas Trainer is an Activerecord model. Notice here that we need to define both the association field for storing the information and the association itself. It’s also important to remember that Bigrecord models have their IDs stored as string, while Activerecord models use integers.

Once the association columns are defined, you define the associations themselves with either belongs_to_bigrecord or belongs_to_many and by specifying the :foreign_key (this is required for all associations).

Specifying default return columns

There are two ways to define which columns should be returned when querying the database: 1) at the model level and 2) during the query.

1. At the model level, a collection of columns are called named views, and are defined like the following:

  class Book < BigRecord::Base
    column :title,   :string
    column :author,             :string
    column :description,        :string
    column :links,              :string,  :collection => true

    view :front_page, :title, :author
    view :summary_page, :title, :author, :description

    # Override default if you don't want all columns returned
    view :default, :title, :author, :description
  end

Now, whenever you work with a Book record, it will only return the columns you specify according to the view option you pass. i.e.

  >> Book.find(:first, :view => :front_page)
  => #<Book id: "2e13f182-1085-495e-9841-fe5c84ae9992", attribute:title: "Hello Thar", attribute:author: "Greg">

  >> Book.find(:first, :view => :summary_page)
  => #<Book id: "2e13f182-1085-495e-9841-fe5c84ae9992", attribute:description: "Masterpiece!", attribute:title: "Hello Thar", attribute:author: "Greg">

  >> Book.find(:first, :view => :default)
  => #<Book id: "2e13f182-1085-495e-9841-fe5c84ae9992", attribute:description: "Masterpiece!", attribute:title: "Hello Thar", attribute:links: ["link1", "link2", "link3", "link4"], attribute:author: "Greg">

Note: By default, a Bigrecord model will return all the columns within the default column family (i.e. when :view option is left blank). You can override the :default name view to change this behaviour.

2. If you don’t want to define named views ahead of time, you can just pass an array of columns to the :columns option and it will return only those attributes:

  >> Book.find(:first, :columns => [:author, :description])
  => #<Book id: "2e13f182-1085-495e-9841-fe5c84ae9992", attribute:description: "Masterpiece!", attribute:author: "Greg">

As you may have noticed, this functionality is synonymous with the :select option in Activerecord.

Indexed Finders

To enable full-featured finders (e.g. find_by_name), you should install BigIndex for Solr.

At this point, usage patterns for a Bigrecord model are similar to that of an Activerecord model, and much of that documentation applies as well. Please refer to those and see if they work!