activerecord-hierarchical_query 0.0.2 → 0.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e317315d0b567e0880277e328380478df97fecd7
-  data.tar.gz: f1918a2d4c9a9e8a84f59b7af8fec42d6fb57dfa
+  metadata.gz: 76f5e82aca51ebd96a9cc00a729b5f418e6fa385
+  data.tar.gz: 3ea6fa61b8b16e6ca0e18948d9280c70417a6386
 SHA512:
-  metadata.gz: aad9047098ff944791fd13f5fed4a120e39195d3f9f4d08a17f5e734dfc8e7409e2a034acec7e0200df336c4a530003ebca1d68c2a494fac9629db3d253ace5f
-  data.tar.gz: 890c7ebfff9df375347f00c061ed213167fe8e09da1cf567996afc9ca5417f264215c270e987a9e8a16925284d0f9cbafc842c2f26d8c8fd142dfd29761e88d9
+  metadata.gz: 5af1b963cdc7763d04a445c1ef248c0ac53bef531b45b15a20cc7a3743e34291a8a0b92bd79786cfec44a60c64f517679f0da57520eeb630665a23d84832b8e6
+  data.tar.gz: f5c489b92a0422ac00dbaec5f6df28ef931e7b835c4a0b7a3f99d95a6e66e8c2616932f19b858b6772fc91f72a9d4b640b6a684c7dbdaee5daeb347202a98301

data/README.md

@@ -10,29 +10,62 @@ Create hierarchical queries using simple DSL, recursively traverse trees using s
 
 If a table contains hierarchical data, then you can select rows in hierarchical order using hierarchical query builder.
 
+### Traverse trees
+
+Let's say you've got an ActiveRecord model `Category` that related to itself:
+
+```ruby
+class Category < ActiveRecord::Base
+  belongs_to :parent, class_name: 'Category'
+  has_many :children, foreign_key: :parent_id, class_name: 'Category'
+end
+
+# Table definition
+# create_table :categories do |t|
+#   t.integer :parent_id
+#   t.string :name
+# end
+```
 
 ### Traverse descendants
 
 ```ruby
 Category.join_recursive do |query|
-  query.start_with(:parent_id => nil)
-       .connect_by(:id => :parent_id)
+  query.start_with(parent_id: nil)
+       .connect_by(id: :parent_id)
        .order_siblings(:name)
-end
+end # returns ActiveRecord::Relation instance
 ```
 
 ### Traverse ancestors
 
 ```ruby
 Category.join_recursive do |query|
-  query.start_with(:id => 42)
-       .connect_by(:parent_id => :id)
+  query.start_with(id: 42)
+       .connect_by(parent_id: :id)
 end
 ```
 
+### Show breadcrumbs using single SQL query
+
+```ruby
+records = Category.join_recursive do |query|
+  query
+    # assume that deepest node has depth=0
+    .start_with(id: 42) { select('0 depth') }
+    # for each ancestor decrease depth by 1, do not apply
+    # following expression to first level of hierarchy
+    .select(query.prior[:depth] - 1, start_with: false)
+    .connect_by(parent_id: :id)
+end.order('depth ASC')
+
+# returned value is just regular ActiveRecord::Relation instance, so you can use its methods
+crumbs = records.pluck(:name).join(' / ')
+```
+
 ## Requirements
 
-* ActiveRecord >= 3.1.0
+* ActiveRecord >= 3.1.0 (Rails 4.2 included)
 * PostgreSQL >= 8.4
 
 ## Installation
@@ -57,8 +90,8 @@ and `name`. You can traverse nodes recursively starting from root rows connected
 
 ```ruby
 Category.join_recursive do
-  start_with(:parent_id => nil).
-  connect_by(:id => :parent_id).
+  start_with(parent_id: nil).
+  connect_by(id: :parent_id).
   order_siblings(:name)
 end
 ```
@@ -81,10 +114,10 @@ Hierarchical queries are processed as follows:
 
 * First, root rows are selected -- those rows that satisfy `START WITH` condition in
   order specified by `ORDER SIBLINGS` clause. In example above it's specified by
-  statements `query.start_with(:parent_id => nil)` and `query.order_siblings(:name)`.
+  statements `query.start_with(parent_id: nil)` and `query.order_siblings(:name)`.
 * Second, child rows for each root rows are selected. Each child row must satisfy
   condition specified by `CONNECT BY` clause with respect to one of the root rows
