active_record_extended 0.7.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d3332acf1ce7aa530fcbaddc871d5bdfc4560f71794fc4efbdd33653c6ea1eb5
-  data.tar.gz: 73df494665607c73c5ddb2999aa0e021e166fc436a1cd75784cd1ffa30e1fe9e
+  metadata.gz: 84402ebc9c8f57ee3db39a3260233b2b737020aa14f26550a76b59bb1a4dd05c
+  data.tar.gz: e6613db1ec9bef7644cd6272a3b9f8c494119d45b756991c0ea61bf49b91312c
 SHA512:
-  metadata.gz: 94c04d0fb830fd9e4b7f0b21bea2fb7a3b753903f4fb41ffb71fc72ed147ac3247507438411a37bf74235aaea943c2f98b5b5141467cf09b663dd9930269d2f0
-  data.tar.gz: 3c5915ec558d623704dc4b824f052639dc25df2a0c0385f143eb597f4984f4beab1ef1d4083c7fbbf696ac0314b3ddd860640f8ecdc601681a4b042fe0224256
+  metadata.gz: edbe5dcb670d2db62f3c6171b377f42feb984babec1ae54780998170e12f3267d34218b03950f41a3b855fab7a4afac63a7536fba79d45cf37fdcdb990f40ce9
+  data.tar.gz: aa5131ef5f854a046762adb914ca199948265c11e01e70519cfc03d8895828d1f20416f8c88188bf7c10775fa3f89338f785f14927720abf204850207cabd52e

data/README.md

