activerecord 3.2.22.5 → 4.2.11.3

data/lib/active_record/relation/calculations.rb

@@ -1,68 +1,60 @@
-require 'active_support/core_ext/object/blank'
-require 'active_support/core_ext/object/try'
-
 module ActiveRecord
   module Calculations
-    # Count operates using three different approaches.
-    #
-    # * Count all: By not passing any parameters to count, it will return a count of all the rows for the model.
-    # * Count using column: By passing a column name to count, it will return a count of all the
-    #   rows for the model with supplied column present.
-    # * Count using options will find the row count matched by the options used.
-    #
-    # The third approach, count using options, accepts an option hash as the only parameter. The options are:
-    #
-    # * <tt>:conditions</tt>: An SQL fragment like "administrator = 1" or [ "user_name = ?", username ].
-    #   See conditions in the intro to ActiveRecord::Base.
-    # * <tt>:joins</tt>: Either an SQL fragment for additional joins like "LEFT JOIN comments ON comments.post_id = id"
-    #   (rarely needed) or named associations in the same form used for the <tt>:include</tt> option, which will
-    #   perform an INNER JOIN on the associated table(s). If the value is a string, then the records
-    #   will be returned read-only since they will have attributes that do not correspond to the table's columns.
-    #   Pass <tt>:readonly => false</tt> to override.
-    # * <tt>:include</tt>: Named associations that should be loaded alongside using LEFT OUTER JOINs.
-    #   The symbols named refer to already defined associations. When using named associations, count
-    #   returns the number of DISTINCT items for the model you're counting.
-    #   See eager loading under Associations.
-    # * <tt>:order</tt>: An SQL fragment like "created_at DESC, name" (really only used with GROUP BY calculations).
-    # * <tt>:group</tt>: An attribute name by which the result should be grouped. Uses the GROUP BY SQL-clause.
-    # * <tt>:select</tt>: By default, this is * as in SELECT * FROM, but can be changed if you, for example,
-    #   want to do a join but not include the joined columns.
-    # * <tt>:distinct</tt>: Set this to true to make this a distinct calculation, such as
-    #   SELECT COUNT(DISTINCT posts.id) ...
-    # * <tt>:from</tt> - By default, this is the table name of the class, but can be changed to an
-    #   alternate table name (or even the name of a database view).
-    #
-    # 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")
-    #
-    #   # because of the named association, it finds the DISTINCT count using LEFT OUTER JOIN.
-    #   Person.count(:conditions => "age > 26 AND job.salary > 60000", :include => :job)
-    #
-    #   # finds the number of rows matching the conditions and joins.
-    #   Person.count(:conditions => "age > 26 AND job.salary > 60000",
-    #                :joins => "LEFT JOIN jobs on jobs.person_id = person.id")
-    #
-    #   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: <tt>Person.count(:all)</tt> will not work because it will use <tt>:all</tt> as the condition.
-    # Use Person.count instead.
+    # 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 +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 +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 +select+, it will count the selected columns:
+    #
+    #   Person.select(:age).count
+    #   # => counts the number of different age values
+    #
+    # Note: not all valid +select+ expressions are valid +count+ expressions. The specifics differ
+    # between databases. In invalid cases, an error from the database is thrown.
     def count(column_name = nil, options = {})
-      column_name, options = nil, column_name if column_name.is_a?(Hash)
+      if options.present? && !ActiveRecord.const_defined?(:DeprecatedFinders)
+        raise ArgumentError, "Relation#count does not support finder options anymore. " \
+                             "Please build a scope and then call count on it or use the " \
+                             "activerecord-deprecated_finders gem to enable this functionality."
+
+      end
+
+      # TODO: Remove options argument as soon we remove support to
+      # activerecord-deprecated_finders.
       calculate(:count, column_name, options)
     end
 
     # 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
+    #   Person.average(:age) # => 35.8
     def average(column_name, options = {})
+      # TODO: Remove options argument as soon we remove support to
+      # activerecord-deprecated_finders.
       calculate(:average, column_name, options)
     end
 
@@ -70,8 +62,10 @@ module ActiveRecord
     # 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
+    #   Person.minimum(:age) # => 7
     def minimum(column_name, options = {})
+      # TODO: Remove options argument as soon we remove support to
+      # activerecord-deprecated_finders.
       calculate(:minimum, column_name, options)
     end
 
@@ -79,8 +73,10 @@ module ActiveRecord
     # 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
+    #   Person.maximum(:age) # => 93
     def maximum(column_name, options = {})
+      # TODO: Remove options argument as soon we remove support to
+      # activerecord-deprecated_finders.
       calculate(:maximum, column_name, options)
     end
 