-  (`query.connect_by(:id => :parent_id)` in example above). Order of child rows is
+  (`query.connect_by(id: :parent_id)` in example above). Order of child rows is
   also specified by `ORDER SIBLINGS` clause.
 * Successive generations of child rows are selected with respect to `CONNECT BY` clause.
   First the children of each row selected in step 2 selected, then the children of those
@@ -95,9 +128,9 @@ Hierarchical queries are processed as follows:
 This clause is specified by `start_with` method:
 
 ```ruby
-Category.join_recursive { start_with(:parent_id => nil) }
-Category.join_recursive { start_with { where(:parent_id => nil) } }
-Category.join_recursive { start_with { |root_rows| root_rows.where(:parent_id => nil) } }
+Category.join_recursive { start_with(parent_id: nil) }
+Category.join_recursive { start_with { where(parent_id: nil) } }
+Category.join_recursive { start_with { |root_rows| root_rows.where(parent_id: nil) } }
 ```
 
 All of these statements are equivalent.
@@ -108,7 +141,7 @@ This clause is necessary and specified by `connect_by` method:
 
 ```ruby
 # join parent table ID columns and child table PARENT_ID column
-Category.join_recursive { connect_by(:id => :parent_id) }
+Category.join_recursive { connect_by(id: :parent_id) }
 
 # you can use block to build complex JOIN conditions
 Category.join_recursive do
@@ -126,7 +159,7 @@ You can specify order in which rows on each hierarchy level should appear:
 Category.join_recursive { order_siblings(:name) }
 
 # you can reverse order
-Category.join_recursive { order_siblings(:name => :desc) }
+Category.join_recursive { order_siblings(name: :desc) }
 
 # arbitrary strings and Arel nodes are allowed also
 Category.join_recursive { order_siblings('name ASC') }
@@ -139,7 +172,7 @@ You can filter rows on each hierarchy level by applying `WHERE` conditions:
 
 ```ruby
 Category.join_recursive do
-  connect_by(:id => :parent_id).where('name LIKE ?', 'ruby %')
+  connect_by(id: :parent_id).where('name LIKE ?', 'ruby %')
 end
 ```
 
@@ -147,7 +180,7 @@ You can even refer to parent table, just don't forget to include columns in `SEL
 
 ```ruby
 Category.join_recursive do |query|
-  query.connect_by(:id => :parent_id)
+  query.connect_by(id: :parent_id)
        .select(:name).
        .where(query.prior[:name].matches('ruby %'))
 end
@@ -157,7 +190,7 @@ Or, if Arel semantics does not fit your needs:
 
 ```ruby
 Category.join_recursive do |query|
-  query.connect_by(:id => :parent_id)
+  query.connect_by(id: :parent_id)
        .where("#{query.prior.name}.name LIKE ?", 'ruby %')
 end
 ```
@@ -171,7 +204,7 @@ Loop example:
 
 ```ruby
 node_1 = Category.create
-node_2 = Category.create(:parent => node_1)
+node_2 = Category.create(parent: node_1)
 
 node_1.parent = node_2
 node_1.save
@@ -181,8 +214,8 @@ node_1.save
 
 ```ruby
 Category.join_recursive do |query|
-  query.connect_by(:id => :parent_id)
-       .start_with(:id => node_1.id)
+  query.connect_by(id: :parent_id)
+       .start_with(id: node_1.id)
 end
 ```
 
@@ -190,8 +223,8 @@ end
 
 ```ruby
 Category.join_recursive do |query|
-  query.connect_by(:id => :parent_id)
-       .start_with(:id => node_1.id)
+  query.connect_by(id: :parent_id)
+       .start_with(id: node_1.id)
        .nocycle
 end
 ```
@@ -204,10 +237,10 @@ For example, this piece of code
 
 ```ruby
 Category.join_recursive do |query|
-  query.start_with(:parent_id => nil) { select('0 LEVEL') }
-       .connect_by(:id => :parent_id)
+  query.start_with(parent_id: nil) { select('0 LEVEL') }
+       .connect_by(id: :parent_id)
        .select(:depth)
-       .select(query.prior[:LEVEL] + 1, :start_with => false)
+       .select(query.prior[:LEVEL] + 1, start_with: false)
        .where(query.prior[:depth].lteq(5))
        .order_siblings(:position)
        .nocycle
@@ -247,10 +280,6 @@ FROM "categories" INNER JOIN (
 ORDER BY "categories__recursive"."__order_column" ASC
 ```
 
