order_query 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 65a8e133a25873debf2d301e567ebd385e173aed
-  data.tar.gz: ba20134c27cc4b03deb1f76c382c9a6a0abd9b0a
+  metadata.gz: b77ab79b198ad089f382ace5d234c433f239bff0
+  data.tar.gz: 1c2507543963747b645dd4426328fea48b6909e1
 SHA512:
-  metadata.gz: f642f0b9d674d7cdd2b1bc7cae39831cc059baf574787640ddeb1d5170059982e4ff9a93629b4c2a57b897991af15d83940a29ce80b14d09b971b88ac51a4719
-  data.tar.gz: de5fccc4d3e103bd32f2237d5a89d2a70d9df5799e4f205100adf8026200af588214704a6bc92a0ff979017405fac95914c6b758fb6df23ecd61a3a69ad85714
+  metadata.gz: 258a2dd941e882fb115a1a15f1f2be6cabe359840d9fe06fbbb6fbbe41dd37284b4cc27909507624367412a65383d6480462cb37d19181acff1602a8c67894b0
+  data.tar.gz: d72f77b66611f6ca0f784ac080e1ef6cd99369fe4cf8c279c8a7bdaa3a130a13821df4efceb035ff201772d7f3cde0563b1dac4752b95d6feaee69bb0fd9e624

data/CHANGES.md