@@ -88,128 +84,144 @@ module ActiveRecord
     # with the same data type of the column, 0 if there's no row. See
     # +calculate+ for examples with options.
     #
-    #   Person.sum('age') # => 4562
+    #   Person.sum(:age) # => 4562
     def sum(*args)
-      if block_given?
-        self.to_a.sum(*args) {|*block_args| yield(*block_args)}
-      else
-        calculate(:sum, *args)
-      end
+      calculate(:sum, *args)
     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 <tt>:conditions</tt>,
-    # <tt>:order</tt>, <tt>:group</tt>, <tt>:having</tt>, and <tt>:joins</tt> can be passed to customize the query.
+    # minimum, and maximum have been added as shortcuts.
     #
     # There are two basic forms of output:
-    #   * Single aggregate value: The single value is type cast to Fixnum for COUNT, Float
+    #
+    #   * 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 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')
+    #   * 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
+    #       # => 43
     #
-    #       drake  = Family.find_by_last_name('Drake')
-    #       values = Person.maximum(:age, :group => :family) # Person belongs_to :family
+    #       drake  = Family.find_by(last_name: 'Drake')
+    #       values = Person.group(:family).maximum(:age) # Person belongs_to :family
     #       puts values[drake]
-    #       => 43
+    #       # => 43
     #
     #       values.each do |family, max_age|
     #       ...
     #       end
     #
-    # Options:
-    # * <tt>:conditions</tt> - An SQL fragment like "administrator = 1" or [ "user_name = ?", username ].
-    #   See conditions in the intro to ActiveRecord::Base.
-    # * <tt>:include</tt>: Eager loading, see Associations for details. Since calculations don't load anything,
-    #   the purpose of this is to access fields on joined tables in your conditions, order, or group clauses.
-    # * <tt>:joins</tt> - An SQL fragment for additional joins like "LEFT JOIN comments ON comments.post_id = id".
-    #   (Rarely needed).
-    #   The records will be returned read-only since they will have attributes that do not correspond to the
-    #   table's columns.
-    # * <tt>:order</tt> - An SQL fragment like "created_at DESC, name" (really only used with GROUP BY calculations).
-    # * <tt>:group</tt> - An attribute name by which the result should be grouped. Uses the GROUP BY SQL-clause.
-    # * <tt>:select</tt> - By default, this is * as in SELECT * FROM, but can be changed if you for example
-    #   want to do a join, but not include the joined columns.
-    # * <tt>:distinct</tt> - Set this to true to make this a distinct calculation, such as
-    #   SELECT COUNT(DISTINCT posts.id) ...
-    #
-    # 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'
     #
     #   # Selects the minimum age for any family without any minors
-    #   Person.minimum(:age, :having => 'min(age) > 17', :group => :last_name)
+    #   Person.group(:last_name).having("min(age) > 17").minimum(:age)
     #
     #   Person.sum("2 * age")
     def calculate(operation, column_name, options = {})
-      if options.except(:distinct).present?
-        apply_finder_options(options.except(:distinct)).calculate(operation, column_name, :distinct => options[:distinct])
-      else
-        relation = with_default_scope
+      # TODO: Remove options argument as soon we remove support to
+      # activerecord-deprecated_finders.
+      if column_name.is_a?(Symbol) && attribute_alias?(column_name)
+        column_name = attribute_alias(column_name)
+      end
 
-        if relation.equal?(self)
-          if eager_loading? || (includes_values.present? && references_eager_loaded_tables?)
-            construct_relation_for_association_calculations.calculate(operation, column_name, options)
-          else
-            perform_calculation(operation, column_name, options)
-          end
-        else
-          relation.calculate(operation, column_name, options)
-        end
+      if has_include?(column_name)
+        construct_relation_for_association_calculations.calculate(operation, column_name, options)
+      else
+        perform_calculation(operation, column_name, options)
       end
-    rescue ThrowResult
-      0
     end
 
-    # This method is designed to perform select by a single column as direct SQL query
-    # Returns <tt>Array</tt> with values of the specified column name
-    # The values has same data type as column.
+    # Use <tt>pluck</tt> 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)
     #
-    # Examples:
+    # Pluck returns an <tt>Array</tt> 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(:id) # SELECT people.id FROM people
-    #   Person.uniq.pluck(:role) # SELECT DISTINCT role FROM people
-    #   Person.where(:confirmed => true).limit(5).pluck(:id)
+    #   Person.pluck(:id)
+    #   # SELECT people.id FROM people
+    #   # => [1, 2, 3]
     #
