outoftime-sunspot 0.8.9 → 0.9.0

data/lib/sunspot/query/field_facet.rb

@@ -1,12 +1,41 @@
+require 'set'
+
 module Sunspot
-  class Query
+  module Query
     #
     # Encapsulates a query component representing a field facet. Users create
     # instances using DSL::Query#facet
     #
     class FieldFacet #:nodoc:
-      def initialize(field)
-        @field = field
+      class <<self
+        protected :new
+
+        # 
+        # Return the appropriate FieldFacet instance for the field and options.
+        # If a :time_range option is specified, and the field type is TimeType,
+        # build a DateFieldFacet. Otherwise, build a normal FieldFacet.
+        #
+        # ==== Returns
+        #
+        # FieldFacet:: FieldFacet instance of appropriate class.
+        #
+        def build(field, options)
+          if options.has_key?(:time_range)
+            unless field.type == Type::TimeType
+              raise(
+                ArgumentError,
+                ":time_range key can only be specified for time fields"
+              )
+            end
+            DateFieldFacet.new(field, options)
+          else
+            FieldFacet.new(field, options)
+          end
+        end
+      end
+
+      def initialize(field, options)
+        @field, @options = field, options
       end
 
       # ==== Returns
@@ -14,7 +43,106 @@ module Sunspot
       # Hash:: solr-ruby params for this field facet
       #
       def to_params
-        { :facets => { :fields => [@field.indexed_name] }}
+        params = { :"facet.field" => [@field.indexed_name], :facet => 'true' }
+        params[param_key(:sort)] = 
+          case @options[:sort]
+          when :count then 'true'
+          when :index then 'false'
+          when nil
+          else raise(ArgumentError, 'Allowed facet sort options are :count and :index')
+          end
+        params[param_key(:limit)] = @options[:limit]
+        params[param_key(:mincount)] =
+          if @options[:minimum_count] then @options[:minimum_count]
+          elsif @options[:zeros] then 0
+          else 1
+          end
+        params
+      end
+
+      private
+
+      # 
+      # Given a facet parameter name, return the appropriate Solr parameter for
+      # this facet.
+      #
+      # ==== Returns
+      #
+      # Symbol:: Solr query parameter key
+      #
+      def param_key(name)
+        :"f.#{@field.indexed_name}.facet.#{name}"
+      end
+    end
+
+    class DateFieldFacet < FieldFacet #:nodoc:
+      ALLOWED_OTHER = Set.new(%w(before after between none all))
+
+      # 
+      # Convert the facet to date params.
+      #
+      def to_params
+        super.merge(
+          :"facet.date" => [@field.indexed_name],
+          param_key('date.start') => start_time.utc.xmlschema,
+          param_key('date.end') => end_time.utc.xmlschema,
+          param_key('date.gap') => "+#{interval}SECONDS",
+          param_key('date.other') => others
+        )
+      end
+
+      private
+
+      # 
+      # Start time for facet range
+      #
+      # ==== Returns
+      #
+      # Time:: Start time
+      #
+      def start_time
+        @options[:time_range].first
+      end
+
+      # 
+      # End time for facet range
+      #
+      # ==== Returns
+      #
+      # Time:: End time
+      #
+      def end_time
+        @options[:time_range].last
+      end
+
+      # 
+      # Time interval that each facet row should cover. Default is 1 day.
+      #
+      # ===== Returns
+      #
+      # Integer:: Time interval in seconds
+      #
+      def interval
+        @options[:time_interval] || 86400
+      end
+
+      # 
+      # Other time ranges to create facet rows for. Allowed values are defined
+      # in ALLOWED_OTHER constant.
+      #
+      def others
+        if others = @options[:time_other]
+          Array(others).map do |other|
+            other = other.to_s
+            unless ALLOWED_OTHER.include?(other)
+              raise(
+                ArgumentError,
+                "#{other.inspect} is not a valid argument for :time_other"
+              )
+            end
+            other
+          end
+        end
       end
     end
   end

data/lib/sunspot/query/field_query.rb