-## Future plans
-
-* Oracle support
-
 ## Related resources
 
 * [About hierarchical queries (Wikipedia)](http://en.wikipedia.org/wiki/Hierarchical_and_recursive_queries_in_SQL)

data/lib/active_record/hierarchical_query.rb

@@ -3,7 +3,7 @@
 require 'active_support/lazy_load_hooks'
 
 require 'active_record/hierarchical_query/version'
-require 'active_record/hierarchical_query/builder'
+require 'active_record/hierarchical_query/query'
 require 'active_record/version'
 
 module ActiveRecord
@@ -16,37 +16,37 @@ module ActiveRecord
     #
     # @example
     #   MyModel.join_recursive do |query|
-    #     query.start_with(:parent_id => nil)
-    #          .connect_by(:id => :parent_id)
+    #     query.start_with(parent_id: nil)
+    #          .connect_by(id: :parent_id)
     #          .where('depth < ?', 5)
-    #          .order_siblings(:name => :desc)
+    #          .order_siblings(name: :desc)
     #   end
     #
     # @param [Hash] join_options
     # @option join_options [String, Symbol] :as aliased name of joined
     #   table (`%table_name%__recursive` by default)
     # @yield [query]
-    # @yieldparam [ActiveRecord::HierarchicalQuery::Builder] query Hierarchical query builder
+    # @yieldparam [ActiveRecord::HierarchicalQuery::Query] query Hierarchical query
     # @raise [ArgumentError] if block is omitted
     def join_recursive(join_options = {}, &block)
       raise ArgumentError, 'block expected' unless block_given?
 
-      builder = Builder.new(klass)
+      query = Query.new(klass)
 
       if block.arity == 0
-        builder.instance_eval(&block)
+        query.instance_eval(&block)
       else
-        block.call(builder)
+        block.call(query)
       end
 
-      builder.join_to(self, join_options)
+      query.join_to(self, join_options)
     end
   end
 end
 
-ActiveSupport.on_load(:active_record, :yield => true) do |base|
+ActiveSupport.on_load(:active_record, yield: true) do |base|
   class << base
-    delegate :join_recursive, :to => ActiveRecord::HierarchicalQuery::DELEGATOR_SCOPE
+    delegate :join_recursive, to: ActiveRecord::HierarchicalQuery::DELEGATOR_SCOPE
   end
 
   ActiveRecord::Relation.send :include, ActiveRecord::HierarchicalQuery

data/lib/active_record/hierarchical_query/cte/columns.rb

@@ -4,7 +4,7 @@ module ActiveRecord
   module HierarchicalQuery
     module CTE
       class Columns
-        # @param [ActiveRecord::HierarchicalQuery::CTE::Query] query
+        # @param [ActiveRecord::HierarchicalQuery::Query] query
         def initialize(query)
           @query = query
         end
@@ -18,20 +18,7 @@ module ActiveRecord
 
         private
         def connect_by_columns
-          extractor.call(@query.join_conditions).map { |column| column.name.to_s }
-        end
-
-        def extractor
-          target = []
-
-          ->(arel) {
-            visitor = Arel::Visitors::DepthFirst.new do |node|
-              target << node if node.is_a?(Arel::Attributes::Attribute)
-            end
-            visitor.accept(arel)
-
-            target
-          }
+          @query.join_conditions.grep(Arel::Attributes::Attribute) { |column| column.name.to_s }
         end
       end
     end

data/lib/active_record/hierarchical_query/cte/cycle_detector.rb

@@ -0,0 +1,54 @@
+module ActiveRecord
+  module HierarchicalQuery
+    module CTE
+      class CycleDetector
+        COLUMN_NAME = '__path'.freeze
+
+        delegate :klass, :table, to: :@query
+
+        # @param [ActiveRecord::HierarchicalQuery::Query] query
+        def initialize(query)
+          @query = query
+        end
+
+        def apply_to_non_recursive(arel)
+          if enabled?
+            arel.project Arel::Nodes::PostgresArray.new([primary_key]).as(column_name)
+          end
+
+          arel
+        end
+
+        def apply_to_recursive(arel)
+          if enabled?
+            arel.project Arel::Nodes::ArrayConcat.new(parent_column, primary_key)
+            arel.constraints << Arel::Nodes::Not.new(primary_key.eq(any(parent_column)))
+          end
+
+          arel
+        end
+
+        private
+        def enabled?
+          @query.nocycle_value
+        end
+
+        def column_name
+          COLUMN_NAME
+        end
+
+        def parent_column
+          @query.recursive_table[column_name]
+        end
+
+        def primary_key
+          table[klass.primary_key]
+        end
+
+        def any(argument)
+          Arel::Nodes::NamedFunction.new('ANY', [argument])
+        end
+      end
+    end
+  end
+end

data/lib/active_record/hierarchical_query/cte/non_recursive_term.rb

@@ -6,26 +6,47 @@ module ActiveRecord
       class NonRecursiveTerm
         DISALLOWED_CLAUSES = :order, :limit, :offset, :group, :having
 
-        attr_reader :query
-        delegate :builder, :adapter, :to => :query
-        delegate :start_with_value, :klass, :to => :builder
+        attr_reader :builder
+        delegate :query, to: :builder
 
-        # @param [ActiveRecord::HierarchicalQuery::CTE::Query] query
-        def initialize(query)
-          @query = query
+        # @param [ActiveRecord::HierarchicalQuery::CTE::QueryBuilder] builder
+        def initialize(builder)
+          @builder = builder
+        end
+
+        def bind_values
+          scope.bind_values
         end
 
         def arel
-          arel = scope.select(query.columns)
-                      .except(*DISALLOWED_CLAUSES)
-                      .arel
+          arel = scope.arel
 
-          adapter.visit(:non_recursive, arel)
+          builder.cycle_detector.apply_to_non_recursive(arel)
         end
 
         private
         def scope
-          start_with_value || klass.__send__(HierarchicalQuery::DELEGATOR_SCOPE)
+          @scope ||= query.
+              start_with_value.
+              select(columns).
+              except(*DISALLOWED_CLAUSES)
+        end
+
+        def columns
+          columns = builder.columns.to_a
+
+          if query.orderings.any?
+            columns << ordering
+          end
+
+          columns
+        end
+
+        def ordering
+          value = query.orderings.row_number_expression
+          column_name = query.ordering_column_name
+
+          Arel::Nodes::PostgresArray.new([value]).as(column_name)
         end
       end # class NonRecursiveTerm
     end

data/lib/active_record/hierarchical_query/cte/query_builder.rb

@@ -0,0 +1,82 @@
+# coding: utf-8
+
+require 'active_record/hierarchical_query/cte/columns'
+require 'active_record/hierarchical_query/cte/cycle_detector'
+require 'active_record/hierarchical_query/cte/union_term'
+
+module ActiveRecord
+  module HierarchicalQuery
+    module CTE
+      # CTE query builder
+      class QueryBuilder
+        attr_reader :query,
+                    :columns,
+                    :cycle_detector
+
+        delegate :klass, :table, :recursive_table, to: :query
+
+        # @param [ActiveRecord::HierarchicalQuery::Query] query
+        def initialize(query)
+          @query = query
+          @columns = Columns.new(@query)
+          @cycle_detector = CycleDetector.new(@query)
+        end
+
+        def bind_values
+          union_term.bind_values
+        end
+
+        # @return [Arel::SelectManager]
+        def build_arel
+          build_manager
+          build_select
+          build_limits
+          build_order
+
+          @arel
+        end
+
+        private
+        def build_manager
+          @arel = Arel::SelectManager.new(table.engine).
+              with(:recursive, with_query).
+              from(recursive_table)
+        end
+
+        # "categories__recursive" AS (
+        #   SELECT ... FROM "categories"
+        #   UNION ALL
+        #   SELECT ... FROM "categories"
+        #   INNER JOIN "categories__recursive" ON ...
+        # )
+        def with_query
+          Arel::Nodes::As.new(recursive_table, union_term.arel)
+        end
+
+        def union_term
+          @union_term ||= UnionTerm.new(self)
+        end
+
+        def build_select
+          @arel.project(recursive_table[Arel.star])
+        end
+
+        def build_limits
+          @arel.take(query.limit_value).skip(query.offset_value)
+        end
+
+        def build_order
+          @arel.order(order_column.asc) if should_order?
+        end
+
+        def should_order?
+          query.orderings.any? && (query.limit_value || query.offset_value)
+        end
+
+        def order_column
+          recursive_table[query.ordering_column_name]
+        end
+      end
+    end
+  end
+end