A.1 ActiveRecord_Relation (array of records)

A.1.1 All Array methods

ActiveRecord_Relations inherit from Array, so all Array methods work:

A.1.2 .where

ActiveRecord_Relation#where(Hash) ⇒ ActiveRecord_Relation

Call .where on an ActiveRecord_Relation to filter the array of records based on some criteria.

where returns an ActiveRecord_Relation based on the given Hash.

.where returns an ActiveRecord_Relation regardless of how many results there are. In particular, even if there is only one result, the return value will still be another ActiveRecord_Relation.
The argument to .where is usually a Hash:
- Filtering by an exact match within a column:
```
{ :id => 42 }
```
- Filter by multiple columns at once:
```
{ :photo_id => 23, :user_id => 42 }
```
- Filter using an Array (results will match any of the values in the Array):
```
{ :owner_id => [4, 8, 15 ] }
```
- Filtering within a range of values:
```
{ :dob => (1.year.ago..Date.today) }
```
```
{ :last_name => ("A".."C") }
```
- If you really want to, you can omit the curly brackets around the Hash for brevity, and Ruby will figure out what you mean. So, ultimately, you can write something like this:
```
Contact.where(:last_name => ("A".."C"))
```
  instead of this:
```
Contact.where({ :last_name => ("A".."C") })
```

Related Methods: .where.not, .or, .limit, .order

Full explanation

A.1.3 where.not

ActiveRecord_Relation#where.not(Hash) ⇒ ActiveRecord_Relation

Call .where.not on an ActiveRecord_Relation to filter the array of records to exclude records based on the given Hash. .where.not will return an ActiveRecord_Relation.

Contact.where({ :last_name => "Mouse" }).where.not({ :first_name => "Mickey" })

Returns an ActiveRecord_Relation.
The acceptable arguments to .not are the same as to .where; see that method for a list.

Related methods: .where, .order, .limit

Full explanation

A.1.4 .or

ActiveRecord_Relation#or(ActiveRecord_Relation) ⇒ ActiveRecord_Relation

Call .or on an ActiveRecord_Relation to combine the array of records with another array of records:

Returns an ActiveRecord_Relation.
The argument to .or must be another ActiveRecord_Relation from the same table.
Broadens the result set.

Contact.where({ :first_name => "Mickey" }).or(Contact.where({ :last_name => "Betina" }))

Full explanation

A.1.5 .order

ActiveRecord_Relation#order(Hash) ⇒ ActiveRecord_Relation

ActiveRecord_Relation.order(Symbol) ⇒ ActiveRecord_Relation

Call .order on an ActiveRecord_Relation to sort the array based on one or more columns. This method returns an ActiveRecord_Relation.

Contact.all.order({ :last_name => :asc, :first_name => :asc, :date_of_birth => :desc })

Returns an ActiveRecord_Relation.
The argument to .order is usually a Hash.
- The keys in the Hash must be Symbols that match names of columns in the table. These are the columns that will be used for sorting. If there are multiple keys, the order in which they are provided will be used to break ties.
- The value associated to each key must be either :asc (for ascending order) or :desc (for descending order).
The argument to .order can also just be one Symbol, a column name.

Contact.all.order(:last_name)

In that case, :asc order is assumed.

Full explanation

A.1.6 .limit

ActiveRecord_Relation#limit(Integer) ⇒ ActiveRecord_Relation

Call .limit on an ActiveRecord_Relation to cap the number of records in the array.

Returns an ActiveRecord_Relation.
The argument to .limit must be an Integer.

Contact.where({ :last_name => "Mouse" }).limit(10)

Full explanation

A.1.7 .offset

ActiveRecord_Relation#offset(Integer) ⇒ ActiveRecord_Relation

Call .offset on an ActiveRecord_Relation to discard the first few records in the array:

Returns an ActiveRecord_Relation.
The argument to .offset must be an Integer.

Contact.where({ :last_name => "Mouse" }).offset(10).limit(10)

Full explanation

A.1.8 .map_relation_to_array

ActiveRecord_Relation#map_relation_to_array(Symbol) ⇒ Array

Call .map_relation_to_array on an ActiveRecord_Relation to retrieve the values stored in just one column of the records, and discard all other data.

.map_relation_to_array returns a regular Ruby Array of scalar values in the column.
- Not a single value, even if there was only one record in the ActiveRecord_Relation.
- Not an ActiveRecord_Relation, so you can no longer use methods like .where, .order, etc. You can use Array methods like .sort, .sample, etc.
The argument to .map_relation_to_array must be a Symbol that matches the name of a column in the table.
You cannot call .map_relation_to_array on an individual ActiveRecord row. If you want the value in a column for an individual row, simply call the accessor method directly:

Contact.all.map_relation_to_array(:last_name) # => ["Betina", "Mouse", "Woods"]

# for an array of records
people.last_name # undefined method for array; bad
people.map_relation_to_array(:last_name) # => ["Betina", "Woods"]; good

Full explanation

A.1.9 .maximum

ActiveRecord_Relation#maximum(Symbol) ⇒ Object

Call .maximum on an ActiveRecord_Relation to grab and return the biggest value of a particular column.

User.all.maximun(:age)
# => 102

Returns a value from an ActiveRecord column.

Full explanation

A.1.10 .minimum

ActiveRecord_Relation#minimum(Symbol) ⇒ Object

Call .minimum on an ActiveRecord_Relation to grab and return the smallest value of a particular column.

Photo.all.minimum(:caption) 
# => "... a mind needs books as a sword needs a whetstone, if it is to keep its edge."

Returns a value from an ActiveRecord column.

Full explanation

A.1.11 .sum

ActiveRecord_Relation#sum(Symbol) ⇒ Integer or ⇒ Float or ⇒ String

Call .sum on an ActiveRecord_Relation to find the sum of the values in a single column:

@poem.scores.sum(:points)

Returns an Integer or Float (or even a String), depending on datatype of the column that was summed.
The argument to .sum must be a Symbol that matches the name of a column in the table.

Full explanation

A.1.12 .average

ActiveRecord_Relation#average(Symbol) ⇒ Integer or ⇒ Float

Call .average on an ActiveRecord_Relation to find the mean of the values in a single column:

@restaurant.reviews.average(:rating)

Returns an Integer or Float, depending on datatype of the column that was averaged.
The argument to .average must be a Symbol that matches the name of a column in the table.

Full explanation