Module: ActiveRecord::Calculations

Included in:
Relation
Defined in:
lib/active_record/relation/calculations.rb

Instance Method Summary collapse

Instance Method Details

#average(column_name, options = {}) ⇒ Object

Calculates the average value on a given column. Returns nil if there’s no row. See calculate for examples with options.

Person.average('age') # => 35.8



31
32
33
 
# File 'lib/active_record/relation/calculations.rb', line 31

def average(column_name, options = {})
  calculate(:average, column_name, options)
end

#calculate(operation, column_name, options = {}) ⇒ Object

This calculates aggregate values in the given column. Methods for count, sum, average, minimum, and maximum have been added as shortcuts.

There are two basic forms of output:

* Single aggregate value: The single value is type cast to Fixnum for COUNT, Float
  for AVG, and the given column's type for everything else.

* Grouped values: This returns an ordered hash of the values and groups them. It
  takes either a column name, or the name of a belongs_to association.

    values = Person.group('last_name').maximum(:age)
    puts values["Drake"]
    # => 43

    drake  = Family.find_by(last_name: 'Drake')
    values = Person.group(:family).maximum(:age) # Person belongs_to :family
    puts values[drake]
    # => 43

    values.each do |family, max_age|
    ...
    end

Person.calculate(:count, :all) # The same as Person.count
Person.average(:age) # SELECT AVG(age) FROM people...

# Selects the minimum age for any family without any minors
Person.group(:last_name).having("min(age) > 17").minimum(:age)

Person.sum("2 * age")



101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
 
# File 'lib/active_record/relation/calculations.rb', line 101

def calculate(operation, column_name, options = {})
  relation = with_default_scope

  if relation.equal?(self)
    if has_include?(column_name)
      construct_relation_for_association_calculations.calculate(operation, column_name, options)
    else
      perform_calculation(operation, column_name, options)
    end
  else
    relation.calculate(operation, column_name, options)
  end
rescue ThrowResult
  0
end

#count(column_name = nil, options = {}) ⇒ Object

Count the records.

Person.count
# => the total count of all people

Person.count(:age)
# => returns the total count of all people whose age is present in database

Person.count(:all)
# => performs a COUNT(*) (:all is an alias for '*')

Person.distinct.count(:age)
# => counts the number of different age values

If count is used with group, it returns a Hash whose keys represent the aggregated column, and the values are the respective amounts:

Person.group(:city).count
# => { 'Rome' => 5, 'Paris' => 3 }



22
23
24
25
 
# File 'lib/active_record/relation/calculations.rb', line 22

def count(column_name = nil, options = {})
  column_name, options = nil, column_name if column_name.is_a?(Hash)
  calculate(:count, column_name, options)
end

#ids ⇒ Object

Pluck all the ID’s for the relation using the table’s primary key

Person.ids # SELECT people.id FROM people
Person.joins(:companies).ids # SELECT people.id FROM people INNER JOIN companies ON companies.person_id = people.id



188
189
190
 
# File 'lib/active_record/relation/calculations.rb', line 188

def ids
  pluck primary_key
end

#maximum(column_name, options = {}) ⇒ Object

Calculates the maximum value on a given column. The value is returned with the same data type of the column, or nil if there’s no row. See calculate for examples with options.

Person.maximum('age') # => 93



49
50
51
 
# File 'lib/active_record/relation/calculations.rb', line 49

def maximum(column_name, options = {})
  calculate(:maximum, column_name, options)
end

#minimum(column_name, options = {}) ⇒ Object

Calculates the minimum value on a given column. The value is returned with the same data type of the column, or nil if there’s no row. See calculate for examples with options.

Person.minimum('age') # => 7



40
41
42
 
# File 'lib/active_record/relation/calculations.rb', line 40

def minimum(column_name, options = {})
  calculate(:minimum, column_name, options)
end

#pluck(*column_names) ⇒ Object

Use pluck as a shortcut to select one or more attributes without loading a bunch of records just to grab the attributes you want.

Person.pluck(:name)

instead of

Person.all.map(&:name)

Pluck returns an Array of attribute values type-casted to match the plucked column names, if they can be deduced. Plucking an SQL fragment returns String values by default.

Person.pluck(:id)
# SELECT people.id FROM people
# => [1, 2, 3]

Person.pluck(:id, :name)
# SELECT people.id, people.name FROM people
# => [[1, 'David'], [2, 'Jeremy'], [3, 'Jose']]

Person.pluck('DISTINCT role')
# SELECT DISTINCT role FROM people
# => ['admin', 'member', 'guest']

Person.where(age: 21).limit(5).pluck(:id)
# SELECT people.id FROM people WHERE people.age = 21 LIMIT 5
# => [2, 3]

Person.pluck('DATEDIFF(updated_at, created_at)')
# SELECT DATEDIFF(updated_at, created_at) FROM people
# => ['0', '27761', '173']



150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
 
# File 'lib/active_record/relation/calculations.rb', line 150

def pluck(*column_names)
  column_names.map! do |column_name|
    if column_name.is_a?(Symbol) && self.column_names.include?(column_name.to_s)
      "#{connection.quote_table_name(table_name)}.#{connection.quote_column_name(column_name)}"
    else
      column_name
    end
  end

  if has_include?(column_names.first)
    construct_relation_for_association_calculations.pluck(*column_names)
  else
    relation = spawn
    relation.select_values = column_names
    result = klass.connection.select_all(relation.arel, nil, bind_values)
    columns = result.columns.map do |key|
      klass.column_types.fetch(key) {
        result.column_types.fetch(key) {
          Class.new { def type_cast(v); v; end }.new
        }
      }
    end

    result = result.map do |attributes|
      values = klass.initialize_attributes(attributes).values

      columns.zip(values).map do |column, value|
        column.type_cast(value)
      end
    end
    columns.one? ? result.map!(&:first) : result
  end
end

#sum(*args) ⇒ Object

Calculates the sum of values on a given column. The value is returned with the same data type of the column, 0 if there’s no row. See calculate for examples with options.

Person.sum('age') # => 4562



58
59
60
61
62
63
64
65
66
67
68
 
# File 'lib/active_record/relation/calculations.rb', line 58

def sum(*args)
  if block_given?
    ActiveSupport::Deprecation.warn(
      "Calling #sum with a block is deprecated and will be removed in Rails 4.1. " \
      "If you want to perform sum calculation over the array of elements, use `to_a.sum(&block)`."
    )
    self.to_a.sum(*args) {|*block_args| yield(*block_args)}
  else
    calculate(:sum, *args)
  end
end