edge badge
Methods
A
C
I
M
P
S
Instance Public methods
average(column_name)

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 activerecord/lib/active_record/relation/calculations.rb, line 59
def average(column_name)
  calculate(:average, column_name)
end
calculate(operation, column_name)

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 activerecord/lib/active_record/relation/calculations.rb, line 131
def calculate(operation, column_name)
  if has_include?(column_name)
    relation = apply_join_dependency

    if operation.to_s.downcase == "count"
      relation.distinct!
      # PostgreSQL: ORDER BY expressions must appear in SELECT list when using DISTINCT
      if (column_name == :all || column_name.nil?) && select_values.empty?
        relation.order_values = []
      end
    end

    relation.calculate(operation, column_name)
  else
    perform_calculation(operation, column_name)
  end
end
count(column_name = nil)

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.

# File activerecord/lib/active_record/relation/calculations.rb, line 41
def count(column_name = nil)
  if block_given?
    unless column_name.nil?
      ActiveSupport::Deprecation.warn \
        "When `count' is called with a block, it ignores other arguments. " \
        "This behavior is now deprecated and will result in an ArgumentError in Rails 6.0."
    end

    return super()
  end

  calculate(:count, column_name)
end
ids()

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 activerecord/lib/active_record/relation/calculations.rb, line 225
def ids
  pluck primary_key
end
maximum(column_name)

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 activerecord/lib/active_record/relation/calculations.rb, line 77
def maximum(column_name)
  calculate(:maximum, column_name)
end
minimum(column_name)

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 activerecord/lib/active_record/relation/calculations.rb, line 68
def minimum(column_name)
  calculate(:minimum, column_name)
end
pick(*column_names)

Pick the value(s) from the named column(s) in the current relation. This is short-hand for relation.limit(1).pluck(*column_names).first, and is primarily useful when you have a relation that's already narrowed down to a single row.

Just like pluck, pick will only load the actual value, not the entire record object, so it's also more efficient. The value is, again like with pluck, typecast by the column type.

Person.where(id: 1).pick(:name)
# SELECT people.name FROM people WHERE id = 1 LIMIT 1
# => 'David'

Person.where(id: 1).pick(:name, :email_address)
# SELECT people.name, people.email_address FROM people WHERE id = 1 LIMIT 1
# => [ 'David', 'david@loudthinking.com' ]
# File activerecord/lib/active_record/relation/calculations.rb, line 217
def pick(*column_names)
  limit(1).pluck(*column_names).first
end
pluck(*column_names)

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 activerecord/lib/active_record/relation/calculations.rb, line 184
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)
    relation = apply_join_dependency
    relation.pluck(*column_names)
  else
    enforce_raw_sql_whitelist(column_names)
    relation = spawn
    relation.select_values = column_names.map { |cn|
      @klass.has_attribute?(cn) || @klass.attribute_alias?(cn) ? arel_attribute(cn) : cn
    }
    result = skip_query_cache_if_necessary { klass.connection.select_all(relation.arel, nil) }
    result.cast_values(klass.attribute_types)
  end
end
sum(column_name = nil)

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
# File activerecord/lib/active_record/relation/calculations.rb, line 86
def sum(column_name = nil)
  if block_given?
    unless column_name.nil?
      ActiveSupport::Deprecation.warn \
        "When `sum' is called with a block, it ignores other arguments. " \
        "This behavior is now deprecated and will result in an ArgumentError in Rails 6.0."
    end

    return super()
  end

  calculate(:sum, column_name)
end