cuatlan-activerecord-hierarchical_query 1.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 12a45b3c8eccd84634a044029ebf6b5bf893de28f46a4ee00a74d8254a9eed88
+  data.tar.gz: c22d63e8514cea22bb2acb9e9f2ede158d17a1f62eb470a937943c9620f78639
+SHA512:
+  metadata.gz: 6cf8660bcdace09d9b4cac59decf97bb955be87aef4a2363c908a087d075ee4c4d04a1fed2d240d8908fd25751428798f13adfad01eb5318b4f70acb87959f1b
+  data.tar.gz: cc4a27033c075bcc77b78c4a3743a81d6a99e78383ada23c039adef286e649d43aa15322f5e155e140d80a4ceaf3811c8df07d138d2c47b0a4910701cc029b1d

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,356 @@
+# LOOKING FOR MAINTAINER
+
+I'm sorry but I can't maintain this project anymore.
+
+If you want to maintain this project, contact me (amikhailov83[at]gmail.com) and I will grant you all necessary permissions.
+
+# 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)
+[![Gem Version](https://badge.fury.io/rb/activerecord-hierarchical_query.png)](http://badge.fury.io/rb/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 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)
+       .order_siblings(:name)
+end # returns ActiveRecord::Relation instance
+```
+
+### Traverse ancestors
+
+```ruby
+Category.join_recursive do |query|
+  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
+* PostgreSQL >= 8.4
+
+## Rails 5
+
+Rails 5 is supported on the `rails-5` branch and through gem versions
+`>= 1.0.0` on rubygems.org. The Rails branch is intended to
+follow minor Rails releases (currently 5.1), but it should be
+compatible with 5.0 as well. If you have trouble try upgrading Rails
+first. Tag @zachaysan with in a GitHub issue if the latest version
+of Rails is not supported or if there are reproducable problems on
+the latest minor version of Rails 5.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'activerecord-hierarchical_query'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install activerecord-hierarchical_query
+
+You'll then need to require the gem:
+
+```ruby
+require 'active_record/hierarchical_query'
+```
+
+Alternatively, the require can be placed in the `Gemfile`:
+
+```ruby
+gem 'activerecord-hierarchical_query', require: 'active_record/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
+```
+
+## DISTINCT
+By default, the union term in the Common Table Expression uses a `UNION ALL`. If you want
+to `SELECT DISTINCT` CTE values, add a query option for  `distinct`:
+```ruby
+Category.join_recursive do |query|
+  query.connect_by(id: :parent_id)
+       .start_with(id: node_1.id)
+       .distinct
+end
+```
+
+If you want to join CTE terms by `UNION DISTINCT`, pass an option to `join_recursive`:
+```ruby
+Category.join_recursive(union_type: :distinct) do |query|
+  query.connect_by(id: :parent_id)
+       .start_with(id: node_1.id)
+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
+```
+
+If you want to use a `LEFT OUTER JOIN` instead of an `INNER JOIN`, add a query option for `outer_join_hierarchical`.   This option allows the query to return non-hierarchical entries:
+```ruby
+  .join_recursive(outer_join_hierarchical: true)
+```
+
+If, when joining the recursive view to the main table, you want to change the foreign_key on the recursive view from the primary key of the main table to another column:
+```ruby
+.join_recursive(foreign_key: another_column)
+```
+
+## 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/query'
+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::Query] query Hierarchical query
+    # @raise [ArgumentError] if block is omitted
+    def join_recursive(join_options = {}, &block)
+      raise ArgumentError, 'block expected' unless block_given?
+
+      query = Query.new(klass)
+
+      if block.arity == 0
+        query.instance_eval(&block)
+      else
+        block.call(query)
+      end
+
+      query.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/cte/columns.rb

@@ -0,0 +1,26 @@
+require 'arel/visitors/depth_first'
+
+module ActiveRecord
+  module HierarchicalQuery
+    module CTE
+      class Columns
+        # @param [ActiveRecord::HierarchicalQuery::Query] query
+        def initialize(query)
+          @query = query
+        end
+
+        # returns columns to be selected from both recursive and non-recursive terms
+        def to_a
+          column_names = [@query.klass.primary_key] | connect_by_columns
+          column_names.map { |name| @query.table[name] }
+        end
+        alias_method :to_ary, :to_a
+
+        private
+        def connect_by_columns
+          @query.join_conditions.grep(Arel::Attributes::Attribute) { |column| column.name.to_s }
+        end
+      end
+    end
+  end
+end