@@ -4,9 +4,10 @@
 [![Test Coverage](https://api.codeclimate.com/v1/badges/f22154211bb3a8feb89f/test_coverage)](https://codeclimate.com/github/GeorgeKaraszi/ActiveRecordExtended/test_coverage)
 ## Index
 - [Description and history](#description-and-history)
+- [Compatibility](#compatibility)
 - [Installation](#installation)
-- [Useage](#usage)
-  - [Query Methods](#query-methods)
+- [Usage](#usage)
+  - [Predicate Query Methods](#predicate-query-methods)
     - [Any](#any)
     - [All](#all)
     - [Contains](#contains)
@@ -21,6 +22,20 @@
     - [Any_of / None_of](#any_of--none_of)
     - [Either Join](#either-join)
     - [Either Order](#either-order)
+  - [Common Table Expressions (CTE)](#common-table-expressions-cte)
+    - [Subquery CTE Gotchas](#subquery-cte-gotchas)
+  - [JSON Query Methods](#json-query-methods)
+    - [Row To JSON](#row-to-json)
+    - [JSON/B Build Object](#jsonb-build-object)
+    - [JSON/B Build Literal](#jsonb-build-literal)
+  - [Unionization](#unionization)
+    - [Union](#union)
+    - [Union ALL](#union-all)
+    - [Union Except](#union-except)
+    - [Union Intersect](#union-intersect)
+    - [Union As](#union-as)
+    - [Union Order](#union-order)
+    - [Union Reorder](#union-reorder)
 
 ## Description and History
 
@@ -29,12 +44,21 @@ Active Record Extended is the continuation of maintaining and improving the work
 Overtime the lack of updating to support the latest versions of ActiveRecord 5.x has caused quite a bit of users forking off the project to create their own patches jobs to maintain compatibility. 
 The only problem is that this has created a wild west of environments of sorts. The problem has grown to the point no one is attempting to directly contribute to the original source. And forked repositories are finding themselves as equally as dead with little to no activity.
 
-Active Record Extended is intended to be a supporting community that will maintain compatibility for the foreseeable future.
+Active Record Extended is essentially providing users with the other half of Postgreses querying abilities. Due to Rails/ActiveRecord/Arel being designed to be DB agnostic, there are a lot of left out features; Either by choice or the simple lack of supporting API's for other databases. However some features are not exactly PG explicit. Some are just helper methods to express an idea much more easily.
 
 
+## Compatibility
+
+This package is designed align and work with any officially supported Ruby and Rails versions.
+ - Minimum Ruby Version: 2.3.x **(EOL warning!)**
+ - Minimum Rails Version: 5.0.x **(EOL warning!)**
+ - Latest Ruby supported: 2.6.x
+ - Latest Rails supported: 5.2.x
+ - Postgres: 9.6-current(11) (probably works with most older versions to a certain point)
+
 ## Usage
 
-### Query Methods
+### Predicate Query Methods
 
 #### Any
 [Postgres 'ANY' expression](https://www.postgresql.org/docs/10/static/functions-comparisons.html#id-1.5.8.28.16)
@@ -273,6 +297,486 @@ User.either_order(:asc, profile_l: :left_turns, profile_r: :right_turns) #=> [bo
 User.either_order(:desc, profile_l: :left_turns, profile_r: :right_turns) #=> [randy, alice, bob]
 ```
 
+### Common Table Expressions (CTE)
+[Postgres WITH (CTE) Statement](https://www.postgresql.org/docs/current/static/queries-with.html)
+
+The `.with/1` method is a base ActiveRecord querying method that will aid in creating complex queries.
+
+```ruby
+alice = User.create!
+bob   = User.create!
+randy = User.create!
+ProfileL.create!(user_id: alice.id, likes: 200)
+ProfileL.create!(user_id: bob.id,   likes: 400)
+ProfileL.create!(user_id: randy.id, likes: 600)
+
+User.with(highly_liked: ProfileL.where("likes > 300"))
+    .joins("JOIN highly_liked ON highly_liked.user_id = users.id") #=> [bob, randy]
+```
+
+Query output:
+
+```sql
+WITH "highly_liked" AS (SELECT "profile_ls".* FROM "profile_ls" WHERE (likes >= 300)) 
+SELECT "users".* 
+FROM "users" 
+JOIN highly_liked ON highly_liked.user_id = users.id
+```
+
+You can also chain or provide additional arguments to the `with/1` method for it to merge into a single, `WITH` statement.
+
+```ruby
+User.with(highly_liked: ProfileL.where("likes > 300"), less_liked: ProfileL.where("likes <= 200"))
+    .joins("JOIN highly_liked ON highly_liked.user_id = users.id")
+    .joins("JOIN less_liked ON less_liked.user_id = users.id")
+
+# OR
+
+User.with(highly_liked: ProfileL.where("likes > 300"))
+    .with(less_liked: ProfileL.where("likes <= 200"))
+    .joins("JOIN highly_liked ON highly_liked.user_id = users.id")
+    .joins("JOIN less_liked ON less_liked.user_id = users.id")
+```
+
+Query output:
+
+```sql
+WITH "highly_liked" AS (SELECT "profile_ls".* FROM "profile_ls" WHERE (likes > 300)), 
+     "less_liked" AS (SELECT "profile_ls".* FROM "profile_ls" WHERE (likes <= 200)) 
+SELECT "users".* 
+FROM "users" 
+JOIN highly_liked ON highly_liked.user_id = users.id 
+JOIN less_liked ON less_liked.user_id = users.id
+```
+
+#### Subquery CTE Gotchas
+ In order keep queries PG valid, subquery explicit methods (like Unions and JSON methods) 
+ will be subject to "Piping" the CTE clauses up to the parents query level. 
+ 
+ This also means there's potential for having duplicate CTE names.
+ In order to combat duplicate CTE references with the same name, **piping will favor the parents CTE over the nested sub-queries**.
+ 
+ This also means that this is a "First come First Served" implementation. 
+ So if you have a parent with no CTE's but two sub-queries with the same CTE name but with different querying statements. 
+ It will process and favor the one that comes first.
+ 
+ Example:
+ ```ruby
+    sub_query      = Person.with(dupped_cte: Person.where(id: 1)).select("dup_cte.id").from(:dup_cte)
+    other_subquery = Person.with(unique_cte: Person.where(id: 5)).select("unique_cte.id").from(:unique_cte)
+    
+    # Will favor this CTE below, over the `sub_query`'s CTE 
+    Person.with(dupped_cte: Person.where.not(id: 1..4)).union(sub_query, other_subquery)
+```
+
+Query Output
+```sql
+WITH "unique_cte" AS (
+  SELECT "people".*
+  FROM "people"
+  WHERE "people"."id" = 5
+), "dupped_cte" AS (
+  SELECT "people".*
+  FROM "people"
+  WHERE NOT ("people"."id" BETWEEN 1 AND 4)
+)
+  SELECT "people".*
+  FROM (( (
+    SELECT dup_cte.id
+    FROM dup_cte
+  ) UNION (
+    SELECT unique_cte.id
+    FROM unique_cte
+  ) )) people
+```
+ 
+
+### JSON Query Methods
+If any or all of your json sub-queries include a CTE, read the [Subquery CTE Gotchas](#subquery-cte-gotchas) warnings.
+
+#### Row To JSON
+[Postgres 'ROW_TO_JSON' function](https://www.postgresql.org/docs/current/functions-json.html#FUNCTIONS-JSON-CREATION-TABLE)
+
+The implementation of the`.row_to_json/2` method is designed to be used with sub-queries. As a means for taking complex 
+query logic and transform them into a single or multiple json responses. These responses are required to be assigned 
+to an aliased column on the parent(callee) level.
+
+While quite the mouthful of an explanation. The implementation of combining unrelated or semi-related queries is quite smooth(imo).
+
+```ruby
+    physical_cat  = Category.create!(name: "Physical")
+    products      = 3.times.map { Product.create! }
+    products.each { |product|  100.times { Variant.create!(product: product, category: physical_cat) } }
+    
+    # Since we plan to nest this query, you have access top level information. (I.E categories table)
+    item_query = Variant.select(:name, :id, :category_id, :product_id).where("categories.id = variants.category_id")
+    
+    # You can provide addition scopes that will be applied to the nested query (but will not effect the actual inner query)
+    # This is ideal if you are dealing with but not limited to, CTE's being applied multiple times and require additional constraints 
+    product_query  = 
+    Product.select(:id)
+            .joins(:items)
+            .select_row_to_json(item_query, key: :outer_items, as: :items, cast_as_array: true) do |item_scope|
+              item_scope.where("outer_items.product_id = products.id")
+                # Results to: 
+                #  SELECT ..., ARRAY(SELECT ROW_TO_JSON("outer_items")   
+                #   FROM ([:item_query:]) outer_items
+                #   WHERE outer_items.product_id = products.id
+                # ) AS items
+            end
+                   
+    # Not defining a key will automatically generate a random key between a-z 
+    category_query = Category.select(:name, :id).select_row_to_json(product_query, as: :products, cast_as_array: true)
+    Category.json_build_object(:physical_category, category_query.where(id: physical_cat.id)).results
+    #=> {
+    #        "physical_category" => {
+    #            "name" => "Physical",
+    #            "id" => 1, 
+    #            "products" => [
+    #              {
+    #                "id" => 2,
+    #                "items" => [{"name" => "Bojangels", "id" => 3, "category_id" => 1, "product_id" => 2}, ...] 
+    #              },
+    #              ... 
+    #            ] 
+    #        } 
+    #  } 
+    #
+```
+
+Query Output 
+```sql
+SELECT (JSON_BUILD_OBJECT('physical_category', "physical_category")) AS "results"
+FROM (
+     SELECT "categories"."name", "categories"."id", (ARRAY(
+         SELECT ROW_TO_JSON("j")
+         FROM (
+              SELECT "products"."id", (ARRAY(
+                  SELECT ROW_TO_JSON("outer_item")
+                  FROM (
+                       SELECT "variants"."name", "variants"."id", "variants"."category_id", "variants"."product_id"
+                       FROM "variants"
+                       WHERE (categories.id = variants.category_id)
+                       ) outer_items
+                  WHERE (outer_items.product_id = products.id)
+                )) AS "items"
+              FROM "products"
+              INNER JOIN "items" ON "products"."id" = "items"."product_id"
+              ) j
+       )) AS "products"
+     FROM "categories"
+     WHERE "categories"."id" = 1
+     ) AS "physical_category"
+```
+
+
+#### JSON/B Build Object
+[Postgres 'json(b)_build_object' function](https://www.postgresql.org/docs/current/functions-json.html#FUNCTIONS-JSON-CREATION-TABLE)
+
+The implementation of the`.json_build_object/2` and `.jsonb_build_object/2` methods are designed to be used with sub-queries. 
+As a means for taking complex  query logic and transform them into a single or multiple json responses.
+
+**Arguments:**
+  - `key`: [Symbol or String]: What should this response return as
+  - `from`: [String, Arel, or ActiveRecord::Relation] : A subquery that can be nested into the top-level from clause
+
+**Options:**
+   - `as`: [Symbol or String] (defaults to `"results"`): What the column will be aliased to
+   - `value`: [Symbol or String] (defaults to `key` argument): How the response should handel the json value return
+
+See the included example on [Row To JSON](#row-to-json) to see it in action.
+
+#### JSON/B Build Literal
+[Postgres 'json(b)_build_object' function](https://www.postgresql.org/docs/current/functions-json.html#FUNCTIONS-JSON-CREATION-TABLE)
+
+The implementation of the`.json_build_literal/1` and `.jsonb_build_literal/1` is designed for creating static json objects
+ that don't require subquery interfacing.
+ 
+**Arguments:**
+ - Requires an Array or Hash set of values
+
+**Options:**
+ - `as`: [Symbol or String] (defaults to `"results"`): What the column will be aliased to
+      
+```ruby
+    User.json_build_literal(number: 1, last_name: "json", pi: 3.14).take.results
+     #=> { "number" => 1, "last_name" => "json", "pi" => 3.14 }
+    
+    # Or as array elements
+    User.json_build_literal(:number, 1, :last_name, "json", :pi, 3.14).take.results
+      #=> { "number" => 1, "last_name" => "json", "pi" => 3.14 } 
+     
+```
+
+Query Output
+```sql
+SELECT (JSON_BUILD_OBJECT('number', 1, 'last_name', 'json', 'pi', 3.14)) AS "results"
+  FROM "users"
+```
+
+
+### Unionization
+If any or all of your union queries include a CTE, read the [Subquery CTE Gotchas](#subquery-cte-gotchas) warnings.
+
+#### SQL-Query Helpers
+ - `.to_union_sql` : Will return a string of the constructed union query without being nested in the `from` clause.
+ - `.to_nice_union_sql`(requires [NiceQL Gem](https://github.com/alekseyl/niceql) to be install): A formatted `.to_union_sql`
+
+
+#### Known issue
+There's an issue with providing a single union clause and chaining it with a different union clause. 
+This is due to requirements of grouping SQL statements. The issue is being working on, but with no ETA.
+
+This issue only applies to the first initial set of unions and is recommended that you union two relations right off the bat. 
+Afterwords you can union/chain single relations.
+
+Example
+
+```ruby
+
+Person.union(Person.where(id: 1..4)).union_except(Person.where(id: 3..4)).union(Person.where(id: 4))
+#=> Will include all people with an ID between 1 & 3 (throwing the except on ID 4)
+
+# This can be fixed by doing something like
+
+Person.union_except(Person.where(id: 1..4), Person.where(id: 3..4)).union(Person.where(id: 4))
+#=> Will include people with the ids of 1, 2, and 4 (properly excluding the user with the ID of 3)
+```
+
+Problem Query Output
+```sql
+( ( (
+  SELECT "people".*
+  FROM "people"
+  WHERE "people"."id" BETWEEN 1 AND 4
+) UNION (
+  SELECT "people".*
+  FROM "people"
+  WHERE "people"."id" BETWEEN 3 AND 4
+) ) EXCEPT (
+  SELECT "people".*
+  FROM "people"
+  WHERE "people"."id" = 4
+) )
+```
+
+
+#### Union
+[Postgres 'UNION' combination](https://www.postgresql.org/docs/current/queries-union.html)
+
+```ruby
+user_1 = Person.where(id: 1)
+user_2 = Person.where(id: 2)
+users  = Person.where(id: 1..3)
+
+Person.union(user_1, user_2, users) #=> [#<Person id: 1, ..>, #<Person id: 2,..>, #<Person id: 3,..>]
+
+# You can also chain union's
+Person.union(user_1).union(user_2).union(users)
+```
+
+Query Output
+```sql
+SELECT "people".*
+  FROM (( ( (
+    SELECT "people".*
+    FROM "people"
+    WHERE "people"."id" = 1
+  ) UNION (
+    SELECT "people".*
+    FROM "people"
+    WHERE "people"."id" = 2
+  ) ) UNION (
+    SELECT "people".*
+    FROM "people"
+    WHERE "people"."id" BETWEEN 1 AND 3
+  ) )) people
+```
+
+
+#### Union ALL
+[Postgres 'UNION ALL' combination](https://www.postgresql.org/docs/current/queries-union.html)
+
+```ruby
+user_1 = Person.where(id: 1)
+user_2 = Person.where(id: 2)
+users  = Person.where(id: 1..3)
+
+Person.union_all(user_1, user_2, users) 
+  #=> [#<Person id: 1, ..>, #<Person id: 2,..>, #<Person id: 1, ..>, #<Person id: 2,..>, #<Person id: 3,..>]
+
+# You can also chain union's
+Person.union_all(user_1).union_all(user_2).union_all(users)
+# Or
+Person.union.all(user1, user_2).union.all(users) 
+```
+
+Query Output
+```sql
+SELECT "people".*
+  FROM (( ( (
+    SELECT "people".*
+    FROM "people"
+    WHERE "people"."id" = 1
+  ) UNION ALL (
+    SELECT "people".*
+    FROM "people"
+    WHERE "people"."id" = 2
+  ) ) UNION ALL (
+    SELECT "people".*
+    FROM "people"
+    WHERE "people"."id" BETWEEN 1 AND 3
+  ) )) people
+```
+
+#### Union Except
+[Postgres 'EXCEPT' combination](https://www.postgresql.org/docs/current/queries-union.html)
+
+```ruby
+users               = Person.where(id: 1..5)
+expect_these_users  = Person.where(id: 2..4)
+
+Person.union_except(users, expect_these_users) #=> [#<Person id: 1, ..>, #<Person id: 5,..>]
+
+# You can also chain union's
+Person.union.except(users, expect_these_users).union(Person.where(id: 20))
+```
+
+Query Output
+```sql
+SELECT "people".*
+  FROM (( ( (
+    SELECT "people".*
+    FROM "people"
+    WHERE "people"."id" BETWEEN 1 AND 5
+  ) EXCEPT (
+    SELECT "people".*
+    FROM "people"
+    WHERE "people"."id" BETWEEN 2 AND 4
+  )) people
+```
+
+#### Union Intersect
+[Postgres 'INTERSECT' combination](https://www.postgresql.org/docs/current/queries-union.html)
+
+```ruby
+randy = Person.create!
+alice = Person.create!
+ProfileL.create!(person: randy, likes: 100)
+ProfileL.create!(person: alice, likes: 120)
+
+likes_100           = Person.select(:id, "profile_ls.likes").joins(:profile_l).where(profile_ls: { likes: 100 })
+likes_less_than_150 = Person.select(:id, "profile_ls.likes").joins(:profile_l).where("profile_ls.likes < 150")
+Person.union_intersect(likes_100, likes_less_than_150) #=> [randy]
+
+
+
+# You can also chain union's
+Person.union_intersect(likes_100).union_intersect(likes_less_than_150) #=> [randy]
+# Or
+Person.union.intersect(likes_100, likes_less_than_150) #=> [randy] 
+
+```
+
+Query Output
+```sql
+SELECT "people".*
+  FROM (( (
+    SELECT "people"."id", profile_ls.likes
+    FROM "people"
+    INNER JOIN "profile_ls" ON "profile_ls"."person_id" = "people"."id"
+    WHERE "profile_ls"."likes" = 100
+  ) INTERSECT (
+    SELECT "people"."id", profile_ls.likes
+    FROM "people"
+    INNER JOIN "profile_ls" ON "profile_ls"."person_id" = "people"."id"
+    WHERE (profile_ls.likes < 150)
+  ) )) people
+```
+
+#### Union As
+
+By default unions are nested in the from clause and are aliased to the parents table name.
+We can change this behavior by chaining the method `.union_as/1`
+
+```ruby
+Person.select("good_people.id").union(Person.where(id: 1), Person.where(id: 2)).union_as(:good_people)
+```
+
+Query Output
+```sql
+SELECT good_people.id
+  FROM (( (
+    SELECT "people".*
+    FROM "people"
+    WHERE "people"."id" = 1
+  ) UNION (
+    SELECT "people".*
+    FROM "people"
+    WHERE "people"."id" = 2
+  ) )) good_people
+```
+
+
+#### Union Order
+
+Unions allow for a final outside `ORDER BY` clause. This will ensure that all the results that come back are ordered in an expected return.
+
+```ruby
+query_1 = Person.where(id: 1..3)
+query_2 = Person.where(id: 3)
+query_3 = Person.where(id: 3..10)
+Person.union_except(query_1, query_2).union(query_3).order_union(:id, tags: :desc)
+```
+
+Query Output
+```sql
+SELECT "people".*
+  FROM (( ( (
+    SELECT "people".*
+    FROM "people"
+    WHERE "people"."id" BETWEEN 1 AND 3
+  ) EXCEPT (
+    SELECT "people".*
+    FROM "people"
+    WHERE "people"."id" = 3
+  ) ) UNION (
+    SELECT "people".*
+    FROM "people"
+    WHERE "people"."id" BETWEEN 3 AND 10
+  ) ) ORDER BY id ASC, tags DESC) people
+```
+
+#### Union Reorder
+
+much like Rails `.reorder`; `.reorder_union/1`  will clear the previous order in a new instance and/or apply a new ordering scheme
+```ruby
+query_1     = Person.where(id: 1..3)
+query_2     = Person.where(id: 3)
+query_3     = Person.where(id: 3..10)
+union_query = Person.union_except(query_1, query_2).union(query_3).order_union(:id, tags: :desc)
+union_query.reorder_union(personal_id: :desc, id: :desc)
+```
+
+Query Output
+```sql
+SELECT "people".*
+  FROM (( ( (
+    SELECT "people".*
+    FROM "people"
+    WHERE "people"."id" BETWEEN 1 AND 3
+  ) EXCEPT (
+    SELECT "people".*
+    FROM "people"
+    WHERE "people"."id" = 3
+  ) ) UNION (
+    SELECT "people".*
+    FROM "people"
+    WHERE "people"."id" BETWEEN 3 AND 10
+  ) ) ORDER BY personal_id DESC, id DESC) people
+```
+
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -289,14 +793,6 @@ Or install it yourself as:
 
     $ gem install active_record_extended
 
-
-## Development
-
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
-
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
-
-
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).