active_record_extended 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b524c24c37e0b6f7449d70e5030b893119b98dec6646b905c3a307c9a671c7f1
-  data.tar.gz: 18cb235fba334ebfaa752b92ad024117f686176b0e9107af6333e317a333c70f
+  metadata.gz: 69a8ed712b33088a8aa79eb2d89ba86f645882d085d3bb752fb997eb1888b6af
+  data.tar.gz: a60306c9e2551606772007b683dee9477d7c87545569647c47a78e45a92b21bc
 SHA512:
-  metadata.gz: 78539255c169c26a1d6bab3968a2eed038d8391d532f97d55dabf7a7c071cddf4eee1424586021cd7b790db4abf042cf0617ac69ede670caeb9cde55a23125a4
-  data.tar.gz: 798ea355e5ebe213735db1552e7328d05c855c45800c941d4c5400a812b6d71f169ff52a48c0b9e6bf678d2dcf83ac1c7308a172b120caf9f83a240b0025e599
+  metadata.gz: 5530aaaf8f2f45aa1f7daaed6398eeac033cd50c3fb542a427dac4b9097c6ebffe08928f6d7a13bacdf9e04509f26f85ed607d4622e16423ced1308e079a2cf7
+  data.tar.gz: 8ca7691c2c23da13e8f1a409eeb5528ed47f01736f4cabbefa06fe441f56cae24ff504b1a0b31996645ef6bba7e2c308e1a8ee6254ee795d3a5fdbd15b0de57b

data/README.md

