Module | ActiveRecord::Calculations::ClassMethods |
In: |
vendor/rails/activerecord/lib/active_record/calculations.rb
|
Calculates 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 73 73: def average(column_name, options = {}) 74: calculate(:avg, column_name, options) 75: 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 :group 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
# File vendor/rails/activerecord/lib/active_record/calculations.rb, line 134 134: def calculate(operation, column_name, options = {}) 135: validate_calculation_options(operation, options) 136: column_name = options[:select] if options[:select] 137: column_name = '*' if column_name == :all 138: column = column_for column_name 139: aggregate = select_aggregate(operation, column_name, options) 140: aggregate_alias = column_alias_for(operation, column_name) 141: if options[:group] 142: execute_grouped_calculation(operation, column_name, column, aggregate, aggregate_alias, options) 143: else 144: execute_simple_calculation(operation, column_name, column, aggregate, aggregate_alias, options) 145: end 146: end
Count operates using three different approaches.
The last 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 count by conditions and joins (for backwards compatibility):
Person.count("age > 26") # returns the number of people older than 26 Person.find("age > 26 AND job.salary > 60000", "LEFT JOIN jobs on jobs.person_id = person.id") # returns the total number of rows matching the conditions and joins fetched by SELECT COUNT(*).
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 44 44: def count(*args) 45: options = {} 46: column_name = :all 47: # For backwards compatibility, we need to handle both count(conditions=nil, joins=nil) or count(options={}) or count(column_name=:all, options={}). 48: if args.size >= 0 && args.size <= 2 49: if args.first.is_a?(Hash) 50: options = args.first 51: elsif args[1].is_a?(Hash) 52: options = args[1] 53: column_name = args.first 54: else 55: # Handle legacy paramter options: def count(conditions=nil, joins=nil) 56: options.merge!(:conditions => args[0]) if args.length > 0 57: options.merge!(:joins => args[1]) if args.length > 1 58: end 59: else 60: raise(ArgumentError, "Unexpected parameters passed to count(*args): expected either count(conditions=nil, joins=nil) or count(options={})") 61: end 62: 63: if options[:include] || scope(:find, :include) 64: count_with_associations(options) 65: else 66: calculate(:count, column_name, options) 67: end 68: 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 87 87: def maximum(column_name, options = {}) 88: calculate(:max, column_name, options) 89: 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 80 80: def minimum(column_name, options = {}) 81: calculate(:min, column_name, options) 82: end
Calculates the sum value 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 94 94: def sum(column_name, options = {}) 95: calculate(:sum, column_name, options) 96: end