activerecord-hierarchical_query 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 031176cf523c47f50c3ca2a10b7c79129766b1e2
+  data.tar.gz: 9abc865a1f8e2bcbc42f084611b1d588ab7f8879
+SHA512:
+  metadata.gz: e5a632144805142246f4ba00cdf938b785660e5bac28063194782efbd446d901fc9154c79c8ee0c039d2d61e7afe4b10a58ff62a84115941653f5943cc137059
+  data.tar.gz: 7931d4bf31d74b4759ab93d779efdac40ef0cdb10f3b1d583bc9120a48395eeb5c9409ee48790ff626303bf47a4129d924df98c7b2c0613f9b638696e4b5c5ea

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Alexei Mikhailov
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,266 @@
+# ActiveRecord::HierarchicalQuery
+
+[![Build Status](https://travis-ci.org/take-five/activerecord-hierarchical_query.png?branch=master)](https://travis-ci.org/take-five/activerecord-hierarchical_query)
+[![Code Climate](https://codeclimate.com/github/take-five/activerecord-hierarchical_query.png)](https://codeclimate.com/github/take-five/activerecord-hierarchical_query)
+[![Coverage Status](https://coveralls.io/repos/take-five/activerecord-hierarchical_query/badge.png)](https://coveralls.io/r/take-five/activerecord-hierarchical_query)
+[![Dependency Status](https://gemnasium.com/take-five/activerecord-hierarchical_query.png)](https://gemnasium.com/take-five/activerecord-hierarchical_query)
+
+Create hierarchical queries using simple DSL, recursively traverse trees using single SQL query.
+
+If a table contains hierarchical data, then you can select rows in hierarchical order using hierarchical query builder.
+
+
+### Traverse descendants
+
+```ruby
+Category.join_recursive do |query|
+  query.start_with(:parent_id => nil)
+       .connect_by(:id => :parent_id)
+       .order_siblings(:name)
+end
+```
+
+### Traverse ancestors
+
+```ruby
+Category.join_recursive do |query|
+  query.start_with(:id => 42)
+       .connect_by(:parent_id => :id)
+end
+```
+
+## Requirements
+
+* ActiveRecord >= 3.1.0
+* PostgreSQL >= 8.4
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'activerecord-hierarchical_query'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install activerecord-hierarchical_query
+
+## Usage
+
+Let's say you've got an ActiveRecord model `Category` with attributes `id`, `parent_id`
+and `name`. You can traverse nodes recursively starting from root rows connected by
+`parent_id` column ordered by `name`:
+
+```ruby
+Category.join_recursive do
+  start_with(:parent_id => nil).
+  connect_by(:id => :parent_id).
+  order_siblings(:name)
+end
+```
+
+Hierarchical queries consist of these important clauses:
+
+* **START WITH** clause
+
+  This clause specifies the root row(s) of the hierarchy.
+* **CONNECT BY** clause
+
+  This clause specifies relationship between parent rows and child rows of the hierarchy.
+* **ORDER SIBLINGS** clause
+
+  This clause specifies an order of rows in which they appear on each hierarchy level.
+
+These terms are borrowed from [Oracle hierarchical queries syntax](http://docs.oracle.com/cd/B19306_01/server.102/b14200/queries003.htm).
+
+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)`.
+* 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
+  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
+  children and so on.
+
+### START WITH
+
+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) } }
+```
+
+All of these statements are equivalent.
+
+### CONNECT BY
+
+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) }
+
+# you can use block to build complex JOIN conditions
+Category.join_recursive do
+  connect_by do |parent_table, child_table|
+    parent_table[:id].eq child_table[:parent_id]
+  end
+end
+```
+
+### ORDER SIBLINGS
+
+You can specify order in which rows on each hierarchy level should appear:
+
+```ruby
+Category.join_recursive { order_siblings(:name) }
+
+# you can reverse order
+Category.join_recursive { order_siblings(:name => :desc) }
+
+# arbitrary strings and Arel nodes are allowed also
+Category.join_recursive { order_siblings('name ASC') }
+Category.join_recursive { |query| query.order_siblings(query.table[:name].asc) }
+```
+
+### WHERE conditions
+
+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 %')
+end
+```
+
+You can even refer to parent table, just don't forget to include columns in `SELECT` clause!
+
+```ruby
+Category.join_recursive do |query|
+  query.connect_by(:id => :parent_id)
+       .select(:name).
+       .where(query.prior[:name].matches('ruby %'))
+end
+```
+
+Or, if Arel semantics does not fit your needs:
+
+```ruby
+Category.join_recursive do |query|
+  query.connect_by(:id => :parent_id)
+       .where("#{query.prior.name}.name LIKE ?", 'ruby %')
+end
+```
+
+### NOCYCLE
+
+Recursive query will loop if hierarchy contains cycles (your graph is not acyclic).
+`NOCYCLE` clause, which is turned off by default, could prevent it.
+
+Loop example:
+
+```ruby
+node_1 = Category.create
+node_2 = Category.create(:parent => node_1)
+
+node_1.parent = node_2
+node_1.save
+```
+
+`node_1` and `node_2` now link to each other, so following query will never end:
+
+```ruby
+Category.join_recursive do |query|
+  query.connect_by(:id => :parent_id)
+       .start_with(:id => node_1.id)
+end
+```
+
+`#nocycle` method will prevent endless loop:
+
+```ruby
+Category.join_recursive do |query|
+  query.connect_by(:id => :parent_id)
+       .start_with(:id => node_1.id)
+       .nocycle
+end
+```
+
+## Generated SQL queries
+
+Under the hood this extensions builds `INNER JOIN` to recursive subquery.
+
+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)
+       .select(:depth)
+       .select(query.prior[:LEVEL] + 1, :start_with => false)
+       .where(query.prior[:depth].lteq(5))
+       .order_siblings(:position)
+       .nocycle
+end
+```
+
+would generate following SQL (if PostgreSQL used):
+
+```sql
+SELECT "categories".*
+FROM "categories" INNER JOIN (
+    WITH RECURSIVE "categories__recursive" AS (
+        SELECT depth,
+               0 LEVEL,
+               "categories"."id",
+               "categories"."parent_id",
+               ARRAY["categories"."position"] AS __order_column,
+               ARRAY["categories"."id"] AS __path
+        FROM "categories"
+        WHERE "categories"."parent_id" IS NULL
+
+        UNION ALL
+
+        SELECT "categories"."depth",
+               "categories__recursive"."LEVEL" + 1,
+               "categories"."id",
+               "categories"."parent_id",
+               "categories__recursive"."__order_column" || "categories"."position",
+               "categories__recursive"."__path" || "categories"."id"
+        FROM "categories" INNER JOIN
+             "categories__recursive" ON "categories__recursive"."id" = "categories"."parent_id"
+        WHERE ("categories__recursive"."depth" <= 5) AND
+              NOT ("categories"."id" = ANY("categories__recursive"."__path"))
+    )
+    SELECT "categories__recursive".* FROM "categories__recursive"
+) AS "categories__recursive" ON "categories"."id" = "categories__recursive"."id"
+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)
+* [Hierarchical queries in Oracle](http://docs.oracle.com/cd/B19306_01/server.102/b14200/queries003.htm)
+* [Recursive queries in PostgreSQL](http://www.postgresql.org/docs/9.3/static/queries-with.html)
+* [Using Recursive SQL with ActiveRecord trees](http://hashrocket.com/blog/posts/recursive-sql-in-activerecord)
+
+## Contributing
+
+1. Fork it ( http://github.com/take-five/activerecord-hierarchical_query/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/lib/active_record/hierarchical_query.rb

@@ -0,0 +1,53 @@
+# coding: utf-8
+
+require 'active_support/lazy_load_hooks'
+
+require 'active_record/hierarchical_query/version'
+require 'active_record/hierarchical_query/builder'
+require 'active_record/version'
+
+module ActiveRecord
+  module HierarchicalQuery
+    # @api private
+    DELEGATOR_SCOPE = ActiveRecord::VERSION::STRING < '4.0.0' ? :scoped : :all
+
+    # Performs a join to recursive subquery
+    # which should be built within a block.
+    #
+    # @example
+    #   MyModel.join_recursive do |query|
+    #     query.start_with(:parent_id => nil)
+    #          .connect_by(:id => :parent_id)
+    #          .where('depth < ?', 5)
+    #          .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
+    # @raise [ArgumentError] if block is omitted
+    def join_recursive(join_options = {}, &block)
+      raise ArgumentError, 'block expected' unless block_given?
+
+      builder = Builder.new(klass)
+
+      if block.arity == 0
+        builder.instance_eval(&block)
+      else
+        block.call(builder)
+      end
+
+      builder.join_to(self, join_options)
+    end
+  end
+end
+
+ActiveSupport.on_load(:active_record, :yield => true) do |base|
+  class << base
+    delegate :join_recursive, :to => ActiveRecord::HierarchicalQuery::DELEGATOR_SCOPE
+  end
+
+  ActiveRecord::Relation.send :include, ActiveRecord::HierarchicalQuery
+end

data/lib/active_record/hierarchical_query/adapters.rb

@@ -0,0 +1,20 @@
+# coding: utf-8
+
+module ActiveRecord
+  module HierarchicalQuery
+    module Adapters
+      SUPPORTED_ADAPTERS = %w(PostgreSQL)
+
+      autoload :PostgreSQL, 'active_record/hierarchical_query/adapters/postgresql'
+
+      def self.lookup(klass)
+        name = klass.connection.adapter_name
+
+        raise 'Your database does not support recursive queries' unless
+            SUPPORTED_ADAPTERS.include?(name)
+
+        const_get(name)
+      end
+    end # module Adapters
+  end # module HierarchicalQuery
+end # module ActiveRecord

data/lib/active_record/hierarchical_query/adapters/postgresql.rb

@@ -0,0 +1,29 @@
+# coding: utf-8
+
+require 'active_record/hierarchical_query/cte/query'
+
+module ActiveRecord
+  module HierarchicalQuery
+    module Adapters
+      # @api private
+      class PostgreSQL
+        attr_reader :builder,
+                    :table
+
+        delegate :klass, :to => :builder
+        delegate :build_join, :to => :@query
+
+        # @param [ActiveRecord::HierarchicalQuery::Builder] builder
+        def initialize(builder)
+          @builder = builder
+          @table = klass.arel_table
+          @query = CTE::Query.new(builder)
+        end
+
+        def prior
+          @query.recursive_table
+        end
+      end # class PostgreSQL
+    end # module Adapters
+  end # module HierarchicalQuery
+end # module ActiveRecord

data/lib/active_record/hierarchical_query/builder.rb

@@ -0,0 +1,289 @@
+# coding: utf-8
+
+require 'active_support/core_ext/array/extract_options'
+
+require 'active_record/hierarchical_query/adapters'
+
+module ActiveRecord
+  module HierarchicalQuery
+    class Builder
+      # @api private
+      attr_reader :klass,
+                  :start_with_value,
+                  :connect_by_value,
+                  :child_scope_value,
+                  :limit_value,
+                  :offset_value,
+                  :order_values,
+                  :nocycle_value
+
+      # @api private
+      CHILD_SCOPE_METHODS = :where, :joins, :group, :having
+
+      def initialize(klass)
+        @klass = klass
+        @adapter = Adapters.lookup(@klass).new(self)
+
+        @start_with_value = nil
+        @connect_by_value = nil
+        @child_scope_value = klass
+        @limit_value = nil
+        @offset_value = nil
+        @nocycle_value = false
+        @order_values = []
+      end
+
+      # Specify root scope of the hierarchy.
+      #
+      # @example When scope given
+      #   MyModel.join_recursive do |hierarchy|
+      #     hierarchy.start_with(MyModel.where(:parent_id => nil))
+      #              .connect_by(:id => :parent_id)
+      #   end
+      #
+      # @example When Hash given
+      #   MyModel.join_recursive do |hierarchy|
+      #     hierarchy.start_with(:parent_id => nil)
+      #              .connect_by(:id => :parent_id)
+      #   end
+      #
+      # @example When block given
+      #   MyModel.join_recursive do |hierarchy|
+      #     hierarchy.start_with { |root| root.where(:parent_id => nil) }
+      #              .connect_by(:id => :parent_id)
+      #   end
+      #
+      # @example When block with arity=0 given
+      #   MyModel.join_recursive do |hierarchy|
+      #     hierarchy.start_with { where(:parent_id => nil) }
+      #              .connect_by(:id => :parent_id)
+      #   end
+      #
+      # @example Specify columns for root relation (PostgreSQL-specific)
+      #   MyModel.join_recursive do |hierarchy|
+      #     hierarchy.start_with { select('ARRAY[id] AS _path') }
+      #              .connect_by(:id => :parent_id)
+      #              .select('_path || id', :start_with => false) # `:start_with => false` tells not to include this expression into START WITH clause
+      #   end
+      #
+      # @param [ActiveRecord::Relation, Hash, nil] scope root scope (optional).
+      # @return [ActiveRecord::HierarchicalQuery::Builder] self
+      def start_with(scope = nil, &block)
+        raise ArgumentError, 'START WITH: scope or block expected, none given' unless scope || block
+
+        case scope
+          when Hash
+            @start_with_value = klass.where(scope)
+
+          when ActiveRecord::Relation
+            @start_with_value = scope
+
+          else
+            # do nothing if something weird given
+        end
+
+        if block
+          object = @start_with_value || @klass
+
+          @start_with_value = if block.arity == 0
+                                object.instance_eval(&block)
+                              else
+                                block.call(object)
+                              end
+        end
+
+        self
+      end
+
+      # Specify relationship between parent rows and child rows of the
+      # hierarchy. It can be specified with Hash where keys are parent columns
+      # names and values are child columns names, or with block (see example below).
+      #
+      # @example Specify relationship with Hash (traverse descendants)
+      #   MyModel.join_recursive do |hierarchy|
+      #     # join child rows with condition `parent.id = child.parent_id`
+      #     hierarchy.connect_by(:id => :parent_id)
+      #   end
+      #
+      # @example Specify relationship with block (traverse descendants)
+      #   MyModel.join_recursive do |hierarchy|
+      #     hierarchy.connect_by { |parent, child| parent[:id].eq(child[:parent_id]) }
+      #   end
+      #
+      # @param [Hash, nil] conditions (optional) relationship between parent rows and
+      #   child rows map, where keys are parent columns names and values are child columns names.
+      # @yield [parent, child] Yields both parent and child tables.
+      # @yieldparam [Arel::Table] parent parent rows table instance.
+      # @yieldparam [Arel::Table] child child rows table instance.
+      # @yieldreturn [Arel::Nodes::Node] relationship condition expressed as Arel node.
+      # @return [ActiveRecord::HierarchicalQuery::Builder] self
+      def connect_by(conditions = nil, &block)
+        # convert hash to block which returns Arel node
+        if conditions
+          block = conditions_to_proc(conditions)
+        end
+
+        raise ArgumentError, 'CONNECT BY: Conditions hash or block expected, none given' unless block
+
+        @connect_by_value = block
+
+        self
+      end
+
+      # Specify which columns should be selected in addition to primary key,
+      # CONNECT BY columns and ORDER SIBLINGS columns.
+      #
+      # @param [Array<Symbol, String, Arel::Attributes::Attribute, Arel::Nodes::Node>] columns
+      # @option columns [true, false] :start_with include given columns to START WITH clause (true by default)
+      # @return [ActiveRecord::HierarchicalQuery::Builder] self
+      def select(*columns)
+        options = columns.extract_options!
+
+        columns = columns.flatten.map do |column|
+          column.is_a?(Symbol) ? table[column] : column
+        end
+
+        # TODO: detect if column already present in START WITH clause and skip it
+        if options.fetch(:start_with, true)
+          start_with { |scope| scope.select(columns) }
+        end
+
+        @child_scope_value = @child_scope_value.select(columns)
+
+        self
+      end
+
+      # Generate methods that apply filters to child scope, such as
+      # +where+ or +group+.
+      #
+      # @example Filter child nodes by certain condition
+      #   MyModel.join_recursive do |hierarchy|
+      #     hierarchy.where('depth < 5')
+      #   end
+      #
+      # @!method where(*conditions)
+      # @!method joins(*tables)
+      # @!method group(*values)
+      # @!method having(*conditions)
+      CHILD_SCOPE_METHODS.each do |method|
+        define_method(method) do |*args|
+          @child_scope_value = @child_scope_value.public_send(method, *args)
+
+          self
+        end
+      end
+
+      # Specifies a limit for the number of records to retrieve.
+      #
+      # @param [Fixnum] value
+      # @return [ActiveRecord::HierarchicalQuery::Builder] self
+      def limit(value)
+        @limit_value = value
+
+        self
+      end
+
+      # Specifies the number of rows to skip before returning row
+      #
+      # @param [Fixnum] value
+      # @return [ActiveRecord::HierarchicalQuery::Builder] self
+      def offset(value)
+        @offset_value = value
+
+        self
+      end
+
+      # Specifies hierarchical order of the recursive query results.
+      #
+      # @example
+      #   MyModel.join_recursive do |hierarchy|
+      #     hierarchy.connect_by(:id => :parent_id)
+      #              .order_siblings(:name)
+      #   end
+      #
+      # @example
+      #   MyModel.join_recursive do |hierarchy|
+      #     hierarchy.connect_by(:id => :parent_id)
+      #              .order_siblings('name DESC, created_at ASC')
+      #   end
+      #
+      # @param [<Symbol, String, Arel::Nodes::Node, Arel::Attributes::Attribute>] columns
+      # @return [ActiveRecord::HierarchicalQuery::Builder] self
+      def order_siblings(*columns)
+        @order_values += columns
+
+        self
+      end
+      alias_method :order, :order_siblings
+
+      # Turn on/off cycles detection. This option can prevent
+      # endless loops if your tree could contain cycles.
+      #
+      # @param [true, false] value
+      # @return [ActiveRecord::HierarchicalQuery::Builder] self
+      def nocycle(value = true)
+        @nocycle_value = value
+        self
+      end
+
+      # Returns object representing parent rows table,
+      # so it could be used in complex WHEREs.
+      #
+      # @example
+      #   MyModel.join_recursive do |hierarchy|
+      #     hierarchy.connect_by(:id => :parent_id)
+      #              .start_with(:parent_id => nil) { select(:depth) }
+      #              .select(hierarchy.table[:depth])
+      #              .where(hierarchy.prior[:depth].lteq 1)
+      #   end
+      #
+      # @return [Arel::Table]
+      def prior
+        @adapter.prior
+      end
+      alias_method :previous, :prior
+
+      # Returns object representing child rows table,
+      # so it could be used in complex WHEREs.
+      #
+      # @example
+      #   MyModel.join_recursive do |hierarchy|
+      #     hierarchy.connect_by(:id => :parent_id)
+      #              .start_with(:parent_id => nil) { select(:depth) }
+      #              .select(hierarchy.table[:depth])
+      #              .where(hierarchy.prior[:depth].lteq 1)
+      #   end
+      def table
+        @klass.arel_table
+      end
+
+      # Builds recursive query and joins it to given +relation+.
+      #
+      # @api private
+      # @param [ActiveRecord::Relation] relation
+      # @param [Hash] join_options
+      # @option join_options [#to_s] :as joined table alias
+      def join_to(relation, join_options = {})
+        raise 'Recursive query requires CONNECT BY clause, please use #connect_by method' unless
+            connect_by_value
+
+        table_alias = join_options.fetch(:as, "#{table.name}__recursive")
+
+        @adapter.build_join(relation, table_alias)
+      end
+
+      private
+      # converts conditions given as a hash to proc
+      def conditions_to_proc(conditions)
+        proc do |parent, child|
+          conditions.map do |parent_expression, child_expression|
+            parent_expression = parent[parent_expression] if parent_expression.is_a?(Symbol)
+            child_expression = child[child_expression] if child_expression.is_a?(Symbol)
+
+            Arel::Nodes::Equality.new(parent_expression, child_expression)
+          end.reduce(:and)
+        end
+      end
+    end # class Builder
+  end # module HierarchicalQuery
+end # module ActiveRecord