calculate-all 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: bcc98d3d676bc5db549074f9bd4f3e182f42ecb1
-  data.tar.gz: 0ec0592767487a7245339f4c4f7ac0c8a29c22c8
+  metadata.gz: beb910feb72d190c1d3cb8b5795accadfcb8871c
+  data.tar.gz: e80af03a1220682d3c333642df00812793daa7ac
 SHA512:
-  metadata.gz: ad855ac14b2c81caa8c849f0e9be8b28a8aeae0c87faf47e25a63e5b56739d63cc6c111211e170ec2b9757636d6c11b214ba937da5cd4caf05192f477ed34018
-  data.tar.gz: 2b3c94259c9d902722b31f203bb4620800fb863eea0fe12fb8561bb60dfc86177148704bb1b5de02ddd8b0d75290a46ed4b87843ddd2199229c2514579779685
+  metadata.gz: 16cce395e20d2caf89a3db8735dd3c488a24e13e29edfa8bc7bc3e5ff85dae1122673a0d6acc4162e61f81eeb0261ae5229a9f8c9d394d5d3ac8903a935262d6
+  data.tar.gz: e528558f62c977b231f896ab8b14d501f02788e103405f2dab019e50eab340db20e69e159ff0b6e8d5c710d988faa562e331987dfdd90994bfea16422fa71d06

data/Gemfile

@@ -3,5 +3,5 @@ source 'https://rubygems.org'
 # Specify your gem's dependencies in calculate-all.gemspec
 gemspec
 
-gem "activerecord"
-gem "pry"
+gem 'activerecord'
+gem 'pry'

data/README.md

@@ -4,64 +4,156 @@ Provides `#calculate_all` method on your Active Record models, scopes and relati
 It's a little addition to Active Record's `#count`, `#maximum`, `#minimum`, `#average` and `#sum`.
 It allows to fetch all of the above and any other aggregate functions results in one request, with respect to grouping.
 
-Tested only with Postgres and Mysql only right now. It relies on automatic values type-casting of underlying driver.
+Tested only with Postgres and MySQL only right now. It relies on automatic values type-casting of underlying driver.
 
 ## Usage
 
 ```ruby
-results = YourModel.yourscopes.group(:grouping1).group(:grouping2)
-  .calculate_all(:column1_max, :column2_distinct_count,
-    column3_median: 'percentile_cont(0.5) within group (order by column3 desc)')
+stats = Order.group(:department_id).group(:payment_method).calculate_all(
+  :count,
+  :count_distinct_user_id,
+  :price_max,
+  :price_min,
+  :price_avg,
+  price_median: 'percentile_cont(0.5) within group (order by price desc)'
+)
+#
+#   (2.2ms)  SELECT department_id, payment_method, percentile_cont(0.5) within group (order by price desc),
+#      COUNT(*), COUNT(DISTINCT user_id), MAX(price), MIN(price), AVG(price) FROM "orders" GROUP BY "department_id", "payment_method"
+#
+# => {
+#   [1, "cash"] => {
+#     count: 10,
+#     count_distinct_user_id: 5,
+#     price_max: 500,
+#     price_min: 100,
+#     price_avg: #<BigDecimal:7ff5932ff3d8,'0.3E3',9(27)>,
+#     price_median: #<BigDecimal:7ff5932ff3c2,'0.4E3',9(27)>
+#   },
+#   [1, "card"] => {
+#     ...
+#   }
+# }
 ```
 
