activerecord-summarize 0.5.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f469f566e328d4cc697d23295d95c477f6eb66c5d9246874b36bc59b5fbdcac0
-  data.tar.gz: 7a7315482f217384462c869796531e1ea27511ba1787f435aec1eed754601506
+  metadata.gz: 9a4373f45ac68b039a480eabff7429cf8c0459c3ca43ab1d2e44ac7fce5987cd
+  data.tar.gz: da0aee342ea440116ffb2e557f628d5f18781de3c143e23a2b6b3350a607aea7
 SHA512:
-  metadata.gz: 66a61050cec2736eed06d01b5889f85259e0625daa530376fb840f02cb93a041483f335bda4614d2925b9b4d1ae22f811d8fa5d005dad82d559bd1a5d64f0bb5
-  data.tar.gz: b3f3e98e768a019f4c2a32c06d61fb84a50fcbc9f6866df35c1c254ee7d8feb2fd300a286a33cefd6407d12f8e67353348e7e600290ccfb2ae192e9dffd9fd9b
+  metadata.gz: b8812147378b9d2c1b4069b9074f126cd20e37f763c6b4df374ada72bec3b2d354505cf67470cc6708198f4d997c14d8d0b402b71efe7274ef2ce096c4ac73d1
+  data.tar.gz: d7a893afa09e883a5a9db77f802d0f3a9ab85ff9ad744cb30f30247c0b2d85fea30147ea15ca866f9e4498538dc7d5b68c191a7219050cc4ef35cebe2474ed47

data/CHANGELOG.md

@@ -1,3 +1,7 @@
+## [0.6.0] - 2026-05-20
+
+- **FEATURE:** Support for `.average`, `.minimum`, and `.maximum` inside `summarize` blocks. All three work with the same flexibility as `.count` and `.sum`: they can be combined freely with each other and with other calculation methods, support `.where` and `.group` sub-scopes, and their results are chainable just like any other `ChainableResult`.
+
 ## [0.5.1] - 2023-08-16
 
 - **BUGFIX:** Starting with version 7.0.5, the behavior of ActiveRecord's `pluck` changed: when you pluck multiple values with the same aggregate function (e.g., `sum`), in PostgreSQL, the data type of the last such value is now applied to all such values, though they used to be inferred correctly. Our solution is to add an explicit alias to each result column.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    activerecord-summarize (0.5.1)
+    activerecord-summarize (0.6.0)
       activerecord (>= 5.0)
 
 GEM
@@ -24,6 +24,7 @@ GEM
     json (2.6.3)
     language_server-protocol (3.17.0.3)
     lint_roller (1.1.0)
+    mini_portile2 (2.8.7)
     minitest (5.19.0)
     parallel (1.23.0)
     parser (3.2.2.3)
@@ -51,8 +52,9 @@ GEM
       rubocop (>= 1.7.0, < 2.0)
       rubocop-ast (>= 0.4.0)
     ruby-progressbar (1.13.0)
+    sqlite3 (1.6.3)
+      mini_portile2 (~> 2.8.0)
     sqlite3 (1.6.3-arm64-darwin)
-    sqlite3 (1.6.3-x86_64-linux)
     standard (1.30.1)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.0)
@@ -71,6 +73,7 @@ GEM
 
 PLATFORMS
   arm64-darwin-21
+  arm64-darwin-23
   x86_64-linux
 
 DEPENDENCIES

data/README.md

@@ -127,6 +127,7 @@ puts Purchase.last_year.complete.group(:region_id).summarize do |purchases,with_
   target = with_resolved[total / 4, by_quarter.values.max] {|avg_q, best_q| [avg_q * 1.25, best_q].max.round }
   {last_year: total, quarters: by_quarter, unit_target: target}
 end
+
 # Output:
 # {
 #   1 => {

data/lib/activerecord/summarize/calculation_implementation.rb

