| Module | ActiveRecord::Calculations::ClassMethods |
| In: |
vendor/rails/activerecord/lib/active_record/calculations.rb
|
Calculates the average value on a given column. The value is returned as a float. See calculate for examples with options.
Person.average('age')
# File vendor/rails/activerecord/lib/active_record/calculations.rb, line 52
52: def average(column_name, options = {})
53: calculate(:avg, column_name, options)
54: end
This calculates aggregate values in the given column. Methods for count, sum, average, minimum, and maximum have been added as shortcuts. Options such as :conditions, :order, :group, :having, and :joins can be passed to customize the query.
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 by the <tt>:group</tt> option. It takes either a column name, or the name
of a belongs_to association.
values = Person.maximum(:age, :group => 'last_name')
puts values["Drake"]
=> 43
drake = Family.find_by_last_name('Drake')
values = Person.maximum(:age, :group => :family) # Person belongs_to :family
puts values[drake]
=> 43
values.each do |family, max_age|
...
end
Options:
Examples:
Person.calculate(:count, :all) # The same as Person.count
Person.average(:age) # SELECT AVG(age) FROM people...
Person.minimum(:age, :conditions => ['last_name != ?', 'Drake']) # Selects the minimum age for everyone with a last name other than 'Drake'
Person.minimum(:age, :having => 'min(age) > 17', :group => :last_name) # Selects the minimum age for any family without any minors
Person.sum("2 * age")
# File vendor/rails/activerecord/lib/active_record/calculations.rb, line 115
115: def calculate(operation, column_name, options = {})
116: validate_calculation_options(operation, options)
117: column_name = options[:select] if options[:select]
118: column_name = '*' if column_name == :all
119: column = column_for column_name
120: catch :invalid_query do
121: if options[:group]
122: return execute_grouped_calculation(operation, column_name, column, options)
123: else
124: return execute_simple_calculation(operation, column_name, column, options)
125: end
126: end
127: 0
128: end
Count operates using three different approaches.
The third approach, count using options, accepts an option hash as the only parameter. The options are:
Examples for counting all:
Person.count # returns the total count of all people
Examples for counting by column:
Person.count(:age) # returns the total count of all people whose age is present in database
Examples for count with options:
Person.count(:conditions => "age > 26")
Person.count(:conditions => "age > 26 AND job.salary > 60000", :include => :job) # because of the named association, it finds the DISTINCT count using LEFT OUTER JOIN.
Person.count(:conditions => "age > 26 AND job.salary > 60000", :joins => "LEFT JOIN jobs on jobs.person_id = person.id") # finds the number of rows matching the conditions and joins.
Person.count('id', :conditions => "age > 26") # Performs a COUNT(id)
Person.count(:all, :conditions => "age > 26") # Performs a COUNT(*) (:all is an alias for '*')
Note: Person.count(:all) will not work because it will use :all as the condition. Use Person.count instead.
# File vendor/rails/activerecord/lib/active_record/calculations.rb, line 45
45: def count(*args)
46: calculate(:count, *construct_count_options_from_args(*args))
47: end
Calculates the maximum value on a given column. The value is returned with the same data type of the column. See calculate for examples with options.
Person.maximum('age')
# File vendor/rails/activerecord/lib/active_record/calculations.rb, line 66
66: def maximum(column_name, options = {})
67: calculate(:max, column_name, options)
68: end
Calculates the minimum value on a given column. The value is returned with the same data type of the column. See calculate for examples with options.
Person.minimum('age')
# File vendor/rails/activerecord/lib/active_record/calculations.rb, line 59
59: def minimum(column_name, options = {})
60: calculate(:min, column_name, options)
61: end
Calculates the sum of values on a given column. The value is returned with the same data type of the column. See calculate for examples with options.
Person.sum('age')
# File vendor/rails/activerecord/lib/active_record/calculations.rb, line 73
73: def sum(column_name, options = {})
74: calculate(:sum, column_name, options) || 0
75: end
# File vendor/rails/activerecord/lib/active_record/calculations.rb, line 131
131: def construct_count_options_from_args(*args)
132: options = {}
133: column_name = :all
134:
135: # We need to handle
136: # count()
137: # count(:column_name=:all)
138: # count(options={})
139: # count(column_name=:all, options={})
140: case args.size
141: when 1
142: args[0].is_a?(Hash) ? options = args[0] : column_name = args[0]
143: when 2
144: column_name, options = args
145: else
146: raise ArgumentError, "Unexpected parameters passed to count(): #{args.inspect}"
147: end if args.size > 0
148:
149: [column_name, options]
150: end