Module: ActiveRecord::Calculations

Same as #count, but performs the query asynchronously and returns an Promise.

Same as #ids, but performs the query asynchronously and returns an Promise.

Same as #maximum, but performs the query asynchronously and returns an Promise.

Same as #minimum, but performs the query asynchronously and returns an Promise.

Same as #pick, but performs the query asynchronously and returns an Promise.

Same as #pluck, but performs the query asynchronously and returns an Promise.

Same as #sum, but performs the query asynchronously and returns an Promise.

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

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

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", "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.

When given a block, calls the block with each record in the relation and returns the number of records for which the block returns a truthy value.

Person.count { |person| person.age > 21 }
# => counts the number of people older that 21

If the relation hasn’t been loaded yet, calling count with a block will load all records in the relation. If there are a lot of records in the relation, loading all records could result in performance issues.

Returns the base model’s ID’s for the relation using the table’s primary key

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

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

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

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' ]

Use #pluck as a shortcut to select one or more attributes without loading an entire record object per row.

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]

Comment.joins(:person).pluck(:id, person: [:id])
# SELECT comments.id, people.id FROM comments INNER JOIN people on comments.person_id = people.id
# => [[1, 2], [2, 2]]

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

See also #ids.

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

When given a block, calls the block with each record in the relation and returns the sum of initial_value_or_column plus the block return values:

Person.sum { |person| person.age } # => 4562
Person.sum(1000) { |person| person.age } # => 5562

If the relation hasn’t been loaded yet, calling sum with a block will load all records in the relation. If there are a lot of records in the relation, loading all records could result in performance issues.