@@ -1,3 +1,7 @@
+## 0.1.3
+
+* New condition option `complete` for list conditions for optimized query generation
+
 ## 0.1.2
 
 * Wrap top-level `OR` with a redundant `AND` for [performance reasons](https://github.com/glebm/order_query/issues/3).

data/README.md

@@ -16,40 +16,49 @@ This is slow. Here is where `order_query` comes in!
 Add to Gemfile:
 
 ```ruby
-gem 'order_query', '~> 0.1.2'
+gem 'order_query', '~> 0.1.3'
 ```
 
 ## Usage
 
-Define the criteria with `order_query`:
+Define a list of order conditions with `order_query`:
 
 ```ruby
 class Post < ActiveRecord::Base
   include OrderQuery
-  order_query :order_list, [
-    [:pinned, [true, false]],
+  order_query :order_for_index, [
+    [:pinned, [true, false], complete: true],
     [:published_at, :desc],
     [:id, :desc]
   ]
 end
 ```
 
+An order condition is specified as an attribute name, optionally an ordered list of values, and a sort direction.
+Additional options are:
+
+| option     | description                                                                                             |
+|------------|---------------------------------------------------------------------------------------------------------|
+| unique     | Unique attribute, avoids redundant comparisons. Default: `true` for primary key, `false` otherwise.     |
+| complete   | Complete attribute, avoids redundant comparisons. Default: `false` for ordered lists, `true` otherwise. |
+| sql        | Customize attribute value SQL                                                                           |
+
 ### Order scopes
 
-Defining the criteria adds `ORDER BY` scopes:
+Order scopes are defined by `order_query`:
 
 ```ruby
-Post.order_list #=> ActiveRecord::Relation<...>
-Post.reverse_order_list #=> ActiveRecord::Relation<...>
+Post.order_for_index         #=> ActiveRecord::Relation<...>
+Post.reverse_order_for_index #=> ActiveRecord::Relation<...>
 ```
 
-### Records relative to a given one
+### Before, after, previous, and next
 
-`order_query` also adds an instance method for querying relative to the record:
+An method is added by `order_query` to query around a record:
 
 ```ruby
 # get the order object, scope default: Post.all
-p = Post.find(31).order_list(scope) #=> OrderQuery::RelativeOrder<...>
+p = Post.find(31).order_for_index(scope) #=> OrderQuery::RelativeOrder<...>
 p.before         #=> ActiveRecord::Relation<...>
 p.previous       #=> Post<...>
 # pass true to #next and #previous in order to loop onto the the first / last record
@@ -60,9 +69,7 @@ p.next       #=> Post<...>
 p.after      #=> ActiveRecord::Relation<...>
 ```
 
-### Advanced options
-
-Pass arrays and custom sql as order conditions:
+#### Order conditions, advanced example
 
 ```ruby
 class Issue < ActiveRecord::Base
@@ -70,7 +77,7 @@ class Issue < ActiveRecord::Base
   order_query :order_display, [
     # Pass an array for attribute order, and an optional sort direction for the array,
     # default is *:desc*, so that first in the array <=> first in the result
-    [:priority, %w(high medium low), :desc],
+    [:priority, %w(high medium low), :desc, complete: true],
     # Sort attribute can be a method name, provided you pass :sql for the attribute
     [:valid_votes_count, :desc, sql: '(votes - suspicious_votes)'],
     # Default sort order for non-array attributes is :asc, just like SQL
@@ -158,7 +165,7 @@ LIMIT 1
 ```
 
 The top-level `x0 OR ..` clause is actually wrapped with `x0' AND (x0 OR ...)`, where *x0'* is a non-strict condition,
-for [performance reasons](https://github.com/glebm/order_query/issues/3).
+for [performance reasons](https://github.com/glebm/order_query/issues/3). This can be disabled with `OrderQuery::WhereBuilder.wrap_top_level_or = false`.
 
 See how this affects query planning in Markus Winand's slides on [Pagination done the Right Way](http://use-the-index-luke.com/blog/2013-07/pagination-done-the-postgresql-way).
 

data/lib/order_query/order_condition.rb

@@ -2,28 +2,45 @@ module OrderQuery
   class OrderCondition
     attr_reader :name, :order, :order_order, :options, :scope
 
+    # @option spec [String] :unique    Mark the attribute as unique to avoid redundant conditions
+    # @option spec [String] :complete  Mark the condition's domain as complete to avoid redundant conditions (only for array conditions)
     def initialize(scope, spec)
-      spec              = spec.dup
-      @options          = spec.extract_options!
-      @name             = spec[0]
-      @order            = spec[1] || :asc
-      @order_order      = spec[2] || :desc
-      @scope            = scope
-      @unique           = @options.key?(:unique) ? !!@options[:unique] : (name.to_s == scope.primary_key)
+      spec         = spec.dup
+      options      = spec.extract_options!
+      @name        = spec[0]
+      @order       = spec[1] || :asc
+      @order_order = spec[2] || :desc
+      @options     = options
+      @scope       = scope
+      @unique      = if options.key?(:unique)
+                       !!options[:unique]
+                     else
+                       name.to_s == scope.primary_key
+                     end
+      @complete    = if options.key?(:complete)
+                       !!options[:complete]
+                     else
+                       !list?
+                     end
     end
 
     def unique?
       @unique
     end
 
-    def ray?
-      !order.is_a?(Array)
+    def complete?
+      @complete
+    end
+
+    # @return [Boolean] whether order is specified as a list of values
+    def list?
+      order.is_a?(Enumerable)
     end
 
     # @param [Object] value
     # @param [:before, :after] mode
     # @return [Array] valid order values before / after passed (depending on the mode)
-    def values_around(value, mode, strict = true)
+    def filter_values(value, mode, strict = true)
       ord = order
       pos = ord.index(value)
       if pos
@@ -40,12 +57,14 @@ module OrderQuery
     end
 
     def col_name_sql
-      sql = options[:sql]
-      if sql
-        sql = sql.call if sql.respond_to?(:call)
-        sql
-      else
-        scope.connection.quote_table_name(scope.table_name) + '.' + scope.connection.quote_column_name(name)
+      @col_name_sql ||= begin
+        sql = options[:sql]
+        if sql
+          sql = sql.call if sql.respond_to?(:call)
+          sql
+        else
+          scope.connection.quote_table_name(scope.table_name) + '.' + scope.connection.quote_column_name(name)
+        end
       end
     end
   end

data/lib/order_query/version.rb

@@ -1,3 +1,3 @@
 module OrderQuery
-  VERSION = '0.1.2'
+  VERSION = '0.1.3'
 end

data/lib/order_query/where_builder.rb

@@ -1,3 +1,4 @@
+# coding: utf-8
 module OrderQuery
   # Build where clause for searching around a record in an order space
   class WhereBuilder
@@ -16,20 +17,24 @@ module OrderQuery
     # @param [:before or :after] mode
     # @return [query, parameters] conditions that exclude all elements not before / after the current one
     def build_query(mode)
-      conditions = order.conditions
-      terms = conditions.map { |cond| [where_mode(cond, mode, true), where_eq(cond)] }
-      query = group_operators terms
+      # pairs of [x0, y0]
+      pairs = order.conditions.map { |cond|
+        [where_relative(cond, mode, true), (where_eq(cond) unless cond.unique?)].reject { |x|
+          x.nil? || x == WHERE_IDENTITY || x == WHERE_NONE
+        }.compact
+      }
+      query = group_operators pairs
+      return query unless self.class.wrap_top_level_or
       # Wrap top level OR clause for performance, see https://github.com/glebm/order_query/issues/3
-      if self.class.wrap_top_level_or && !terms[0].include?(EMPTY_FILTER)
-        join_terms 'AND'.freeze,
-                   where_mode(conditions.first, mode, false),
-                   ["(#{query[0]})", query[1]]
+      top_pair_idx = pairs.index(&:present?)
+      if top_pair_idx && pairs[top_pair_idx].length == 2 && (top_level_cond = order.conditions[top_pair_idx])
+        join_terms 'AND'.freeze, where_relative(top_level_cond, mode, false), wrap_parens(query)
       else
         query
       end
     end
 
-    # Join conditions with operators and parenthesis
+    # Join condition pairs internally with OR, and nested within each other with AND
     # @param [Array] term_pairs of query terms [[x0, y0], [x1, y1], ...],
     #                xi, yi are pairs of [query, parameters]
     # @return [query, parameters]
@@ -44,17 +49,20 @@ module OrderQuery
     def group_operators(term_pairs)
       # create "x OR y" string
       disjunctive = join_terms 'OR'.freeze, *term_pairs[0]
-      rest = term_pairs.from(1)
+      rest        = term_pairs.from(1)
       if rest.present?
         # nest the remaining pairs recursively, appending them with " AND "
-        rest_grouped    = group_operators rest
-        rest_grouped[0] = "(#{rest_grouped[0]})" unless rest.length == 1
-        join_terms 'AND'.freeze, disjunctive, rest_grouped
+        rest_grouped = group_operators rest
+        join_terms 'AND'.freeze, disjunctive, (rest.length == 1 ? rest_grouped : wrap_parens(rest_grouped))
       else
         disjunctive
       end
     end
 
+    def wrap_parens(t)
+      ["(#{t[0]})", t[1]]
+    end
+
     # joins terms with an operator
     # @return [query, parameters]
     def join_terms(op, *terms)
@@ -62,48 +70,48 @@ module OrderQuery
        terms.map(&:second).reduce(:+) || []]
     end
 
-    EMPTY_FILTER = [''.freeze, []]
-
-    # @return [query, params] Unless order attribute is unique, such as id, return ['WHERE value = ?', current value].
-    def where_eq(cond)
-      if cond.unique?
-        EMPTY_FILTER
+    # @param [:before or :after] mode
+    # @return [query, params] return query conditions for attribute values before / after the current one
+    def where_relative(cond, mode, strict = true, skip_complete = true)
+      value = attr_value cond
+      if cond.list?
+        values = cond.filter_values(value, mode, strict)
+        if cond.complete? && values.length == cond.order.length
+          WHERE_IDENTITY
+        else
+          where_in cond, values
+        end
       else
-        [%Q(#{cond.col_name_sql} = ?).freeze, [attr_value(cond)]]
+        where_ray cond, value, mode, strict
       end
     end
 
-    def where_ray(cond, from, mode, strict = true)
-      ops = %w(< >)
-      ops = ops.reverse if mode == :after
-      op  = {asc: ops[0], desc: ops[1]}[cond.order || :asc]
-      ["#{cond.col_name_sql} #{op}#{'=' unless strict} ?".freeze, [from]]
-    end
 
     def where_in(cond, values)
       case values.length
         when 0
-          EMPTY_FILTER
+          WHERE_NONE
         when 1
-          ["#{cond.col_name_sql} = ?".freeze, [values]]
+          where_eq cond, values[0]
         else
           ["#{cond.col_name_sql} IN (?)".freeze, [values]]
       end
     end
 
-    # @param [:before or :after] mode
-    # @return [query, params] return query conditions for attribute values before / after the current one
-    def where_mode(cond, mode, strict = true)
-      value = attr_value cond
-      if cond.ray?
-        where_ray cond, value, mode, strict
-      else
-        # ord is an array of sort values, ordered first to last
-        # if current not in result set, do not apply filter
-        where_in cond, cond.values_around(value, mode, strict)
-      end
+    def where_eq(cond, value = attr_value(cond))
+      [%Q(#{cond.col_name_sql} = ?).freeze, [value]]
+    end
+
+    def where_ray(cond, from, mode, strict = true)
+      ops = %w(< >)
+      ops = ops.reverse if mode == :after
+      op  = {asc: ops[0], desc: ops[1]}[cond.order || :asc]
+      ["#{cond.col_name_sql} #{op}#{'=' unless strict} ?".freeze, [from]]
     end
 
+    WHERE_IDENTITY = [''.freeze, [].freeze].freeze
+    WHERE_NONE = ['∅'.freeze, [].freeze].freeze
+
     def attr_value(cond)
       record.send cond.name
     end

data/spec/order_query_spec.rb

@@ -4,7 +4,7 @@ require 'spec_helper'
 class Post < ActiveRecord::Base
   include OrderQuery
   order_query :order_list, [
-      [:pinned, [true, false]],
+      [:pinned, [true, false], complete: true],
       [:published_at, :desc],
       [:id, :desc]
   ]
@@ -17,7 +17,7 @@ end
 # Advanced example
 class Issue < ActiveRecord::Base
   DISPLAY_ORDER = [
-      [:priority, %w(high medium low)],
+      [:priority, %w(high medium low), complete: true],
       [:valid_votes_count, :desc, sql: '(votes - suspicious_votes)'],
       [:updated_at, :desc],
       [:id, :desc]

data/spec/spec_helper.rb

@@ -13,4 +13,7 @@ require 'order_query'
 
 Dir["#{File.dirname(__FILE__)}/support/**/*.rb"].each { |f| require f }
 
+require 'fileutils'
+FileUtils.mkpath 'log' unless File.directory? 'log'
+ActiveRecord::Base.logger = Logger.new('log/test-queries.log')
 ActiveRecord::Base.establish_connection(adapter: 'sqlite3', database: ':memory:')

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: order_query
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.3
 platform: ruby
 authors:
 - Gleb Mazovetskiy