# module ActiveRecord::Calculations

### Public Instance Methods

average(column_name) click to toggle source

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

    # File lib/active_record/relation/calculations.rb, line 48
    def average(column_name)
      calculate(:average, column_name)
    end

calculate(operation, column_name) click to toggle source

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

    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")

There are two basic forms of output:

- Single aggregate value: The single value is type cast to Integer 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

    # File lib/active_record/relation/calculations.rb, line 111
    def calculate(operation, column_name)
      if has_include?(column_name)
        relation = construct_relation_for_association_calculations
        relation.distinct! if operation.to_s.downcase == "count"

        relation.calculate(operation, column_name)
      else
        perform_calculation(operation, column_name)
      end
    end

count(column_name = nil) click to toggle source

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 Relation#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 }

If count is used with Relation#group for multiple columns, it returns a Hash whose keys are an array containing the individual values of each column and the value of each key would be the count.

    Article.group(:status, :category).count
    # =>  {["draft", "business"]=>10, ["draft", "technology"]=>4,
           ["published", "business"]=>0, ["published", "technology"]=>2}

If count is used with Relation#select, it will count the selected columns:

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

Note: not all valid Relation#select expressions are valid count expressions. The specifics differ between databases. In invalid cases, an error from the database is thrown.

Calls superclass method

    # File lib/active_record/relation/calculations.rb, line 39
    def count(column_name = nil)
      return super() if block_given?
      calculate(:count, column_name)
    end

ids() click to toggle source

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

    # File lib/active_record/relation/calculations.rb, line 178
    def ids
      pluck primary_key
    end

maximum(column_name) click to toggle source

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

    # File lib/active_record/relation/calculations.rb, line 66
    def maximum(column_name)
      calculate(:maximum, column_name)
    end

minimum(column_name) click to toggle source

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

    # File lib/active_record/relation/calculations.rb, line 57
    def minimum(column_name)
      calculate(:minimum, column_name)
    end

pluck(*column_names) click to toggle source

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(:name)
    # SELECT people.name FROM people
    # => ['David', 'Jeremy', 'Jose']

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

    Person.distinct.pluck(: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']

See also ids.

    # File lib/active_record/relation/calculations.rb, line 157
    def pluck(*column_names)
      if loaded? && (column_names.map(&:to_s) - @klass.attribute_names - @klass.attribute_aliases.keys).empty?
        return records.pluck(*column_names)
      end

      if has_include?(column_names.first)
        construct_relation_for_association_calculations.pluck(*column_names)
      else
        relation = spawn
        relation.select_values = column_names.map { |cn|
          @klass.has_attribute?(cn) || @klass.attribute_alias?(cn) ? arel_attribute(cn) : cn
        }
        result = klass.connection.select_all(relation.arel, nil, bound_attributes)
        result.cast_values(klass.attribute_types)
      end
    end

sum(column_name = nil) click to toggle source

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

Calls superclass method

    # File lib/active_record/relation/calculations.rb, line 75
    def sum(column_name = nil)
      return super() if block_given?
      calculate(:sum, column_name)
    end

### Private Instance Methods

aggregate_column(column_name) click to toggle source

    # File lib/active_record/relation/calculations.rb, line 213
    def aggregate_column(column_name)
      return column_name if Arel::Expressions === column_name

      if @klass.has_attribute?(column_name.to_s) || @klass.attribute_alias?(column_name.to_s)
        @klass.arel_attribute(column_name)
      else
        Arel.sql(column_name == :all ? "*" : column_name.to_s)
      end
    end

build_count_subquery(relation, column_name, distinct) click to toggle source

    # File lib/active_record/relation/calculations.rb, line 371
    def build_count_subquery(relation, column_name, distinct)
      relation.select_values = [
        if column_name == :all
          distinct ? table[Arel.star] : Arel.sql("1")
        else
          column_alias = Arel.sql("count_column")
          aggregate_column(column_name).as(column_alias)
        end
      ]

      subquery = relation.arel.as(Arel.sql("subquery_for_count"))
      select_value = operation_over_aggregate_column(column_alias || Arel.star, "count", false)

      Arel::SelectManager.new(subquery).project(select_value)
    end

column_alias_for(keys) click to toggle source

Converts the given keys to the value that the database adapter returns as a usable column name:

    column_alias_for("users.id")                 # => "users_id"
    column_alias_for("sum(id)")                  # => "sum_id"
    column_alias_for("count(distinct users.id)") # => "count_distinct_users_id"
    column_alias_for("count(*)")                 # => "count_all"

    # File lib/active_record/relation/calculations.rb, line 334
    def column_alias_for(keys)
      if keys.respond_to? :name
        keys = "#{keys.relation.name}.#{keys.name}"
      end

      table_name = keys.to_s.downcase
      table_name.gsub!(/\*/, "all")
      table_name.gsub!(/\W+/, " ")
      table_name.strip!
      table_name.gsub!(/ +/, "_")

      @klass.connection.table_alias_for(table_name)
    end

has_include?(column_name) click to toggle source

    # File lib/active_record/relation/calculations.rb, line 184
    def has_include?(column_name)
      eager_loading? || (includes_values.present? && column_name && column_name != :all)
    end

operation_over_aggregate_column(column, operation, distinct) click to toggle source

    # File lib/active_record/relation/calculations.rb, line 223
    def operation_over_aggregate_column(column, operation, distinct)
      operation == "count" ? column.count(distinct) : column.send(operation)
    end

perform_calculation(operation, column_name) click to toggle source

    # File lib/active_record/relation/calculations.rb, line 188
    def perform_calculation(operation, column_name)
      operation = operation.to_s.downcase

      # If #count is used with #distinct (i.e. `relation.distinct.count`) it is
      # considered distinct.
      distinct = distinct_value

      if operation == "count"
        column_name ||= select_for_count
        if column_name == :all
          if distinct && !(has_limit_or_offset? && order_values.any?)
            column_name = primary_key
          end
        elsif column_name =~ /\s*DISTINCT[\s(]+/i
          distinct = nil
        end
      end

      if group_values.any?
        execute_grouped_calculation(operation, column_name, distinct)
      else
        execute_simple_calculation(operation, column_name, distinct)
      end
    end

select_for_count() click to toggle source

    # File lib/active_record/relation/calculations.rb, line 362
    def select_for_count
      if select_values.present?
        return select_values.first if select_values.one?
        select_values.join(", ")
      else
        :all
      end
    end

type_cast_calculated_value(value, type, operation = nil) click to toggle source

    # File lib/active_record/relation/calculations.rb, line 353
    def type_cast_calculated_value(value, type, operation = nil)
      case operation
      when "count"   then value.to_i
      when "sum"     then type.deserialize(value || 0)
      when "average" then value.respond_to?(:to_d) ? value.to_d : value
      else type.deserialize(value)
      end
    end

type_for(field, &block) click to toggle source

    # File lib/active_record/relation/calculations.rb, line 348
    def type_for(field, &block)
      field_name = field.respond_to?(:name) ? field.name.to_s : field.to_s.split(".").last
      @klass.type_for_attribute(field_name, &block)
    end