@@ -0,0 +1,57 @@
+module Sunspot
+  module Query
+    # 
+    # This class acts as a base class for query components that encapsulate
+    # operations on fields. It is subclassed by the Query::Query class and the
+    # Query::DynamicQuery class.
+    #
+    class FieldQuery < Scope
+      # 
+      # Add a field facet. See Sunspot::Facet for more information.
+      #
+      # ==== Parameters
+      #
+      # field_name<Symbol>:: Name of the field on which to get a facet
+      #
+      # ==== Returns
+      #
+      # FieldFacet:: The field facet object
+      #
+      def add_field_facet(field_name, options = nil)
+        add_component(FieldFacet.build(build_field(field_name), options || {}))
+      end
+
+      # 
+      # Add a query facet.
+      #
+      # ==== Parameters
+      #
+      # name<Symbol>::
+      #   The name associated with the query facet. This is not passed to Solr,
+      #   but allows the user to retrieve the facet result by passing the name
+      #   to the Search#facet method.
+      #
+      # ==== Returns
+      #
+      # QueryFacet:: The query facet object
+      #
+      def add_query_facet(name)
+        add_component(facet = QueryFacet.new(name, setup))
+        query_facets[name.to_sym] = facet
+        facet
+      end
+
+      # 
+      # Set result ordering.
+      #
+      # ==== Parameters
+      #
+      # field_name<Symbol>:: Name of the field on which to order
+      # direction<Symbol>:: :asc or :desc (default :asc)
+      #
+      def order_by(field_name, direction = nil)
+        add_sort(Sort.new(build_field(field_name), direction))
+      end
+    end
+  end
+end

data/lib/sunspot/query/pagination.rb

@@ -1,5 +1,5 @@
 module Sunspot
-  class Query
+  module Query
     # 
     # A query component that holds information about pagination. Unlike other
     # query components, this one is mutable, because the query itself holds a

data/lib/sunspot/query/query_facet.rb

@@ -0,0 +1,72 @@
+module Sunspot
+  module Query
+    # 
+    # QueryFacets encapsulate requests for Sunspot's query faceting capability.
+    # They are created by the FieldQuery#add_query_facet method.
+    #
+    #--
+    #
+    # The actual concept of a QueryFacet is somewhat artificial - it provides a
+    # grouping for the facet at the Sunspot level, which provides a nicer and
+    # more consistent API in Sunspot; Solr does not provide any grouping for
+    # query facet rows, instead returning each requested row individually, keyed
+    # by the boolean phrase used in the facet query.
+    #
+    class QueryFacet
+      attr_reader :name #:nodoc:
+
+      def initialize(name, setup) #:nodoc:
+        @name = name
+        @setup = setup
+        @components = []
+      end
+
+      #
+      # Add a QueryFacetRow to this facet. The label argument becomes the value
+      # of the Sunspot::QueryFacetRow object corresponding to this query facet
+      # row.
+      #
+      # ==== Parameters
+      #
+      # label<Object>::
+      #   An object that will become the value of the result row. Use whatever
+      #   type is most intuitive.
+      #
+      # ==== Returns
+      #
+      # QueryFacetRow:: QueryFacetRow object containing scope for this row
+      #
+      def add_row(label)
+        @components << row = QueryFacetRow.new(label, @setup)
+        row
+      end
+
+      # 
+      # Express this query facet as Solr parameters
+      #
+      # ==== Returns
+      #
+      # Hash:: Solr params hash
+      #
+      def to_params #:nodoc:
+        components = @components.map { |component| component.to_boolean_phrase }
+        components = components.first if components.length == 1
+        {
+          :facet => 'true',
+          :"facet.query" => components
+        }
+      end
+
+      # 
+      # Get query facet rows (used when constructing results)
+      #
+      # ==== Returns
+      #
+      # Array:: Array of QueryFacetRow objects.
+      #
+      def rows #:nodoc:
+        @components
+      end
+    end
+  end
+end

data/lib/sunspot/query/query_facet_row.rb

@@ -0,0 +1,19 @@
+module Sunspot
+  module Query
+    # 
+    # QueryFacetRow objects encapsulate restrictions for a particular
+    # QueryFacet. They also contain a label attribute, which is used as the
+    # value for the search result's corresponding facet row object.
+    #
+    # See Query::Scope for the API provided.
+    #
+    class QueryFacetRow < Connective::Conjunction
+      attr_reader :label #:nodoc:
+
+      def initialize(label, setup) #:nodoc:
+        super(setup)
+        @label = label
+      end
+    end
+  end
+end

data/lib/sunspot/query/restriction.rb

@@ -1,5 +1,5 @@
 module Sunspot
-  class Query
+  module Query
     module Restriction #:nodoc:
       class <<self
         #
@@ -33,6 +33,8 @@ module Sunspot
       # * #to_solr_conditional
       #
       class Base #:nodoc:
+        include RSolr::Char
+
         def initialize(field, value, negative = false)
           @field, @value, @negative = field, value, negative
         end
@@ -49,7 +51,7 @@ module Sunspot
         # Hash:: Representation of this restriction as solr-ruby parameters
         #
         def to_params