-    def pluck(column_name)
-      if column_name.is_a?(Symbol) && column_names.include?(column_name.to_s)
-        column_name = "#{connection.quote_table_name(table_name)}.#{connection.quote_column_name(column_name)}"
+    #   Person.pluck(:id, :name)
+    #   # SELECT people.id, people.name FROM people
+    #   # => [[1, 'David'], [2, 'Jeremy'], [3, 'Jose']]
+    #
+    #   Person.pluck('DISTINCT 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']
+    #
+    def pluck(*column_names)
+      column_names.map! do |column_name|
+        if column_name.is_a?(Symbol) && attribute_alias?(column_name)
+          attribute_alias(column_name)
+        else
+          column_name.to_s
+        end
       end
 
-      result = klass.connection.exec_query(select(column_name).to_sql)
-      last_column = result.columns.last
-
-      result.map do |attributes|
-        klass.type_cast_attribute(last_column, klass.initialize_attributes(attributes))
+      if has_include?(column_names.first)
+        construct_relation_for_association_calculations.pluck(*column_names)
+      else
+        relation = spawn
+        relation.select_values = column_names.map { |cn|
+          columns_hash.key?(cn) ? arel_table[cn] : cn
+        }
+        result = klass.connection.select_all(relation.arel, nil, relation.arel.bind_values + bind_values)
+        result.cast_values(klass.column_types)
       end
     end
 
+    # 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
+    def ids
+      pluck primary_key
+    end
+
     private
 
+    def has_include?(column_name)
+      eager_loading? || (includes_values.present? && ((column_name && column_name != :all) || references_eager_loaded_tables?))
+    end
+
     def perform_calculation(operation, column_name, options = {})
+      # TODO: Remove options argument as soon we remove support to
+      # activerecord-deprecated_finders.
       operation = operation.to_s.downcase
 
-      # If #count is used in conjuction with #uniq it is considered distinct. (eg. relation.uniq.count)
-      distinct = options[:distinct] || self.uniq_value
+      # If #count is used with #distinct / #uniq it is considered distinct. (eg. relation.distinct.count)
+      distinct = self.distinct_value
 
       if operation == "count"
-        column_name ||= (select_for_count || :all)
+        column_name ||= select_for_count
 
         unless arel.ast.grep(Arel::Nodes::OuterJoin).empty?
           distinct = true
         end
 
         column_name = primary_key if column_name == :all && distinct
-
-        distinct = nil if column_name =~ /\s*DISTINCT\s+/i
+        distinct = nil if column_name =~ /\s*DISTINCT[\s(]+/i
       end
 
-      if @group_values.any?
+      if group_values.any?
         execute_grouped_calculation(operation, column_name, distinct)
       else
         execute_simple_calculation(operation, column_name, distinct)
@@ -230,48 +242,66 @@ module ActiveRecord
 
     def execute_simple_calculation(operation, column_name, distinct) #:nodoc:
       # Postgresql doesn't like ORDER BY when there are no GROUP BY
-      relation = reorder(nil)
+      relation = unscope(:order)
+
+      column_alias = column_name
+
+      bind_values = nil
 
       if operation == "count" && (relation.limit_value || relation.offset_value)
         # Shortcut when limit is zero.
         return 0 if relation.limit_value == 0
 
         query_builder = build_count_subquery(relation, column_name, distinct)
+        bind_values = query_builder.bind_values + relation.bind_values
       else
         column = aggregate_column(column_name)
 
         select_value = operation_over_aggregate_column(column, operation, distinct)
 
+        column_alias = select_value.alias
+        column_alias ||= @klass.connection.column_name_for_operation(operation, select_value)
         relation.select_values = [select_value]
 
         query_builder = relation.arel
+        bind_values = query_builder.bind_values + relation.bind_values
       end
 
-      type_cast_calculated_value(@klass.connection.select_value(query_builder), column_for(column_name), operation)
+      result = @klass.connection.select_all(query_builder, nil, bind_values)
+      row    = result.first
+      value  = row && row.values.first
+      column = result.column_types.fetch(column_alias) do
+        type_for(column_name)
+      end
+
+      type_cast_calculated_value(value, column, operation)
     end
 
     def execute_grouped_calculation(operation, column_name, distinct) #:nodoc:
-      group_attrs = @group_values
+      group_attrs = group_values
 
       if group_attrs.first.respond_to?(:to_sym)
-        association  = @klass.reflect_on_association(group_attrs.first.to_sym)
-        associated   = group_attrs.size == 1 && association && association.macro == :belongs_to # only count belongs_to associations
+        association  = @klass._reflect_on_association(group_attrs.first)
+        associated   = group_attrs.size == 1 && association && association.belongs_to? # only count belongs_to associations
         group_fields = Array(associated ? association.foreign_key : group_attrs)
       else
         group_fields = group_attrs
       end
+      group_fields = arel_columns(group_fields)
 
-      group_aliases = group_fields.map { |field| column_alias_for(field) }
+      group_aliases = group_fields.map { |field|
+        column_alias_for(field)
+      }
       group_columns = group_aliases.zip(group_fields).map { |aliaz,field|
-        [aliaz, column_for(field)]
+        [aliaz, field]
       }
 
-      group = @klass.connection.adapter_name == 'FrontBase' ? group_aliases : group_fields
+      group = group_fields
 
       if operation == 'count' && column_name == :all
         aggregate_alias = 'count_all'
       else
-        aggregate_alias = column_alias_for(operation, column_name)
+        aggregate_alias = column_alias_for([operation, column_name].join(' '))
       end
 
       select_values = [
@@ -280,7 +310,7 @@ module ActiveRecord
           operation,
           distinct).as(aggregate_alias)
       ]