+## Rationale
+
+Active Record allows to use most common DB aggregate functions, COUNT(), MAX(), MIN(), AVG(), SUM() really easy.
+But there's a whole world of wonderful other functions in
+[Postgres](http://www.postgresql.org/docs/9.5/static/functions-aggregate.html) which I can't recommend enough
+if you going to have any work with statistics and BI on your data, though MySQL has something
+[too](http://dev.mysql.com/doc/refman/5.7/en/group-by-functions.html).
+
+Also, in many cases you'll need several metrics at once, and database often has to perform a full scan on
+the table for each metric, but it as well can calculate them all in one scan and one request.
+
+`#calculate_all` to the rescue!
+
+## Arguments
+
+`#calculate_all` accepts a list of expression aliases and/or expression mapping.
+It could be either one string of SQL,
+
+```ruby
+  Model.calculate_all('SUM(price) / COUNT(DISTINCT user_id)')
+```
+
+a hash of expressions with arbitrary symbol keys
+
+```ruby
+  Model.calculate_all(total: 'COUNT(*)', average_spendings: 'SUM(price) / COUNT(DISTINCT user_id)')
+```
+or a list of one or more symbols without expressions, in which case `#calculate_all` tries to guess
+what you wanted from it.
+
+```ruby
+  Model.calculate_all(:count, :average_price, :sum_price)
+```
+
+It's not so smart right now, but here's a cheatsheet:
+
+| symbol                                                                 | would fetch
+|------------------------------------------------------------------------|------------
+| `:count`                                                               | `COUNT(*)`
+| `:count_column1`, `:column1_count`                                     | `COUNT(column1)` (doesn't count NULL's in that column)
+| `:count_distinct_column1`, `:column1_distinct_count`                   | `COUNT(DISTINCT column1)`
+| `:max_column1`, `:column1_max`, `:maximum_column1`, `:column1_maximum` | `MAX(column1)`
+| `:min_column1`, `:column1_min`, `:minimum_column1`, `:column1_minimum` | `MIN(column1)`
+| `:avg_column1`, `:column1_avg`, `:average_column1`, `:column1_average` | `AVG(column1)`
+| `:sum_column1`, `:column1_sum`                                         | `SUM(column1)`
+
+## Result
+
 `#calculate_all` tries to mimic magic of Active Record's `#group`, `#count` and `#pluck`
 so result type depends on arguments and on groupings.
 
-### Container
-
 If you have no `group()` on underlying scope, `#calculate_all` will return just one result.
+
+```ruby
+# same as Order.distinct.count(:user_id), so, probably useless example
+# but you can have any expression with aggregate functions there.
+Order.calculate_all('COUNT(DISTINCT user_id)')
+# => 50
+```
+
 If you have one group, it will return hash of results, with simple keys.
+
+```ruby
+# again, Order.group(:department_id).distinct.count(:user_id) would do the same
+Order.group(:department_id).calculate_all(:count_distinct_user_id)
+# => {
+#   1 => 20,
+#   2 => 10,
+#   ...
+# }
+```
+
 If you have two or more groupings, each result will have an array as a key.
 
-### Results
+```ruby
+Order.group(:department_id).group(:department_method).calculate_all(:count_distinct_user_id)
+# => {
+#   [1, "cash"] => 5,
+#   [1, "card"] => 15,
+#   [2, "cash"] => 1,
+#   ...
+# }
+```
 
 If you provide just one argument to `#calculate_all`, its calculated value will be returned as is.
 Otherwise results would be returned as hash(es) with symbol keys.
 
-so, `Model.calculate_all(:count)` will return just a single integer,
-but `Model.group(:foo1, :foo2).calculate_all(expr1: 'count(expr1)', expr2: 'count(expr2)')` will return
-something like this:
+so, `Order.calculate_all(:count)` will return just a single integer, but
 
 ```ruby
-{
-  ['foo1_1', 'foo2_1'] => {expr1: 0, expr2: 1},
-  ['foo1_1', 'foo2_2'] => {expr1: 2, expr2: 3},
-  ...
-}
+Order.group(:department_id).group(:payment_method).calculate_all(:min_price, expr1: 'count(distinct user_id)')
+# => {
+#   [1, 'cash'] => {min_price: 100, expr1: 5},
+#   [1, 'card'] => {min_price: 150, expr2: 15},
+#   ...
+# }
 ```
 
-### Conversion, formatting, value objects
-
 You can pass block to calculate_all. Rows will be passed to it and returned value will be used instead of
 row in result hash (or returned as is if there's no grouping)
 
 ```ruby
-  Order.group(:country_id).calculate_all(:count, :avg_price) { |count:, avg_price:|
-    "#{count} orders, #{avg_price.to_i} dollars average"
-  }
-  # => {
-  #   1 => "5 orders, 120 dollars average",
-  #   2 => "10 orders, 200 dollars average"
-  # }
-
-  Order.group(:country_id).calculate_all(:avg_price) { |avg_price| avg_price.to_i }
-  # => {
-  #   1 => 120,
-  #   2 => 200
-  # }
-
-  Order.calculate_all(:count, :max_price, &OpenStruct.method(:new))
-  # => #<OpenStruct max_price=500, count=15>
+Order.group(:country_id).calculate_all(:count, :avg_price) { |count:, avg_price:|
+  "#{count} orders, #{avg_price.to_i} dollars average"
+}
+# => {
+#   1 => "5 orders, 120 dollars average",
+#   2 => "10 orders, 200 dollars average"
+# }
+
+Order.group(:country_id).calculate_all(:avg_price) { |avg_price| avg_price.to_i }
+# => {
+#   1 => 120,
+#   2 => 200
+# }
+
+Order.calculate_all(:count, :max_price, &OpenStruct.method(:new))
+# => #<OpenStruct max_price=500, count=15>
 ```
 
 ## groupdate compatibility
@@ -69,14 +161,14 @@ row in result hash (or returned as is if there's no grouping)
 calculate-all should work with [groupdate](https://github.com/ankane/groupdate) too:
 
 ```ruby
-  Model.group_by_year(:created_at, last: 5, default_value: {}).calculate_all(:price_min, :price_max)
-  => {
-    Sun, 01 Jan 2012 00:00:00 UTC +00:00=>{},
-    Tue, 01 Jan 2013 00:00:00 UTC +00:00=>{},
-    Wed, 01 Jan 2014 00:00:00 UTC +00:00=>{},
-    Thu, 01 Jan 2015 00:00:00 UTC +00:00=>{},
-    Fri, 01 Jan 2016 00:00:00 UTC +00:00=>{:price_min=>100, :price_max=>500}
-  }
+Order.group_by_year(:created_at, last: 5, default_value: {}).calculate_all(:price_min, :price_max)
+=> {
+  Sun, 01 Jan 2012 => {},
+  Tue, 01 Jan 2013 => {},
+  Wed, 01 Jan 2014 => {},
+  Thu, 01 Jan 2015 => {},
+  Fri, 01 Jan 2016 => {:price_min=>100, :price_max=>500}
+}
 ```
 
 ## Installation

data/Rakefile

@@ -1,9 +1,9 @@
-require "bundler/gem_tasks"
-require "rake/testtask"
+require 'bundler/gem_tasks'
+require 'rake/testtask'
 
 Rake::TestTask.new(:test) do |t|
-  t.libs << "test"
-  t.libs << "lib"
+  t.libs << 'test'
+  t.libs << 'lib'
   t.test_files = FileList['test/**/*_test.rb']
 end
 

data/bin/console

@@ -1,10 +1,10 @@
 #!/usr/bin/env ruby
 
-require "bundler/setup"
-require "calculate-all"
+require 'bundler/setup'
+require 'calculate-all'
 
 require './test/test_helper'
 require 'logger'
 ActiveRecord::Base.logger = Logger.new(STDERR)
-require "pry"
+require 'pry'
 Pry.start

data/lib/calculate-all.rb

@@ -1,89 +1,84 @@
-require "calculate-all/version"
-require "active_record"
+require 'calculate-all/version'
+require 'calculate-all/helpers'
+require 'calculate-all/querying'
 
 module CalculateAll
+  # Method to aggregate function results in one request
   def calculate_all(*function_aliases, **functions, &block)
+
+    # If only one function_alias is given, the result can be just a single value
+    # So return [{ cash: 3 }] instead of [{ cash: { count: 3 }}]
     if function_aliases.size == 1 && functions == {}
       return_plain_values = true
     end
+
+    # Convert the function_aliases to actual SQL
     functions.merge!(
       CalculateAll::Helpers.decode_function_aliases(function_aliases)
     )
+
+    # Check if any functions are given
     if functions == {}
-      raise ArgumentError, "provide at least one function to calculate"
-    end
-    # groupdate compatibility
-    group_values = self.group_values
-    if !group_values.is_a?(Array) && group_values.respond_to?(:relation)
-      group_values = group_values.relation
+      raise ArgumentError, 'provide at least one function to calculate'
     end
+
+    # If function is called without a group, the pluck method will still return
+    # an array but it is an array with the final results instead of each group
+    # The plain_rows boolean states how the results should be used
     if functions.size == 1 && group_values.size == 0
       plain_rows = true
     end
 
+    # Final output hash
     results = {}
 
-    pluck(*group_values, *functions.values).each do |row|
+    # Fetch all the requested calculations from the database
+    # Note the map(&:to_s). It is required since groupdate returns a
+    # Groupdate::OrderHack instead of a string for the group_values which is not
+    # accepted by ActiveRecord's pluck method.
+    pluck(*group_values.map(&:to_s), *functions.values).each do |row|
+
+      # If no grouping, make sure it is still a results array
       row = [row] if plain_rows
+
+      # If only one value, return a single value, else return a hash
       if return_plain_values
         value = row.last
       else
         value = functions.keys.zip(row.last(functions.size)).to_h
       end
 
+      # Call the block for each group
       value = block.call(value) if block
 
       # Return unwrapped hash directly for scope without any .group()
       return value if group_values.empty?
 
+      # If only one group is provided, the resulting key is just the group name
+      # if multiple group methods are provided, the key will be an array.
       if group_values.size == 1
         key = row.first
       else
         key = row.first(group_values.size)
       end
+
+      # Set the value in the output array
       results[key] = value
     end
 
+    # Return the output array
     results
   end
-
-  module Helpers
-    module_function
-    def decode_function_aliases(aliases)
-      aliases.map do |key|
-        function =
-          case key
-          when String
-            key
-          when :count
-            "COUNT(*)"
-          when /^(.*)_distinct_count$/, /^count_distinct_(.*)$/
-            "COUNT(DISTINCT #{$1})"
-          when /^(.*)_(count|sum|max|min|avg)$/
-            "#{$2.upcase}(#{$1})"
-          when /^(count|sum|max|min|avg)_(.*)$$/
-            "#{$1.upcase}(#{$2})"
-          when /^(.*)_average$/, /^average_(.*)$/
-            "AVG(#{$1})"
-          when /^(.*)_maximum$/, /^maximum_(.*)$/
-            "MAX(#{$1})"
-          when /^(.*)_minimum$/, /^minimum_(.*)$/
-            "MIN(#{$1})"
-          else
-            raise ArgumentError, "Can't recognize function alias #{key}"
-          end
-        [key, function]
-      end.to_h
-    end
-  end
-  module Querying
-    delegate :calculate_all, to: :all
-  end
 end
 
-# should be:
-#   ActiveRecord::Relation.include CalculateAll
-# including in module instead, for groupdate compatibility
-ActiveRecord::Calculations.include CalculateAll
+# Make the calculate_all method available for all ActiveRecord::Relations instances
+ActiveRecord::Relation.include CalculateAll
 
+# Make the calculate_all method available for all ActiveRecord::Base classes
+# You can for example call Orders.calculate_all(:count, :sum_cents)
 ActiveRecord::Base.extend CalculateAll::Querying
+
+# A hack for groupdate since it checks if the calculate_all method is defined
+# on the ActiveRecord::Calculations module. It is never called but it is just
+# needed for the check.
+ActiveRecord::Calculations.include CalculateAll::Querying

data/lib/calculate-all/helpers.rb

@@ -0,0 +1,32 @@
+module CalculateAll
+  module Helpers
+    module_function
+    # Method to convert function aliases like :count to SQL commands like 'COUNT(*)'
+    def decode_function_aliases(aliases)
+      aliases.map do |key|
+        function =
+          case key
+          when String
+            key
+          when :count
+            'COUNT(*)'
+          when /^(.*)_distinct_count$/, /^count_distinct_(.*)$/
+            "COUNT(DISTINCT #{$1})"
+          when /^(.*)_(count|sum|max|min|avg)$/
+            "#{$2.upcase}(#{$1})"
+          when /^(count|sum|max|min|avg)_(.*)$$/
+            "#{$1.upcase}(#{$2})"
+          when /^(.*)_average$/, /^average_(.*)$/
+            "AVG(#{$1})"
+          when /^(.*)_maximum$/, /^maximum_(.*)$/
+            "MAX(#{$1})"
+          when /^(.*)_minimum$/, /^minimum_(.*)$/
+            "MIN(#{$1})"
+          else
+            raise ArgumentError, "Can't recognize function alias #{key}"
+          end
+        [key, function]
+      end.to_h
+    end
+  end
+end

data/lib/calculate-all/querying.rb

@@ -0,0 +1,5 @@
+module CalculateAll
+  module Querying
+    delegate :calculate_all, to: :all
+  end
+end

data/lib/calculate-all/version.rb

@@ -1,3 +1,3 @@
 module CalculateAll
-  VERSION = "0.1.1"
+  VERSION = '0.2.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: calculate-all
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - codesnik
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-02-13 00:00:00.000000000 Z
+date: 2017-01-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -126,6 +126,8 @@ files:
 - bin/setup
 - calculate-all.gemspec
 - lib/calculate-all.rb
+- lib/calculate-all/helpers.rb
+- lib/calculate-all/querying.rb
 - lib/calculate-all/version.rb
 homepage: http://github.com/codesnik/calculate-all
 licenses: