arlj 0.0.2 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a58db94fac67a5fa42539b8b1cc30beaf1134207
-  data.tar.gz: 3ffd40c1670e27ed4e6eefe82b20df628dd7b361
+  metadata.gz: 8d66639a751ea47513133e0ce7d6bbde7e3ea305
+  data.tar.gz: 7063bd9f2a5e51647a644f0ca0b5de206195866a
 SHA512:
-  metadata.gz: caf5c2c6a30881344c5f75074a5a1131263f68614574b28f3790a475008d638cd8745dbdbc3c0f0d7085d4bc863d112b310020b14ba06d3fa3613d133ef803d8
-  data.tar.gz: 5276383d71fdf062b199cd3370dfac5258fccf7856f5a753e8444dd5a741ab8d64ec19ba2c34b79d005e14d0286502ee4f89108bb5e5d49a159267ab7e2237ff
+  metadata.gz: 148bcbd399bec222d45e3aa1abf55d1b71fc97d258237a23ee882f239d4b1f8c838fc950e01a27ed256c8aef1a18c30457a1e4acd86a827e5a59b34b8aa05a4d
+  data.tar.gz: c9f80b5128245a37778974f82966802cbbcbc9ae68a5eef7bf30b3b3850cb44c38481ff96648dd922bffff102837f00bce4416afef7603782750d2ce03993dd7

data/README.md

@@ -45,30 +45,67 @@ puts Parent.left_joins(:children).group('records.id').select('COUNT(children.id)
     GROUP BY records.id
 ```
 
-`left_joins` is purposely low level to be extra chainable.
+`left_joins` is purposely low level for maximum control.
 
-Arlj also adds an aggregation method:
+Arlj has an aggregation method that is higher level and generally easier to use:
 
 ```ruby
-Parent.left_joins_aggregate(:children, 'COUNT(*)', 'SUM(col)' => 'total').select('children_count', 'total').to_sql
+Parent.left_joins_aggregate(:children, 'COUNT(*)').to_sql
+=> SELECT "parents".*
+     FROM "parents"
+     LEFT OUTER JOIN (SELECT "children"."parent_id"
+                           , COUNT("children"."id") AS children_count
+                        FROM "children"
+                       GROUP BY "children"."parent_id") arlj_aggregate_children
+                  ON arlj_aggregate_children."parent_id" = "parents"."id"
+```
+
+Supported aggregation functions are `COUNT()`, `SUM()`, `AVG()`, `MIN()`, and `MAX()`.
+
+The aggregation column has a default name of `{table}_{function}_{column}` which
+is easily renamed:
+
+```ruby
+Parent.left_joins_aggregate(:children, 'SUM(age)' => 'ekkekkekkekkeptangya').to_sql
+=> SELECT "parents".*
+     FROM "parents"
+     LEFT OUTER JOIN (SELECT "children"."parent_id"
+                           , SUM("children"."age") AS ekkekkekkekkeptangya
+                        FROM "children"
+                       GROUP BY "children"."parent_id") arlj_aggregate_children
+                  ON arlj_aggregate_children."parent_id" = "parents"."id"
+```
+
+Since Arlj uses a sub-select, you can easily chain additional queries:
+
+```ruby
+Parent.left_joins_aggregate(:children, 'COUNT(*)').select('children_count').to_sql
 => SELECT children_count
-        , total
      FROM "parents"
      LEFT OUTER JOIN (SELECT "children"."parent_id"
                            , COUNT("children"."id") AS children_count
-                           , SUM("children"."col") AS total
                         FROM "children"
                        GROUP BY "children"."parent_id") arlj_aggregate_children
                   ON arlj_aggregate_children."parent_id" = "parents"."id"
 ```
 
-`left_joins_aggregate` currently uses a subquery to hide its aggregation. It is
-not the most efficient implementation but it does offer a much better chaining
-experience than using `group` at the top level.
+Arlj also supports some basic where clauses:
+
+```ruby
+Parent.left_joins_aggregate(:children, 'COUNT(*)', where: {age: 1..5}).to_sql
+=> SELECT "parents".*
+     FROM "parents"
+     LEFT OUTER JOIN (SELECT "children"."parent_id"
+                           , COUNT("children"."id") AS children_count
+                        FROM "children"
+                       WHERE ("children"."age" BETWEEN 1 AND 5)
+                       GROUP BY "children"."parent_id") arlj_aggregate_children
+                  ON arlj_aggregate_children."parent_id" = "parents"."id"
+```
 
 If you prefer, you may also use `arlj` and `arlj_aggregate` instead of
 `left_joins` and `left_joins_aggregate` respectively. To prevent potential
-naming conflicts, please use `Arlj::Base`:
+naming conflicts, use `Arlj::Base` instead:
 
 ```ruby
 class Parent < ActiveRecord::Base
@@ -85,10 +122,18 @@ Arlj.memoize!
 
 This has not been proven to be faster.
 
+## Gotchas
+
+* Since `left_joins_aggregate` uses a sub-select for its aggregation, it can
+  underperform a better optimized query.
+
+* When `left_joins_aggregate` joins zero records, the aggregate column is NULL.
+  To operate correctly on these columns, please use `COALESCE(col, 0)`.
+
 ## TODO
 
-* Relations with conditions
-* `LEFT JOIN [...] ON`
+* `left_joins(nested: :relations)`
+* `left_joins_aggregate([...], merge: User.active)`
 * `has_and_belongs_to_many`
 * `has_many :through =>`
 

data/lib/arlj/base.rb

@@ -41,21 +41,26 @@ module Arlj
       refl = reflect_on_association(assoc)
       refl_arel = refl.klass.arel_table
 
-      join_name = "arlj_aggregate_#{refl.table_name}"
+      subq_ar = refl.klass.group(refl_arel[refl.foreign_key])
 
       columns = [refl_arel[refl.foreign_key]]
-      args.each do |thunk|
-        columns << parse_thunk(refl, assoc, refl_arel, thunk)
+      args.each do |arg|
+        columns << parse_directive(refl, assoc, refl_arel, arg)
       end
-      options.each do |thunk, name|
-        columns << parse_thunk(refl, assoc, refl_arel, thunk, name)
+      options.each do |key, value|
+        if directive?(key)
+          columns << parse_directive(refl, assoc, refl_arel, key, value)
+        elsif key.to_s == 'where'
+          subq_ar = subq_ar.send(key, value)
+        else
+          raise "'#{key.inspect} => #{value.inspect}' not recognized"
+        end
       end
 
-      subq_arel =
-        refl_arel.project(columns).
-                  from(refl_arel).
-                  group(refl_arel[refl.foreign_key]).
-                  as(join_name)
+      subq_arel = subq_ar.arel
+      subq_arel.projections.clear
+      subq_arel = subq_arel.project(columns).
+                    as("arlj_aggregate_#{refl.table_name}")
 
       arlj_left_join_arel(subq_arel, refl.foreign_key)
     end
@@ -66,7 +71,7 @@ module Arlj
 
     private
 
-    THUNK_PATTERN = /^([a-zA-Z]*)\((.*)\)$/
+    DIRECTIVE_PATTERN = /^([a-zA-Z]*)\((.*)\)$/
     AGGREGATE_FUNCTIONS = {
       'sum'     => 'sum',
       'average' => 'average',
@@ -77,10 +82,14 @@ module Arlj
       'min'     => 'minimum',
       'count'   => 'count',
     }.freeze
-    def parse_thunk(refl, assoc, arel, thunk, name=nil)
-      matchdata = THUNK_PATTERN.match(thunk)
+    def directive?(check)
+      DIRECTIVE_PATTERN =~ check
+    end
+
+    def parse_directive(refl, assoc, arel, directive, name=nil)
+      matchdata = DIRECTIVE_PATTERN.match(directive)
       if matchdata.nil?
-        raise "'#{thunk}' not parsable - must be of format 'func(column)'"
+        raise "'#{directive}' not parsable - must be of format 'func(column)'"
       end
 
       func = AGGREGATE_FUNCTIONS[matchdata[1].downcase]
@@ -98,6 +107,10 @@ module Arlj
       arel[column].send(func).as(name)
     end
 
+    def arel_node(value)
+      Arel::Nodes::SqlLiteral.new(value)
+    end
+
     def arlj_left_join_arel(arel, foreign_key)
       arel_table.join(arel, Arel::Nodes::OuterJoin).
                    on(arel[foreign_key].eq(arel_table[self.primary_key]))

data/lib/arlj/version.rb

@@ -1,3 +1,3 @@
 module Arlj
-  VERSION = "0.0.2"
+  VERSION = "0.1.0"
 end

data/spec/base_spec.rb

@@ -17,14 +17,14 @@ RSpec.describe Arlj::Base do
   Temping.create :child do
     with_columns do |t|
       t.integer :parent_id
-      t.integer :col
+      t.integer :age
     end
   end
 
   before(:all) do
     @parent = Parent.create(name: 'John')
     (1..10).each do |n|
-      @parent.children.create(col: n)
+      @parent.children.create(age: n)
     end
 
     @parent_no_child = Parent.create(name: 'Jane')
@@ -45,25 +45,42 @@ RSpec.describe Arlj::Base do
       assert{ children_count == @parent.children.size }
     end
 
-    specify 'sum(col)' do
-      children_sum_col = Parent.arlj_aggregate(:children, 'SUM(col)').pluck('children_sum_col').first
-      assert{ children_sum_col == @parent.children.sum(:col) }
+    specify 'sum(age)' do
+      children_sum_age = Parent.arlj_aggregate(:children, 'SUM(age)').pluck('children_sum_age').first
+      assert{ children_sum_age == @parent.children.sum(:age) }
     end
 
-    specify 'SUM(col) => name' do
-      sum = Parent.arlj_aggregate(:children, 'sum(col)' => 'sum').pluck('sum').first
-      assert{ sum == @parent.children.sum(:col) }
+    specify 'SUM(age) => name' do
+      sum = Parent.arlj_aggregate(:children, 'sum(age)' => 'sum').pluck('sum').first
+      assert{ sum == @parent.children.sum(:age) }
     end
 
-    specify 'FAKE(col) raises error' do
-      error = rescuing{ Parent.arlj_aggregate(:children, 'FAKE(col)') }
+    specify 'FAKE(age) raises error' do
+      error = rescuing{ Parent.arlj_aggregate(:children, 'FAKE(age)') }
       assert{ error }
     end
 
-    specify 'COUNT(*) => count, SUM(col) => sum' do
-      array = Parent.arlj_aggregate(:children, 'count(*)' => 'count', 'sum(col)' => 'sum').pluck('count', 'sum').first
+    specify 'COUNT(*) => count, SUM(age) => sum' do
+      array = Parent.arlj_aggregate(:children, 'count(*)' => 'count', 'sum(age)' => 'sum').pluck('count', 'sum').first
       assert{ array[0] == @parent.children.size }
-      assert{ array[1] == @parent.children.sum(:col) }
+      assert{ array[1] == @parent.children.sum(:age) }
+    end
+
+    context 'where' do
+      specify 'COUNT(*), where: "age > 4"' do
+        count = Parent.arlj_aggregate(:children, 'COUNT(*)', where: 'age > 4').pluck('children_count').first
+        assert{ count == @parent.children.where('age > 4').count }
+      end
+
+      specify 'SUM(age), where: {age: 1..4}' do
+        count = Parent.arlj_aggregate(:children, 'SUM(age)', where: {age: 1..4}).pluck('children_sum_age').first
+        assert{ count == @parent.children.where(age: 1..4).sum(:age) }
+      end
+
+      specify 'COUNT(age), where: ["age = ?", 1]' do
+        count = Parent.arlj_aggregate(:children, 'SUM(age)', where: ['age = ?', 8]).pluck('children_sum_age').first
+        assert{ count == 8 }
+      end
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: arlj
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.1.0
 platform: ruby
 authors:
 - Benjamin Feng
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-12-05 00:00:00.000000000 Z
+date: 2015-01-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -134,7 +134,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.2.2
+rubygems_version: 2.4.5
 signing_key: 
 specification_version: 4
 summary: ActiveRecord Left Join