@@ -0,0 +1,129 @@
+module ActiveRecord::Summarize::CalculationImplementation
+  def self.new(operation, relation, column_name)
+    case operation
+    when "sum" then Sum
+    when "count" then Count
+    when "minimum" then Minimum
+    when "maximum" then Maximum
+    else raise "Unknown calculation #{operation}"
+    end.new(relation, column_name)
+  end
+
+  class Base
+    attr_reader :relation, :column
+
+    def initialize(relation, column)
+      @relation = relation
+      @column = column
+    end
+
+    def select_column_arel_node(base_relation)
+      where = relation.where_clause - base_relation.where_clause
+      for_select = column
+      for_select = Arel::Nodes::Case.new(where.ast).when(true, for_select).else(unmatch_arel_node) unless where.empty?
+      function_arel_node_class.new([for_select]).tap { |f| f.distinct = relation.distinct_value }
+    end
+
+    def function_arel_node_class
+      # Arel::Node class representing the SQL function
+      raise "`#{self.class}` must implement `function_arel_node_class`"
+    end
+
+    def unmatch_arel_node
+      # In case of `where` filters, this is the does-not-count value for when
+      # filters don't match, so far always 0 or nil (becomes NULL)
+      raise "`#{self.class}` must implement `unmatch_arel_node`"
+    end
+
+    def initial
+      # Initial value for reducing potentially many split-into-groups rows to
+      # a single value, so far always 0 or nil.
+      raise "`#{self.class}` must implement `initial`"
+    end
+
+    def reducer(memo, v)
+      # Reducer method for reducing potentially many split-into-groups rows to
+      # a single value. Method should return a value the same type as memo
+      # and/or v. A reducer is necessary at all because .group in columns
+      # _other than_ this one results in fragmenting this result into several
+      # rows.
+      raise "`#{self.class}` must implement `reducer`"
+    end
+  end
+
+  class Sum < Base
+    def unmatch_arel_node
+      0 # Adding zero to a sum does nothing
+    end
+
+    def function_arel_node_class
+      Arel::Nodes::Sum
+    end
+
+    def initial
+      0
+    end
+
+    def reducer(memo, v)
+      memo + (v || 0)
+    end
+  end
+
+  class Count < Base
+    def unmatch_arel_node
+      nil # In SQL, null is no value and is not counted
+    end
+
+    def function_arel_node_class
+      Arel::Nodes::Count
+    end
+
+    def initial
+      0
+    end
+
+    def reducer(memo, v)
+      memo + (v || 0)
+    end
+  end
+
+  class Minimum < Base
+    def unmatch_arel_node
+      nil # In SQL, null is no value and is not considered for min()
+    end
+
+    def function_arel_node_class
+      Arel::Nodes::Min
+    end
+
+    def initial
+      nil
+    end
+
+    def reducer(memo, v)
+      return memo if v.nil?
+      return v if memo.nil?
+      (v < memo) ? v : memo
+    end
+  end
+
+  class Maximum < Base
+    def unmatch_arel_node
+      nil # In SQL, null is no value and is not considered for max()
+    end
+
+    def function_arel_node_class
+      Arel::Nodes::Max
+    end
+
+    def initial
+      nil
+    end
+
+    def reducer(memo, v)
+      return memo if v.nil?
+      return v if memo.nil?
+      (v > memo) ? v : memo
+    end
+  end
+end

data/lib/activerecord/summarize/version.rb

@@ -2,6 +2,6 @@
 
 module ActiveRecord
   module Summarize
-    VERSION = "0.5.1"
+    VERSION = "0.6.0"
   end
 end

data/lib/activerecord/summarize.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "summarize/version"
+require_relative "summarize/calculation_implementation"
 require_relative "../chainable_result"
 
 module ActiveRecord::Summarize
@@ -130,58 +131,59 @@ module ActiveRecord::Summarize
       end
     end
 
-    def add_calculation(relation, operation, column_name)
+    def add_calculation(operation, relation, column_name)
       merge_from_where!(relation)
-      calculation = CalculationResult.new(relation, operation, column_name)
+      calculation = CalculationImplementation.new(operation, relation, column_name)
       index = @calculations.size
       @calculations << calculation
       ChainableResult.wrap(calculation) { current_result_row[index] }
     end
 
     def resolve
-      # Build & execute query
+      #########################
+      # Build & execute query #
+      #########################
       groups = all_groups
       # MariaDB, SQLite, and Postgres all support `GROUP BY 1, 2, 3`-style syntax,
-      # where the numbers are 1-indexed references to SELECT values. It makes these
-      # generated queries much shorter and more readable, and it avoids the
-      # ambiguity of using aliases (for GROUP BY, they can get clobbered by columns
-      # from underlying tables) even where those are supported. But in case we find
-      # a database that doesn't support numeric references, the fully-explicit
-      # grouping code is commented out below.
-      #
-      # grouped_query = groups.any? ? from_where.group(*groups) : from_where
+      # where the numbers are 1-indexed references to SELECT values.
       grouped_query = groups.any? ? from_where.group(*1..groups.size) : from_where
       data = grouped_query.pluck(*groups, *value_selects)
-      # .pluck(:one_column) returns an array of values instead of an array of arrays,
-      # which breaks the aggregation and assignment below in case anyone ever asks
-      # `summarize` for only one thing.
+
+      # .pluck(:just_one_column) returns an array of values instead of an array
+      # of arrays, which breaks the aggregation and assignment below.
       data = data.map { |d| [d] } if (groups.size + value_selects.size) == 1
 
-      # Aggregate & assign results
-      group_idx = groups.each_with_index.to_h
+      ##############################
+      # Build aggregation reducers #
+      ##############################
+      # groups includes all base groups and all sub-groups
+      group_idx = groups.each_with_index.to_h # Inverts the groups list: `[:foo, :bar]` becomes `{:foo => 0, :bar => 1}`
       starting_values, reducers = @calculations.each_with_index.map do |f, i|
         value_column = groups.size + i
+        # each calculation shares any base groups that exist and may have sub-groups, which won't be shared by others
         group_columns = f.relation.group_values.map { |k| group_idx[k] }
