CriteriaQuery is an extension to the ActiveRecord find mechanism. It allows object-oriented construction of queries.

In short, it lets you write:

Person.query.name_like('name').join('address').city_like('city')

instead of

Person.find(:all, :conditions=>['people.name LIKE ? AND addresses.city LIKE ?', 'name', 'city'], :include=>[:city])

or

Person.query.name_like('name').join('address').city_like('city').join('state').name_eq('state')

instead of

Person.find(:all, :conditions=>['people.name LIKE ? AND addresses.city LIKE ? AND states.name=?', 'name', 'city', 'state'], :include=>[:city=>[:state]])

This becomes increasingly useful for more complex queries, especially if the queries need to be dynamically constructed based on user input (see the README for examples).

Criteria Queries support joins across multiple associations, as well as using the same table in multiple joins.