-          { :filter_queries => [to_boolean_phrase] }
+          { :fq => [to_boolean_phrase] }
         end
 
         # 
@@ -79,7 +81,7 @@ module Sunspot
         # String:: Boolean phrase for restriction in the positive
         #
         def to_positive_boolean_phrase
-          "#{Solr::Util.query_parser_escape(@field.indexed_name)}:#{to_solr_conditional}"
+          "#{escape(@field.indexed_name)}:#{to_solr_conditional}"
         end
 
         # 
@@ -117,7 +119,7 @@ module Sunspot
         # String:: Solr API representation of given value
         #
         def solr_value(value = @value)
-          Solr::Util.query_parser_escape(@field.to_indexed(value))
+          escape(@field.to_indexed(value))
         end
       end
 
@@ -130,7 +132,7 @@ module Sunspot
           unless @value.nil?
             super
           else
-            "-#{Solr::Util.query_parser_escape(@field.indexed_name)}:[* TO *]"
+            "-#{escape(@field.indexed_name)}:[* TO *]"
           end
         end
 
@@ -138,7 +140,7 @@ module Sunspot
           unless @value.nil?
             super
           else
-            "#{Solr::Util.query_parser_escape(@field.indexed_name)}:[* TO *]"
+            "#{escape(@field.indexed_name)}:[* TO *]"
           end
         end
 
@@ -215,7 +217,7 @@ module Sunspot
 
         def to_positive_boolean_phrase
           adapter = Adapters::InstanceAdapter.adapt(@object)
-          "id:#{Solr::Util.query_parser_escape(adapter.index_id)}"
+          "id:#{escape(adapter.index_id)}"
         end
       end
     end

data/lib/sunspot/query/scope.rb

@@ -0,0 +1,165 @@
+module Sunspot
+  module Query
+    # 
+    # The Scope class encapsulates a set of restrictions that scope search
+    # results (as well as query facets rows). This class's API is exposed by
+    # Query::Query and Query::QueryFacetRow.
+    # 
+    class Scope
+      # 
+      # Add a restriction to the query.
+      # 
+      # ==== Parameters
+      #
+      # field_name<Symbol>:: Name of the field to which the restriction applies
+      # restriction_type<Class,Symbol>::
+      #   Subclass of Sunspot::Query::Restriction::Base, or snake_cased name as symbol
+      #   (e.g., +:equal_to+)
+      # value<Object>::
+      #   Value against which the restriction applies (e.g. less_than(2) has a
+      #   value of 2)
+      # negated::
+      #   Whether this restriction should be negated (use add_negated_restriction)
+      #
+      def add_restriction(field_name, restriction_type, value, negated = false)
+        if restriction_type.is_a?(Symbol)
+          restriction_type = Restriction[restriction_type]
+        end
+        add_component(
+          restriction = restriction_type.new(
+            build_field(field_name), value, negated
+          )
+        )
+        restriction
+      end
+
+      # 
+      # Add a negated restriction to the query. The restriction will be taken as
+      # the opposite of its usual meaning (e.g., an :equal_to restriction will
+      # be "not equal to".
+      #
+      # ==== Parameters
+      #
+      # field_name<Symbol>:: Name of the field to which the restriction applies
+      # restriction_type<Class>::
+      #   Subclass of Sunspot::Query::Restriction::Base to instantiate
+      # value<Object>::
+      #   Value against which the restriction applies (e.g. less_than(2) has a
+      #   value of 2)
+      #
+      def add_negated_restriction(field_name, restriction_type, value)
+        add_restriction(field_name, restriction_type, value, true)
+      end
+
+      # 
+      # Add a disjunction to the scope. The disjunction can then take a set of
+      # restrictions, which are combined with OR semantics.
+      #
+      # ==== Returns
+      #
+      # Connective::Disjunction:: New disjunction
+      #
+      def add_disjunction
+        add_component(disjunction = Connective::Disjunction.new(setup))
+        disjunction
+      end
+
+      # 
+      # Add a conjunction to the scope. In most cases, this will simply return
+      # the Scope object itself, since scopes by default combine their
+      # restrictions with OR semantics. The Connective::Disjunction class
+      # overrides this method to return a Connective::Conjunction.
+      #
+      # ==== Returns
+      #
+      # Scope:: Self or another scope with conjunctive semantics.
+      #
+      def add_conjunction
+        self
+      end
+      
+      #
+      # Exclude a particular instance from the search results
+      #
+      # ==== Parameters
+      #
+      # instance<Object>:: instance to exclude from results
+      #
+      def exclude_instance(instance)
+        add_component(Restriction::SameAs.new(instance, true))
+      end
+
+      # 
+      # Generate a DynamicQuery instance for the given base name.
+      # This gives you access to a subset of the Query API but the operations
+      # apply to dynamic fields inside the dynamic field definition specified
+      # by +base_name+.
+      # 
+      # ==== Parameters
+      # 
+      # base_name<Symbol>::
+      #   Base name of the dynamic field definition to use in the dynamic query
+      #   operations
+      #
+      # ==== Returns
+      #
+      # DynamicQuery::
+      #   Instance providing dynamic query functionality for the given field
+      #   definitions.
+      #
+      def dynamic_query(base_name)
+        DynamicQuery.new(setup.dynamic_field_factory(base_name), self)
+      end
+
+      # 
+      # Determine which restriction type to add based on the type of the value.
+      # Used to interpret query conditions passed as a hash, as well as the
+      # short-form DSL::Scope#with method.
+      #
+      # ==== Parameters
+      #
+      # field_name<Symbol>:: Name of the field on which to apply the restriction
+      # value<Object,Array,Range>:: Value to which to apply to the restriction
+      #--
+      # negated<Boolean>:: Whether to negate the restriction.
+      #
+      def add_shorthand_restriction(field_name, value, negated = false) #:nodoc:
+        restriction_type =
+          case value
+          when Range
+            Restriction::Between
+          when Array
+            Restriction::AnyOf
+          else
+            Restriction::EqualTo
+          end
+        add_restriction(field_name, restriction_type, value, negated)
+      end
+
+      # 
+      # Add a negated shorthand restriction. See #add_shorthand_restriction
+      #
+      def add_negated_shorthand_restriction(field_name, value)
+        add_shorthand_restriction(field_name, value, true)
+      end
+
+      private
+
+      # 
+      # Build a field with the given field name. Subclasses may override this
+      # method.
+      #
+      def build_field(field_name)
+        setup.field(field_name)
+      end
+
+      # 
+      # Return a setup object which can return a field object given a name.
+      # Subclasses may override this method.
+      #
+      def setup
+        @setup
+      end
+    end
+  end
+end