@@ -36,6 +36,9 @@
     - [Union As](#union-as)
     - [Union Order](#union-order)
     - [Union Reorder](#union-reorder)
+  - [Window Functions](#window-functions)
+    - [Define Window](#define-window)
+    - [Select Window](#select-window)
 
 ## Description and History
 
@@ -787,6 +790,80 @@ SELECT "people".*
   ) ) ORDER BY personal_id DESC, id DESC) people
 ```
 
+#### Window Functions
+[Postgres Window Functions](https://www.postgresql.org/docs/current/tutorial-window.html)
+
+Let's address the elephant in the room. Arel has had, for a long time now, window function capabilities; 
+However they've never seen the lime light in ActiveRecord's query logic. 
+The following brings the dormant Arel methods up to the ActiveRecord Querying level.
+
+#### Define Window
+
+To set up a window function, we first must establish the window and we do this by using the `.define_window/1` method.
+This method also requires you to call chain `.partition_by/2`
+
+`.define_window/1` - Establishes the name of the window you'll reference later on in [.select_window](#select-window) 
+   - Aliased name of window
+    
+`.partition_by/2`  - Establishes the windows operations a [pre-defined window function](https://www.postgresql.org/docs/current/functions-window.html) will leverage.
+   - column name being partitioned against
+   - (**optional**) `order_by`: Processes how the window should be ordered
+
+```ruby
+User
+.define_window(:number_window).partition_by(:number, order_by: { id: :desc })
+.define_window(:name_window).partition_by(:name, order_by: :id)
+.define_window(:no_order_name).partition_by(:name)
+```
+
+Query Output
+```sql
+SELECT *
+FROM users
+WINDOW number_window AS (PARTITION BY number ORDER BY id DESC),
+       name_window   AS (PARTITION BY name ORDER BY id),
+       no_order_name AS (PARTITION BY name)
+```
+
+#### Select Window
+
+Once you've define a window, the next step to to utilize it on one of the many provided postgres window functions.
+
+`.select_window/3`
+  - [window function name](https://www.postgresql.org/docs/current/functions-window.html)
+  - (**optional**) Window function arguments (treated as a splatted array)
+  - (**optional**) `as:` : Alias name of the final result
+  - `over:` : name of [defined window](#define-window)
+
+```ruby
+User.create!(name: "Alice", number: 100) #=> id: 1
+User.create!(name: "Randy", number: 100) #=> id: 2
+User.create!(name: "Bob", number: 300)   #=> id: 3
+
+User
+.define_window(:number_window).partition_by(:number, order_by: { id: :desc })
+.select(:id, :name)
+.select_window(:row_number, over: :number_window, as: :row_id)
+.select_window(:first_value, :name, over: :number_window, as: :first_value_name)
+#=> [
+ #  { id: 1, name: "Alice", row_id: 2, first_value_name: "Randy" }
+ #  { id: 2, name: "Randy", row_id: 1, first_value_name: "Randy" }
+ #  { id: 3, name: "Bob",   row_id: 1, first_value_name: "Bob" }
+ # ]
+ # 
+
+```
+
+Query Output
+```sql
+SELECT "users"."id", 
+        "users"."name", 
+        (ROW_NUMBER() OVER number_window)      AS "row_id", 
+        (FIRST_VALUE(name) OVER number_window) AS "first_value_name"
+FROM "users" 
+WINDOW number_window AS (PARTITION BY number ORDER BY id DESC)
+```
+
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/active_record_extended/active_record/relation_patch.rb

@@ -1,27 +1,29 @@
 # frozen_string_literal: true
 
+require "active_record_extended/query_methods/window"
 require "active_record_extended/query_methods/unionize"
 require "active_record_extended/query_methods/json"
 
 module ActiveRecordExtended
   module RelationPatch
     module QueryDelegation
-      delegate :with, :foster_select, to: :all
+      delegate :with, :define_window, :select_window, :foster_select, to: :all
       delegate(*::ActiveRecordExtended::QueryMethods::Unionize::UNIONIZE_METHODS, to: :all)
       delegate(*::ActiveRecordExtended::QueryMethods::Json::JSON_QUERY_METHODS, to: :all)
     end
 
     module Merger
       def normal_values
-        super + [:with, :union]
+        super + [:with, :union, :define_window]
       end
     end
 
     module ArelBuildPatch
       def build_arel(*aliases)
         super.tap do |arel|
-          build_unions(arel) if union_values?
-          build_with(arel)   if with_values?
+          build_windows(arel) if window_values?
+          build_unions(arel)  if union_values?
+          build_with(arel)    if with_values?
         end
       end
     end

data/lib/active_record_extended/query_methods/window.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module ActiveRecordExtended
+  module QueryMethods
+    module Window
+      class DefineWindowChain
+        include ::ActiveRecordExtended::Utilities::Support
+        include ::ActiveRecordExtended::Utilities::OrderBy
+
+        def initialize(scope, window_name)
+          @scope        = scope
+          @window_name  = window_name
+        end
+
+        def partition_by(*partitions, order_by: nil)
+          @scope.window_values! << {
+            window_name:  to_arel_sql(@window_name),
+            partition_by: flatten_to_sql(partitions),
+            order_by:     order_by_expression(order_by),
+          }
+
+          @scope
+        end
+      end
+
+      class WindowSelectBuilder
+        include ::ActiveRecordExtended::Utilities::Support
+
+        def initialize(window_function, args, window_name)
+          @window_function = window_function
+          @win_args        = to_sql_array(args)
+          @over            = to_arel_sql(window_name)
+        end
+
+        def build_select(alias_name = nil)
+          window_arel = generate_named_function(@window_function, *@win_args).over(@over)
+
+          if alias_name.nil?
+            window_arel
+          else
+            nested_alias_escape(window_arel, alias_name)
+          end
+        end
+      end
+
+      def window_values
+        @values.fetch(:window, [])
+      end
+
+      def window_values!
+        @values[:window] ||= []
+      end
+
+      def window_values?
+        !window_values.empty?
+      end
+
+      def window_values=(*values)
+        @values[:window] = values.flatten(1)
+      end
+
+      def define_window(name)
+        spawn.define_window!(name)
+      end
+
+      def define_window!(name)
+        DefineWindowChain.new(self, name)
+      end
+
+      def select_window(window_function, *args, over:, as: nil)
+        spawn.select_window!(window_function, args, over: over, as: as)
+      end
+
+      def select_window!(window_function, *args, over:, as: nil)
+        args.flatten!
+        args.compact!
+
+        select_statement = WindowSelectBuilder.new(window_function, args, over).build_select(as)
+        _select!(select_statement)
+      end
+
+      def build_windows(arel)
+        window_values.each do |window_value|
+          window = arel.window(window_value[:window_name]).partition(window_value[:partition_by])
+          window.order(window_value[:order_by]) if window_value[:order_by]
+        end
+      end
+    end
+  end
+end
+
+ActiveRecord::Relation.prepend(ActiveRecordExtended::QueryMethods::Window)

data/lib/active_record_extended/utilities/support.rb

@@ -30,7 +30,7 @@ module ActiveRecordExtended
       # Applies aliases to the given query
       # Ex: `SELECT * FROM users` => `(SELECT * FROM users) AS "members"`
       def nested_alias_escape(query, alias_name)
-        sql_query = Arel::Nodes::Grouping.new(to_arel_sql(query))
+        sql_query = generate_grouping(query)
         Arel::Nodes::As.new(sql_query, to_arel_sql(double_quote(alias_name)))
       end
 
@@ -160,13 +160,23 @@ module ActiveRecordExtended
 
       def group_when_needed(arel_or_rel_query)
         return arel_or_rel_query unless needs_to_be_grouped?(arel_or_rel_query)
-        Arel::Nodes::Grouping.new(to_arel_sql(arel_or_rel_query))
+        generate_grouping(arel_or_rel_query)
       end
 
       def needs_to_be_grouped?(query)
         query.respond_to?(:to_sql) || (query.is_a?(String) && /^SELECT.+/i.match?(query))
       end
 
+      def generate_grouping(expr)
+        ::Arel::Nodes::Grouping.new(to_arel_sql(expr))
+      end
+
+      def generate_named_function(function_name, *args)
+        args.map!(&method(:to_arel_sql))
+        function_name = function_name.to_s.upcase
+        ::Arel::Nodes::NamedFunction.new(to_arel_sql(function_name), args)
+      end
+
       def key_generator
         A_TO_Z_KEYS.sample
       end

data/lib/active_record_extended/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ActiveRecordExtended
-  VERSION = "1.2.0"
+  VERSION = "1.3.0"
 end

data/spec/query_methods/window_spec.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe "Active Record Window Function Query Methods" do
+  let!(:user_one)   { User.create! }
+  let!(:user_two)   { User.create! }
+
+  let!(:tag_one)    { Tag.create!(user: user_one, tag_number: 1) }
+  let!(:tag_two)    { Tag.create!(user: user_two, tag_number: 2) }
+
+  let!(:tag_three)  { Tag.create!(user: user_one, tag_number: 3) }
+  let!(:tag_four)   { Tag.create!(user: user_two, tag_number: 4) }
+
+  let(:tag_group1)  { [tag_one, tag_three] }
+  let(:tag_group2)  { [tag_two, tag_four] }
+
+  describe ".window_select" do
+    context "when using ROW_NUMBER() ordered in asc" do
+      let(:base_query) do
+        Tag.define_window(:w).partition_by(:user_id, order_by: :tag_number).select(:id)
+      end
+
+      it "should return tag_one with r_id 1 and tag_three with r_id 2" do
+        results = base_query.select_window(:row_number, over: :w, as: :r_id).group_by(&:id)
+        tag_group1.each.with_index { |tag, idx| expect(results[tag.id].first.r_id).to eq(idx + 1) }
+      end
+
+      it "should return tag_two with r_id 1 and tag_four with r_id 2" do
+        results = base_query.select_window(:row_number, over: :w, as: :r_id).group_by(&:id)
+        tag_group2.each.with_index { |tag, idx| expect(results[tag.id].first.r_id).to eq(idx + 1) }
+      end
+    end
+
+    context "when using ROW_NUMBER() ordered in desc" do
+      let(:base_query) do
+        Tag.define_window(:w).partition_by(:user_id, order_by: { tag_number: :desc }).select(:id)
+      end
+
+      it "should return tag_one with r_id 2 and tag_three with r_id 1" do
+        results = base_query.select_window(:row_number, over: :w, as: :r_id).group_by(&:id)
+        tag_group1.reverse_each.with_index { |tag, idx| expect(results[tag.id].first.r_id).to eq(idx + 1) }
+      end
+
+      it "should return tag_two with r_id 2 and tag_four with r_id 1" do
+        results = base_query.select_window(:row_number, over: :w, as: :r_id).group_by(&:id)
+        tag_group2.reverse_each.with_index { |tag, idx| expect(results[tag.id].first.r_id).to eq(idx + 1) }
+      end
+    end
+  end
+end

data/spec/sql_inspections/window_sql_spec.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe "Active Record WINDOW Query inspection" do
+  describe "#define_window" do
+    context "when there is a single defined window" do
+      it "should only contain a single defined window statement at the bottom" do
+        query = Tag.define_window(:w_test).partition_by(:user_id).to_sql
+        expect(query).to eq('SELECT "tags".* FROM "tags" WINDOW w_test AS (PARTITION BY user_id)')
+      end
+
+      it "should return a single defined window with a defined ORDER BY" do
+        query = Tag.define_window(:w_test).partition_by(:user_id, order_by: { tags: { user_id: :desc } }).to_sql
+        expect(query).to end_with("WINDOW w_test AS (PARTITION BY user_id ORDER BY tags.user_id DESC)")
+      end
+
+      it "should place the window function below the WHERE and GROUP BY statements" do
+        query = Tag.define_window(:w_test).partition_by(:user_id).where(id: 1).group(:user_id).to_sql
+        expect(query).to eq('SELECT "tags".* FROM "tags" WHERE "tags"."id" = 1 GROUP BY "tags"."user_id" WINDOW w_test AS (PARTITION BY user_id)')
+      end
+    end
+
+    context "when there are multiple defined windows" do
+      it "should only contain a single defined window statement at the bottom" do
+        query =
+          Tag
+          .define_window(:test).partition_by(:user_id)
+          .define_window(:other_window).partition_by(:id)
+          .to_sql
+
+        expect(query).to end_with("WINDOW test AS (PARTITION BY user_id), other_window AS (PARTITION BY id)")
+      end
+
+      it "should contain each windows order by statements" do
+        query =
+          Tag
+          .define_window(:test).partition_by(:user_id, order_by: :id)
+          .define_window(:other_window).partition_by(:id, order_by: { tags: :user_id })
+          .to_sql
+
+        expect(query).to end_with("WINDOW test AS (PARTITION BY user_id ORDER BY id), other_window AS (PARTITION BY id ORDER BY tags.user_id ASC)")
+      end
+    end
+  end
+
+  describe "#window_select" do
+    let(:query_base)   { Tag.define_window(:w).partition_by(:user_id, order_by: :id) }
+    let(:expected_end) { "WINDOW w AS (PARTITION BY user_id ORDER BY id)" }
+
+    context "when using no argument window methods" do
+      [:row_to_number, :rank, :dense_rank, :percent_rank, :cume_dist].each do |window_function|
+        context "#{window_function.to_s.upcase}()" do
+          let(:expected_function) { "#{window_function.to_s.upcase}()" }
+          let(:query) do
+            query_base.select_window(window_function, over: :w, as: :window_response).to_sql
+          end
+
+          it "appends the function to the select query" do
+            expected_start = "SELECT (#{expected_function} OVER w) AS \"window_response\""
+            expect(query).to start_with(expected_start).and(end_with(expected_end))
+          end
+        end
+      end
+    end
+
+    context "when using an argument based window method" do
+      let(:argument_list) { ["a", 1, :sauce] }
+
+      { ntile: 1, lag: 2, lead: 3, first_value: 1, last_value: 1, nth_value: 2 }.each_pair do |window_function, arg_count|
+        context "#{window_function.to_s.upcase}/#{arg_count}" do
+          let(:arguments)         { argument_list.first(arg_count) }
+          let(:expected_function) { "#{window_function.to_s.upcase}(#{arguments.join(', ')})" }
+          let(:query) do
+            query_base.select_window(window_function, *arguments, over: :w, as: :window_response).to_sql
+          end
+
+          it "appends the function to the select query" do
+            expected_start = "SELECT (#{expected_function} OVER w) AS \"window_response\""
+            expect(query).to start_with(expected_start).and(end_with(expected_end))
+          end
+        end
+      end
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: active_record_extended
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.3.0
 platform: ruby
 authors:
 - George Protacio-Karaszi
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-08-11 00:00:00.000000000 Z
+date: 2019-09-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -166,6 +166,7 @@ files:
 - lib/active_record_extended/query_methods/select.rb
 - lib/active_record_extended/query_methods/unionize.rb
 - lib/active_record_extended/query_methods/where_chain.rb
+- lib/active_record_extended/query_methods/window.rb
 - lib/active_record_extended/query_methods/with_cte.rb
 - lib/active_record_extended/utilities/order_by.rb
 - lib/active_record_extended/utilities/support.rb
@@ -179,6 +180,7 @@ files:
 - spec/query_methods/json_spec.rb
 - spec/query_methods/select_spec.rb
 - spec/query_methods/unionize_spec.rb
+- spec/query_methods/window_spec.rb
 - spec/query_methods/with_cte_spec.rb
 - spec/spec_helper.rb
 - spec/sql_inspections/any_of_sql_spec.rb
@@ -189,6 +191,7 @@ files:
 - spec/sql_inspections/either_sql_spec.rb
 - spec/sql_inspections/json_sql_spec.rb
 - spec/sql_inspections/unionize_sql_spec.rb
+- spec/sql_inspections/window_sql_spec.rb
 - spec/sql_inspections/with_cte_sql_spec.rb
 - spec/support/database_cleaner.rb
 - spec/support/models.rb
@@ -226,6 +229,7 @@ test_files:
 - spec/query_methods/json_spec.rb
 - spec/query_methods/select_spec.rb
 - spec/query_methods/unionize_spec.rb
+- spec/query_methods/window_spec.rb
 - spec/query_methods/with_cte_spec.rb
 - spec/spec_helper.rb
 - spec/sql_inspections/any_of_sql_spec.rb
@@ -236,6 +240,7 @@ test_files:
 - spec/sql_inspections/either_sql_spec.rb
 - spec/sql_inspections/json_sql_spec.rb
 - spec/sql_inspections/unionize_sql_spec.rb
+- spec/sql_inspections/window_sql_spec.rb
 - spec/sql_inspections/with_cte_sql_spec.rb
 - spec/support/database_cleaner.rb
 - spec/support/models.rb