-      select_values += @select_values unless @having_values.empty?
+      select_values += self.select_values unless having_values.empty?
 
       select_values.concat group_fields.zip(group_aliases).map { |field,aliaz|
         if field.respond_to?(:as)
@@ -290,10 +320,11 @@ module ActiveRecord
         end
       }
 
-      relation = except(:group).group(group)
+      relation = except(:group)
+      relation.group_values  = group
       relation.select_values = select_values
 
-      calculated_data = @klass.connection.select_all(relation)
+      calculated_data = @klass.connection.select_all(relation, nil, relation.arel.bind_values + bind_values)
 
       if association
         key_ids     = calculated_data.collect { |row| row[group_aliases.first] }
@@ -301,13 +332,18 @@ module ActiveRecord
         key_records = Hash[key_records.map { |r| [r.id, r] }]
       end
 
-      ActiveSupport::OrderedHash[calculated_data.map do |row|
-        key = group_columns.map { |aliaz, column|
+      Hash[calculated_data.map do |row|
+        key = group_columns.map { |aliaz, col_name|
+          column = calculated_data.column_types.fetch(aliaz) do
+            type_for(col_name)
+          end
           type_cast_calculated_value(row[aliaz], column)
         }
         key = key.first if key.size == 1
         key = key_records[key] if associated
-        [key, type_cast_calculated_value(row[aggregate_alias], column_for(column_name), operation)]
+
+        column_type = calculated_data.column_types.fetch(aggregate_alias) { type_for(column_name) }
+        [key, type_cast_calculated_value(row[aggregate_alias], column_type, operation)]
       end]
     end
 
@@ -319,10 +355,12 @@ module ActiveRecord
     #   column_alias_for("count(distinct users.id)") # => "count_distinct_users_id"
     #   column_alias_for("count(*)")                 # => "count_all"
     #   column_alias_for("count", "id")              # => "count_id"
-    def column_alias_for(*keys)
-      keys.map! {|k| k.respond_to?(:to_sql) ? k.to_sql : k}
-      table_name = keys.join(' ')
-      table_name.downcase!
+    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!
@@ -331,28 +369,26 @@ module ActiveRecord
       @klass.connection.table_alias_for(table_name)
     end
 
-    def column_for(field)
+    def type_for(field)
       field_name = field.respond_to?(:name) ? field.name.to_s : field.to_s.split('.').last
-      @klass.columns.detect { |c| c.name.to_s == field_name }
+      @klass.type_for_attribute(field_name)
     end
 
-    def type_cast_calculated_value(value, column, operation = nil)
+    def type_cast_calculated_value(value, type, operation = nil)
       case operation
         when 'count'   then value.to_i
-        when 'sum'     then type_cast_using_column(value || '0', column)
+        when 'sum'     then type.type_cast_from_database(value || 0)
         when 'average' then value.respond_to?(:to_d) ? value.to_d : value
-        else type_cast_using_column(value, column)
+        else type.type_cast_from_database(value)
       end
     end
 
-    def type_cast_using_column(value, column)
-      column ? column.type_cast(value) : value
-    end
-
+    # TODO: refactor to allow non-string `select_values` (eg. Arel nodes).
     def select_for_count
-      if @select_values.present?
-        select = @select_values.join(", ")
-        select if select !~ /(,|\*)/
+      if select_values.present?
+        select_values.join(", ")
+      else
+        :all
       end
     end
 
@@ -362,9 +398,11 @@ module ActiveRecord
 
       aliased_column = aggregate_column(column_name == :all ? 1 : column_name).as(column_alias)
       relation.select_values = [aliased_column]
-      subquery = relation.arel.as(subquery_alias)
+      arel = relation.arel
+      subquery = arel.as(subquery_alias)
 
       sm = Arel::SelectManager.new relation.engine
+      sm.bind_values = arel.bind_values
       select_value = operation_over_aggregate_column(column_alias, 'count', distinct)
       sm.project(select_value).from(subquery)
     end