data/lib/sunspot/query/sort.rb

@@ -1,32 +1,35 @@
 module Sunspot
-  class Query
+  module Query
     # 
     # The Sort class is a query component representing a sort by a given field.
     # 
     class Sort #:nodoc:
-      ASCENDING = Set.new([:asc, :ascending])
-      DESCENDING = Set.new([:desc, :descending])
+      DIRECTIONS = {
+        :asc => 'asc',
+        :ascending => 'asc',
+        :desc => 'desc',
+        :descending => 'desc'
+      }
 
       def initialize(field, direction = nil)
+        if field.multiple?
+          raise(ArgumentError, "#{field.name} cannot be used for ordering because it is a multiple-value field")
+        end
         @field, @direction = field, (direction || :asc).to_sym
       end
 
-      def to_params
-        { :sort => [{ @field.indexed_name.to_sym => direction_for_solr }] }
+      def to_param
+        "#{@field.indexed_name.to_sym} #{direction_for_solr}"
       end
 
       private
 
       def direction_for_solr
-        case
-        when ASCENDING.include?(@direction)
-          :ascending
-        when DESCENDING.include?(@direction)
-          :descending
-        else
-          raise ArgumentError,
-                "Unknown sort direction #{@direction}. Acceptable input is: #{(ASCENDING + DESCENDING).map { |input| input.inspect } * ', '}"
-        end
+        DIRECTIONS[@direction] || 
+          raise(
+            ArgumentError,
+            "Unknown sort direction #{@direction}. Acceptable input is: #{DIRECTIONS.keys.map { |input| input.inspect } * ', '}"
+        )
       end
     end
   end

data/lib/sunspot/query/sort_composite.rb

@@ -0,0 +1,33 @@
+module Sunspot
+  module Query
+    # 
+    # The SortComposite class encapsulates an ordered collection of Sort
+    # objects. It's necessary to keep this as a separate class as Solr takes
+    # the sort as a single parameter, so adding sorts as regular components
+    # would not merge correctly in the #to_params method.
+    #
+    class SortComposite #:nodoc:
+      def initialize
+        @sorts = []
+      end
+
+      # 
+      # Add a sort to the composite
+      #
+      def <<(sort)
+        @sorts << sort
+      end
+
+      # 
+      # Combine the sorts into a single param by joining them
+      #
+      def to_params
+        unless @sorts.empty?
+          { :sort => @sorts.map { |sort| sort.to_param } * ', ' }
+        else
+          {}
+        end
+      end
+    end
+  end
+end