Getting Started

Install HBase or Cassandra

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

Note: Cassandra doesn’t have the capability to modify the ColumnFamily schema while running, and can only be edited from the storage-conf.xml configuration while the cluster is down. Future versions of Cassandra have this planned.

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 default to creating the :attribute column family.

The following is a standard migration file that creates a table called "Books" with the default column family :attribute that has the following option 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)

the creation will change this behavior.

compression. The compression scheme you define here must be installed on the Hbase servers!

Migrating

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

  rake bigrecord:migrate

Column and Attribute Definition

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 notice here is that the first column ‘attribute:title’ had the column family prepended to it. This is identical to just passing the symbol :title to the column method, and the default behaviour is to prepend the column family (attribute) automatically if one is not defined. Furthermore, in Hbase, there’s the option of storing collections for a given column. This will return an array for the links attribute on a Book record.

Associations

There are also associations available in Bigrecord, as well as the ability to associate to Activerecord models. The following are a few models demonstrating this:

animal.rb 

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

    # Association attributes
    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, and 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, and 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 defining the :foreign_key (this is required for all associations).

Specifying return columns

There are two ways to define specific columns to be returned with your models: 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 returend
    view :default, :title, :author, :description
  end

Now, whenever you work with a Book record, it will only returned 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: A Bigrecord model will return all the columns within the default column family (when :view option is left blank, for example). 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.

Embedded Records

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!