-        # `row[value_column] || 0` pattern in reducers because SQL SUM(NULL)
-        # returns NULL, but like ActiveRecord we always want .sum to return a
-        # number, and our "starting_values and reducers" implementation means
-        # we sometimes will have to add NULL to our numbers.
         case group_columns.size
         when 0 then [
-          0,
-          ->(memo, row) { memo + (row[value_column] || 0) }
+          f.initial,
+          ->(memo, row) { f.reducer(memo, row[value_column]) }
         ]
         when 1 then [
-          Hash.new(0), # Default 0 makes the reducer much cleaner, but we have to clean it up later
+          {},
           ->(memo, row) {
-            memo[row[group_columns[0]]] += row[value_column] unless (row[value_column] || 0).zero?
+            key = row[group_columns[0]]
+            prev_val = memo[key] || f.initial
+            next_val = f.reducer(prev_val, row[value_column])
+            memo[key] = next_val unless next_val == prev_val
             memo
           }
         ]
         else [
-          Hash.new(0),
+          {},
           ->(memo, row) {
-            memo[group_columns.map { |i| row[i] }] += row[value_column] unless (row[value_column] || 0).zero?
+            key = group_columns.map { |i| row[i] }
+            prev_val = memo[key] || f.initial
+            next_val = f.reducer(prev_val, row[value_column])
+            memo[key] = next_val unless next_val == prev_val
             memo
           }
         ]
@@ -199,8 +201,7 @@ module ActiveRecord::Summarize
               values[i] = reducers[i].call(values[i], row)
             end
           end
-          # Set any hash's default back to nil, since callers will expect a normal hash
-          values.each { |v| v.default = nil if v.is_a? Hash }
+          values
         end
     end
 
@@ -241,7 +242,7 @@ module ActiveRecord::Summarize
 
     def value_selects
       @calculations.each_with_index.map do |f, i|
-        f.select_value(@relation)
+        f.select_column_arel_node(@relation)
           .as("_v#{i}") # In Postgres with certain Rails versions, alias is needed to disambiguate result column names for type information
       end
     end
@@ -253,39 +254,6 @@ module ActiveRecord::Summarize
     end
   end
 
-  class CalculationResult
-    attr_reader :relation, :method, :column
-
-    def initialize(relation, method, column)
-      @relation = relation
-      @method = method
-      @column = column
-    end
-
-    def select_value(base_relation)
-      where = relation.where_clause - base_relation.where_clause
-      for_select = column
-      for_select = Arel::Nodes::Case.new(where.ast).when(true, for_select).else(unmatch_arel_node) unless where.empty?
-      function.new([for_select]).tap { |f| f.distinct = relation.distinct_value }
-    end
-
-    def unmatch_arel_node
-      case method
-      when "sum" then 0 # Adding zero to a sum does nothing
-      when "count" then nil # In SQL, null is no value and is not counted
-      else raise "Unknown calculation method"
-      end
-    end
-
-    def function
-      case method
-      when "sum" then Arel::Nodes::Sum
-      when "count" then Arel::Nodes::Count
-      else raise "Unknown calculation method"
-      end
-    end
-  end
-
   module RelationMethods
     def summarize(**opts, &block)
       raise Unsummarizable, "Cannot summarize within a summarize block" if @summarize
@@ -299,9 +267,23 @@ module ActiveRecord::Summarize
     def perform_calculation(operation, column_name)
       case operation = operation.to_s.downcase
       when "count", "sum"
-        column_name = :id if [nil, "*", :all].include? column_name
+        column_name = :id if [nil, "*", :all].include? column_name # only applies to count
         raise Unsummarizable, "DISTINCT in SQL is not reliably correct with summarize" if column_name.is_a?(String) && /\bdistinct\b/i === column_name
-        @summarize.add_calculation(self, operation, aggregate_column(column_name))
+        @summarize.add_calculation(operation, self, aggregate_column(column_name))
+      when "average"
+        ChainableResult::WITH_RESOLVED[
+          perform_calculation("sum", column_name),
+          perform_calculation("count", column_name)
+        ] do |sum, count|
+          if sum.is_a? Hash
+            sum.to_h { |key, s| [key, s.to_d / count[key]] }
+          else
+            next nil if count == 0
+            sum.to_d / count
+          end
+        end
+      when "minimum", "maximum"
+        @summarize.add_calculation(operation, self, aggregate_column(column_name))
       else super
       end
     end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: activerecord-summarize
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.6.0
 platform: ruby
 authors:
 - Joshua Paine
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-08-16 00:00:00.000000000 Z
+date: 2026-05-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -58,6 +58,7 @@ files:
 - docs/summarize_compared_with_load_async.md
 - docs/use_case_moderator_dashboard.md
 - lib/activerecord/summarize.rb
+- lib/activerecord/summarize/calculation_implementation.rb
 - lib/activerecord/summarize/version.rb
 - lib/chainable_result.rb
 - sig/activerecord/summarize.rbs