Active record query interface

This Guide is based on Rails 3.0. Some of the code shown here will not work in other versions of Rails.

If you’re used to using raw SQL to find database records then, generally, you will find that there are better ways to carry out the same operations in Rails. Active Record insulates you from the need to use SQL in most cases.

Code examples throughout this guide will refer to one or more of the following models:

All of the following models use id as the primary key, unless specified otherwise.

Class Client < ActiveRecord::Base
has_one :address
has_many :orders
has_and_belongs_to_many :roles
End
class Address < ActiveRecord::Base
belongs_to :client
End
class Order < ActiveRecord::Base
belongs_to :client, :counter_cache => true
End
class Role < ActiveRecord::Base
has_and_belongs_to_many :clients
End
Active Record will perform queries on the database for

you and is compatible with most database systems (MySQL, PostgreSQL and SQLite to name a few). Regardless of which database system you’re using, the Active Record method format will always be the same.

1 Retrieving Objects from the Database
To retrieve objects from the database, Active Record provides several finder methods. Each finder method allows you to pass arguments into it to perform certain queries on your database without writing raw SQL.

The methods are:

Where
Select
Group
Order
Limit
Offset
Joins
Includes
Lock
Readonly
From
Having
All of the above methods return an instance of ActiveRecord::Relation.

Primary operation of Model. find(options) can be summarized as:

Convert the supplied options to an equivalent SQL query.
Fire the SQL query and retrieve the corresponding results from the database.
Instantiate the equivalent Ruby object of the appropriate model for every resulting row.
Run after_find callbacks if any.
1.1 Retrieving a Single Object
Active Record lets you retrieve a single object using three different ways.

1.1.1 Using a Primary Key

Using Model. find(primary_key), you can retrieve the object corresponding to the supplied primary key and matching the supplied options (if any). For example:

# Find the client with primary key (id) 10.
Client = Client. find(10)
=> # “Ryan”>
SQL equivalent of the above is:

SELECT * FROM clients WHERE (clients. id = 10)
Model. find(primary_key) will raise an ActiveRecord::RecordNotFound exception if no matching record is found.

1.1.2 first

Model. first finds the first record matched by the supplied options. For example:

Client = Client. first
=> #
SQL equivalent of the above is:

SELECT * FROM clients LIMIT 1
Model. first returns nil if no matching record is found. No exception will be raised.

1.1.3 last

Model. last finds the last record matched by the supplied options. For example:

Client = Client. last
=> #
SQL equivalent of the above is:

SELECT * FROM clients ORDER BY clients. id DESC LIMIT 1
Model. last returns nil if no matching record is found. No exception will be raised.

1.2 Retrieving Multiple Objects
1.2.1 Using Multiple Primary Keys

Model. find(array_of_primary_key) also accepts an array of primary keys. An array of all the matching records for the supplied primary keys is returned. For example:

# Find the clients with primary keys 1 and 10.
Client = Client. find(1, 10) # Or even Client. find([1, 10])
=> [# “Lifo”>, # “Ryan”>]
SQL equivalent of the above is:

SELECT * FROM clients WHERE (clients. id IN (1,10))
Model.



Active record query interface