Navigating Object Graphs in Rails

2007-02-13T21:26:48-05:00

One of the more powerful and complicated features that good ORM frameworks have is the ability to easily navigate through relationships when constructing queries. What we'd like out of our ORM framework is to be able to build these complicated queries without having to write any SQL, and as luck would have it, Ruby on Rails allows us to do just that.

We are going to build a simple working example, so if you have Rails 1.2 and MySQL installed, feel free to play along at home. Our example is a bare minimum simple model representing an online store. What we want to do is to get all of the users who have ordered a given product. Seems simple enough, but it will require us to go across a few different models. So first, let's go over what the model of our database will be.

First, we have a simple user table:

+----------+--------------+------+-----+---------+----------------+
| Field    | Type         | Null | Key | Default | Extra          |
+----------+--------------+------+-----+---------+----------------+
| id       | int(11)      | NO   | PRI | NULL    | auto_increment |
| username | varchar(255) | YES  |     | NULL    |                |
+----------+--------------+------+-----+---------+----------------+

Just two fields, a primary key and a username. Obviously a real world database would have more, but they don't effect what we are doing here. Next, we have a products table:

+-------+--------------+------+-----+---------+----------------+
| Field | Type         | Null | Key | Default | Extra          |
+-------+--------------+------+-----+---------+----------------+
| id    | int(11)      | NO   | PRI | NULL    | auto_increment |
| name  | varchar(255) | YES  |     | NULL    |                |
| price | decimal(8,2) | YES  |     | NULL    |                |
+-------+--------------+------+-----+---------+----------------+

The fields should be pretty self-explanatory. We have an orders table:

+---------+---------+------+-----+---------+----------------+
| Field   | Type    | Null | Key | Default | Extra          |
+---------+---------+------+-----+---------+----------------+
| id      | int(11) | NO   | PRI | NULL    | auto_increment |
| user_id | int(11) | YES  |     | NULL    |                |
+---------+---------+------+-----+---------+----------------+

In this case user_id is a foreign key to the user who placed the order. And lastly, we have a table to hold the line items for an order:

+------------+---------+------+-----+---------+----------------+
| Field      | Type    | Null | Key | Default | Extra          |
+------------+---------+------+-----+---------+----------------+
| id         | int(11) | NO   | PRI | NULL    | auto_increment |
| order_id   | int(11) | YES  |     | NULL    |                |
| product_id | int(11) | YES  |     | NULL    |                |
| quantity   | int(11) | YES  |     | NULL    |                |
+------------+---------+------+-----+---------+----------------+

A line item has a foreign key to an order and a product. So, the task at hand is to get all users who have ordered a given product, so we'll need to join all these tables to get our data. Now let's build the rails app and make it happen:

C:\ruby\projects>rails store
C:\ruby\projects\store>cd store

Now let's create a database and user for our store:

C:\ruby\projects\store>mysql -u root -p
Enter password: ********
Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is 36 to server version: 5.0.27-community-nt

Type 'help;' or '\h' for help. Type '\c' to clear the buffer.

mysql> CREATE DATABASE store_development;
Query OK, 1 row affected (0.00 sec)

mysql> CREATE USER store@localhost;
Query OK, 0 rows affected (0.00 sec)

mysql> GRANT ALL PRIVILEGES ON store_development.* TO store@localhost;
Query OK, 0 rows affected (0.00 sec)

mysql> quit
Bye

Now we'll log in with our new user to make sure everything is working:

C:\ruby\projects>mysql -u store store_development
Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is 12 to server version: 5.0.27-community-nt

Type 'help;' or '\h' for help. Type '\c' to clear the buffer.

mysql> quit
Bye

Ok, all is well, let's edit the rails config to use this database:

C:\ruby\projects\store>notepad config\database.yml

NOTEPAD? NOTEPAD!!? I know, I know, what can I say. I'm on Windows and the arrogant makers of TextMate are going to port it to Windows. But fear not, I am not using the regular notepad, I'm using Notepad++. Notepad++, ah ha! It is ++, so it must be better! Well, it allows you to edit multiple files at once and has syntax highlighting, so until intype gets the ability to edit multiple files at once, has a file explorer and can do undo/redo, Notepad++ will have to do. So make the development settings look like this:

development:
  adapter: mysql
  database: store_development
  username: store
  password:
  host: localhost

For safety's sake, check to make sure the DB connection is working.

C:\ruby\projects\store>rake db:migrate

This command should return nothing (except possibly a warning about 'require_gem', buy you can safely ignore that). As they say, no news is good news. If you do get some kind of error, do not pass go, do not collect $200, figure out what is wrong.

Ok time, to create our objects

C:\ruby\projects\store>ruby script/generate model user
C:\ruby\projects\store>notepad db\migrate\001_create_users.rb

001_create_users.rb will contain the standard migration skeleton, which looks like this:

class CreateUsers < ActiveRecord::Migration
  def self.up
    create_table :users do |t|
    end
  end

  def self.down
    drop_table :users
  end
end

So we'll just add one line between the create_table and the end, that contains this:

t.column :username, :string

Each subsequent migration will contain only one table, so I'll just give what goes inside the create table. We are going to create the simplest possible model, with as few proprties as possible.

C:\ruby\projects\store>ruby script/generate model product
C:\ruby\projects\store>notepad db\migrate\002_create_products.rb    

t.column :name, :string
t.column :price, :decimal, :precision => 8, :scale => 2

C:\ruby\projects\store>ruby script/generate model order
C:\ruby\projects\store>notepad db\migrate\003_create_orders.rb

t.column :user_id, :integer

C:\ruby\projects\store>ruby script/generate model line_item
C:\ruby\projects\store>notepad db\migrate\004_create_line_items.rb    

t.column :order_id, :integer
t.column :product_id, :integer
t.column :quantity, :integer

Now we'll run the rake task to create the database structure.

C:\ruby\projects\store>rake db:migrate

Now that we have the database structure, we need to edit the code for the models to define the relationships.

C:\ruby\projects\store>notepad app\models\order.rb

class Order < ActiveRecord::Base
  belongs_to :user
end

C:\ruby\projects\store>notepad app\models\product.rb

class Product < ActiveRecord::Base
  has_many :line_items
end

C:\ruby\projects\store>notepad app\models\line_item.rb

class LineItem < ActiveRecord::Base
  belongs_to :order
  belongs_to :product
end

Now that we have the model defined, let's create some test data:

C:\ruby\projects\store>ruby script/generate migration create_test_data

class CreateTestData < ActiveRecord::Migration
  def self.up
    #Create a product
    foo = Product.new(:name => 'foo', :price => 9.99)
    foo.save

    #Create another product
    bar = Product.new(:name => 'bar', :price => 14.99)
    bar.save

    #Create our first user, me
    pbarry = User.new(:username => 'pbarry')
    pbarry.save

    #Create some other guy
    jsmith = User.new(:username => 'jsmith')
    jsmith.save

    #Create our first order
    #notice all the line items and the order get saved with just one order.save
    order = Order.new(:user => pbarry)
    order.line_items << LineItem.new(:product => foo, :quantity => 2, :order => order)
    order.line_items << LineItem.new(:product => bar, :quantity => 1, :order => order)
    order.save

    #What can I say, I just can't get enough foo.
    order = Order.new(:user => pbarry)
    order.line_items << LineItem.new(:product => foo, :quantity => 1, :order => order)
    order.save

    #Random guy order's something too
    order = Order.new(:user => jsmith)
    order.line_items << LineItem.new(:product => bar, :quantity => 1, :order => order)
    order.save
  end

  def self.down
  end
end

So now let's run this migration:

C:\ruby\projects\store>rake db:migrate

Now our database is full of data. Go ahead and check if you don't believe me. And we didn't write any SQL. Nice.

Now here's where the fun starts. Let's get those users who have ordered 'foo':

C:\ruby\projects\store>ruby script/console
Loading development environment.
>> User.find(:all, :include => {:orders => {:line_items => :product}}, \
?> :conditions => ["products.name = ?", 'foo'])[0].username
=> "pbarry"
>>

Whammy! That was easy. We didn't write any SQL to make any of those joins happen. The nested hashes in :include did all the work. We also didn't have to do anything funky with the results, we got back an array of users, just like we asked for. And we did it all in one line of code (ok two lines, broken only for the sake of readability). Not bad.

PaulBarry.com - Navigating Object Graphs in Rails

Navigating Object Graphs in Rails