Add :group option, correspond to GROUP BY, to the find method and to the has_many association. Closes #2818.

git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@2974 5ecf4fe2-1ee6-0310-87b1-e25e094e27de

activerecord/CHANGELOG

@@ -1,5 +1,7 @@
 *SVN*
 
+* Add :group option, correspond to GROUP BY, to the find method and to the has_many association.  #2818 [rubyonrails@atyp.de]
+
 * Don't cast nil or empty strings to a dummy date.  #2789 [Rick Bradley <rick@rickbradley.com>]
 
 * acts_as_list plays nicely with inheritance by remembering the class which declared it.  #2811 [rephorm@rephorm.com]

activerecord/lib/active_record/associations.rb

@@ -307,6 +307,8 @@ module ActiveRecord
       #   sql fragment, such as "price > 5 AND name LIKE 'B%'".
       # * <tt>:order</tt>       - specify the order in which the associated objects are returned as a "ORDER BY" sql fragment,
       #   such as "last_name, first_name DESC"
+      # * <tt>:group</tt>       - specify the attribute by which the associated objects are returned as a "GROUP BY" sql fragment,
+      #   such as "category"      
       # * <tt>:foreign_key</tt> - specify the foreign key used for the association. By default this is guessed to be the name
       #   of this class in lower-case and "_id" suffixed. So a +Person+ class that makes a has_many association will use "person_id"
       #   as the default foreign_key.
@@ -341,7 +343,8 @@ module ActiveRecord
         options.assert_valid_keys(
           :foreign_key, :class_name, :exclusively_dependent, :dependent, 
           :conditions, :order, :include, :finder_sql, :counter_sql, 
-          :before_add, :after_add, :before_remove, :after_remove, :extend
+          :before_add, :after_add, :before_remove, :after_remove, :extend,
+          :group
         )
 
         options[:extend] = create_extension_module(association_id, extension) if block_given?

activerecord/lib/active_record/associations/has_many_association.rb

@@ -113,7 +113,8 @@ module ActiveRecord
               :order      => @options[:order], 
               :limit      => @options[:limit],
               :joins      => @options[:joins],
-              :include    => @options[:include]
+              :include    => @options[:include],
+              :group      => @options[:group]
             )
           end
         end

activerecord/lib/active_record/base.rb

@@ -363,6 +363,7 @@ module ActiveRecord #:nodoc:
       #
       # * <tt>:conditions</tt>: An SQL fragment like "administrator = 1" or [ "user_name = ?", username ]. See conditions in the intro.
       # * <tt>:order</tt>: An SQL fragment like "created_at DESC, name".
+      # * <tt>:group</tt>: An attribute name by which the result should be grouped. Uses the GROUP BY SQL-clause.
       # * <tt>:limit</tt>: An integer determining the limit on the number of rows that should be returned.
       # * <tt>:offset</tt>: An integer determining the offset from where the rows should be fetched. So at 5, it would skip the first 4 rows.
       # * <tt>:joins</tt>: An SQL fragment for additional joins like "LEFT JOIN comments ON comments.post_id = id". (Rarely needed).
@@ -391,6 +392,7 @@ module ActiveRecord #:nodoc:
       #   Person.find(:all, :conditions => [ "category IN (?)", categories], :limit => 50)
       #   Person.find(:all, :offset => 10, :limit => 10)
       #   Person.find(:all, :include => [ :account, :friends ])
+      #   Person.find(:all, :group => "category")
       def find(*args)
         options = extract_options_from_args!(args)
 
@@ -926,6 +928,7 @@ module ActiveRecord #:nodoc:
           sql  = "SELECT #{options[:select] || '*'} FROM #{table_name} "
           add_joins!(sql, options)
           add_conditions!(sql, options[:conditions])
+          sql << " GROUP BY #{options[:group]} " if options[:group]
           sql << " ORDER BY #{options[:order]} " if options[:order]
           add_limit!(sql, options)
           sql
@@ -1171,7 +1174,7 @@ module ActiveRecord #:nodoc:
         end
 
         def validate_find_options(options)
-          options.assert_valid_keys [:conditions, :include, :joins, :limit, :offset, :order, :select, :readonly]
+          options.assert_valid_keys [:conditions, :include, :joins, :limit, :offset, :order, :select, :readonly, :group]
         end
 
         def encode_quoted_value(value)

activerecord/test/associations_test.rb

@@ -384,6 +384,13 @@ class HasManyAssociationsTest < Test::Unit::TestCase
     assert_raises(ActiveRecord::RecordNotFound) { companies(:first_firm).clients.find(6) }
   end
 
+  def test_find_grouped
+    all_clients_of_firm1 = Client.find(:all, :conditions => "firm_id = 1")
+    grouped_clients_of_firm1 = Client.find(:all, :conditions => "firm_id = 1", :group => "firm_id", :select => 'firm_id, count(id) as clients_count')
+    assert_equal 2, all_clients_of_firm1.size
+    assert_equal 1, grouped_clients_of_firm1.size
+  end
+
   def test_adding
     force_signal37_to_load_all_clients_of_firm
     natural = Client.new("name" => "Natural Company")