outoftime-sunspot 0.0.2 → 0.7.0

data/lib/sunspot/query.rb

@@ -1,96 +1,232 @@
 module Sunspot
-  class Query
-    attr_accessor :keywords, :conditions, :rows, :start, :sort
+  # 
+  # This class encapsulates a query that is to be sent to Solr. The query is
+  # constructed in the block passed to the Sunspot.search method, using the
+  # Sunspot::DSL::Query interface. Instances of Query, as well as all of the
+  # components it contains, respond to the #to_params method, which returns
+  # a hash of parameters in the format recognized by the solr-ruby API.
+  #
+  class Query #:nodoc:
+    attr_writer :keywords # <String> full-text keyword boolean phrase
 
     def initialize(types, params, configuration)
       @types, @configuration = types, configuration
-      paginate
+      @rows = @configuration.pagination.default_per_page
+      apply_params(params)
     end
 
-    def to_solr
+    # 
+    # Representation of this query as solr-ruby parameters. Constructs the hash
+    # by deep-merging scope and facet parameters, adding in various other
+    # parameters from instance data.
+    #
+    # Note that solr-ruby takes the :q parameter as a separate argument; for
+    # the sake of consistency, the Query object ignores this fact (the Search
+    # object extracts it back out).
+    #
+    # ==== Returns
+    #
+    # Hash:: Representation of query in solr-ruby form
+    #
+    def to_params
+      params = {}
       query_components = []
-      query_components << keywords if keywords
-      query_components << types_query if types_query
-      query_components.map { |component| "(#{component})"} * ' AND '
+      query_components << @keywords if @keywords
+      query_components << types_phrase if types_phrase
+      params[:q] = query_components.map { |component| "(#{component})"} * ' AND '
+      params[:sort] = @sort if @sort
+      params[:start] = @start if @start
+      params[:rows] = @rows if @rows
+      for component in components
+        Util.deep_merge!(params, component.to_params)
+      end
+      params
     end
 
-    def filter_queries
-      scope_queries
+    # 
+    # Add a query component
+    #
+    # ==== Parameters
+    #
+    # component<~to_params>::  A restriction query component
+    #
+    def add_component(component)
+      components << component
     end
 
-    def add_scope(condition)
-      scope << condition
+    # 
+    # Add instance of Sunspot::Restriction::Base to query components. This
+    # method is exposed to the DSL because the Query instance holds field
+    # definitions and is able to translate field names into full field
+    # definitions, and memoize # the result.
+    # 
+    # ==== Parameters
+    #
+    # field_name<Symbol>:: Name of the field to which the restriction applies
+    # restriction_clazz<Class>::
+    #   Subclass of Sunspot::Restriction::Base to instantiate
+    # value<Object>::
+    #   Value against which the restriction applies (e.g. less_than(2) has a
+    #   value of 2)
+    # negative:: Whether this restriction should be negated
+    #
+    # ==== Returns
+    #
+    # Sunspot::Restriction::Base:: Restriction instance
+    #
+    def add_restriction(field_name, restriction_clazz, value, negative = false)
+      add_component(restriction_clazz.new(field(field_name), value, negative))
     end
 
-    def build_condition(field_name, condition_clazz, value)
-      condition_clazz.new(field(field_name), value)
+    # 
+    # Add a field facet
+    #
+    # ==== Parameters
+    #
+    # field_name<Symbol>:: Name of the field on which to get a facet
+    #
+    def add_field_facet(field_name)
+      add_component(Facets::FieldFacet.new(field(field_name)))
     end
 
-    def paginate(page = nil, per_page = nil)
-      page ||= 1
-      per_page ||= configuration.pagination.default_per_page
+    #
+    # Sets @start and @rows instance variables using pagination semantics
+    #
+    # ==== Parameters
+    #
+    # page<Integer>:: Page on which to start
+    # per_page<Integer>::
+    #   How many rows to display per page. Default taken from
+    #   Sunspot.config.pagination.default_per_page
+    #
+    def paginate(page, per_page = nil)
+      per_page ||= @configuration.pagination.default_per_page
       @start = (page - 1) * per_page
       @rows = per_page
     end
 
-    def order=(order)
-      order_by(*order.split(' '))
-    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)
       direction ||= :asc
-      @sort = [{ field(field_name).indexed_name.to_sym => (direction.to_s == 'asc' ? :ascending : :descending) }] #TODO should support multiple order columns
+      (@sort ||= []) << { field(field_name).indexed_name.to_sym => (direction.to_s == 'asc' ? :ascending : :descending) }
     end
 
+    # 
+    # Page that this query will return (used by Sunspot::Search to expose
+    # pagination)
+    #
+    # ==== Returns
+    #
+    # Integer:: Page number
+    #
     def page
-      return nil unless start && rows
-      start / rows + 1
+      if @start && @rows
+        @start / @rows + 1
+      else
+        1
+      end
     end
 
-    def dsl
-      @dsl ||= ::Sunspot::DSL::Query.new(self)
+    #
+    # Number of rows per page that this query will return (used by
+    # Sunspot::Search to expose pagination)
+    #
+    # ==== Returns
+    #
+    # Integer:: Rows per page
+    #
+    def per_page
+      @rows
     end
 
-    def build_with(builder_class, *args)
-      builder_class.new(dsl, types, fields_hash.keys, *args)
+    # 
+    # Get a DSL instance for building this query.
+    #
+    # ==== Returns
+    #
+    # Sunspot::DSL::Query:: DSL instance
+    #
+    def dsl
+      @dsl ||= DSL::Query.new(self)
     end
 
-    alias_method :per_page, :rows
-
-    protected
-    attr_accessor :types, :configuration
+    # 
+    # Get a Sunspot::Field::Base instance corresponding to the given field name
+    #
+    # ==== Parameters
+    #
+    # field_name<Symbol>:: The field name for which to find a field
+    #
+    # ==== Returns
+    #
+    # Sunspot::Field::Base:: The field object corresponding to the given name
+    #
+    # ==== Raises
+    #
+    # ArgumentError::
+    #   If the given field name is not configured for the types being queried
+    #
+    def field(field_name)
+      fields_hash[field_name.to_sym] || raise(UnrecognizedFieldError, "No field configured for #{@types * ', '} with name '#{field_name}'")
+    end
 
     private
 
-    def scope
-      @scope ||= []
+    # ==== Returns
+    #
+    # Array:: Collection of query components
+    #
+    def components
+      @components ||= []
     end
 
-    def scope_queries
-      scope.map { |condition| condition.to_solr_query }
-    end
-
-    def types_query
-      if types.nil? || types.empty? then "type:[* TO *]"
-      elsif types.length == 1 then "type:#{types.first}"
-      else "type:(#{types * ' OR '})"
+    # 
+    # Boolean phrase that restricts results to objects of the type(s) under
+    # query. If this is an open query (no types specified) then it sends a
+    # no-op phrase because Solr requires that the :q parameter not be empty.
+    #
+    # TODO don't send a noop if we have a keyword phrase
+    # TODO this should be sent as a filter query when possible, especially
+    #      if there is a single type, so that Solr can cache it
+    #
+    # ==== Returns
+    #
+    # String:: Boolean phrase for type restriction
+    #
+    def types_phrase
+      if @types.nil? || @types.empty? then "type:[* TO *]"
+      elsif @types.length == 1 then "type:#{@types.first}"
+      else "type:(#{@types * ' OR '})"
       end
     end
 
-    def field(field_name)
-      fields_hash[field_name.to_s] || raise(ArgumentError, "No field configured for #{types * ', '} with name '#{field_name}'")
-    end
-
+    # 
+    # Return a hash of field names to field objects, containing all fields
+    # that are common to all of the classes under search. In order for fields
+    # to be common, they must be of the same type and have the same
+    # value for allow_multiple?. This method is memoized.
+    #
+    # ==== Returns
+    #
+    # Hash:: field names keyed to field objects
+    #
     def fields_hash
       @fields_hash ||= begin
-        fields_hash = types.inject({}) do |hash, type|
-          ::Sunspot::Field.for(type).each do |field|
-            (hash[field.name.to_s] ||= {})[type.name] = field
+        fields_hash = @types.inject({}) do |hash, type|
+          Setup.for(type).fields.each do |field|
+            (hash[field.name.to_sym] ||= {})[type.name] = field
           end
           hash
         end
         fields_hash.each_pair do |field_name, field_configurations_hash|
-          if types.any? { |type| field_configurations_hash[type.name].nil? } # at least one type doesn't have this field configured
+          if @types.any? { |type| field_configurations_hash[type.name].nil? } # at least one type doesn't have this field configured
             fields_hash.delete(field_name)
           elsif field_configurations_hash.values.map { |configuration| configuration.indexed_name }.uniq.length != 1 # fields with this name have different configs
             fields_hash.delete(field_name)
@@ -100,5 +236,37 @@ module Sunspot
         end
       end
     end
+
+    def apply_params(params)
+      if params.has_key?(:keywords)
+        self.keywords = params[:keywords]
+      end
+      if params.has_key?(:conditions)
+        params[:conditions].each_pair do |field_name, value|
+          begin
+            restriction_type =
+              case value
+              when Array
+                Restriction::AnyOf
+              when Range
+                Restriction::Between
+              else
+                Restriction::EqualTo
+              end
+            add_restriction(field_name, restriction_type, value)
+          rescue UnrecognizedFieldError
+            # ignore fields we don't recognize
+          end
+        end
+      end
+      if params.has_key?(:order)
+        for order in Array(params[:order])
+          order_by(*order.split(' '))
+        end
+      end
+      if params.has_key?(:page)
+        paginate(params[:page], params[:per_page])
+      end
+    end
   end
 end

data/lib/sunspot/restriction.rb

@@ -1,27 +1,141 @@
 module Sunspot
-  module Restriction
-    class Base
-      def initialize(field, value)
-        @field, @value = field, value
+  module Restriction #:nodoc:
+    class <<self
+      #
+      # Return the names of all of the restriction classes that should be made
+      # available to the DSL.
+      #
+      # ==== Returns
+      # 
+      # Array:: Collection of restriction class names
+      #
+      def names
+        constants - %w(Base SameAs) #XXX this seems ugly
+      end
+    end
+
+    # 
+    # Subclasses of this class represent restrictions that can be applied to
+    # a Sunspot query. The Sunspot::DSL::Restriction class presents a builder
+    # API for instances of this class.
+    #
+    # Implementations of this class must respond to #to_params and
+    # #to_negative_params. Instead of implementing those methods, they may
+    # choose to implement any of:
+    #
+    # * #to_positive_boolean_phrase, and optionally #to_negative_boolean_phrase
+    # * #to_solr_conditional
+    #
+    class Base #:nodoc:
+      def initialize(field, value, negative = false)
+        @field, @value, @negative = field, value, negative
+      end
+
+      # 
+      # A hash representing this restriction in solr-ruby's parameter format.
+      # All restriction implementations must respond to this method; however,
+      # the base implementation delegates to the #to_positive_boolean_phrase method, so
+      # subclasses may (and probably should) choose to implement that method
+      # instead.
+      #
+      # ==== Returns
+      #
+      # Hash:: Representation of this restriction as solr-ruby parameters
+      #
+      def to_params
+        { :filter_queries => [to_boolean_phrase] }
+      end
+
+      # 
+      # Return the boolean phrase associated with this restriction object.
+      # Differentiates between positive and negative boolean phrases depending
+      # on whether this restriction is negated.
+      #
+      def to_boolean_phrase
+        unless negative?
+          to_positive_boolean_phrase
+        else
+          to_negative_boolean_phrase
+        end
+      end
+
+      # 
+      # Boolean phrase representing this restriction in the positive. Subclasses
+      # may choose to implement this method rather than #to_params; however,
+      # this method delegates to the abstract #to_solr_conditional method, which
+      # in most cases will be what subclasses will want to implement.
+      # #to_solr_conditional contains the boolean phrase representing the
+      # condition but leaves out the field name (see built-in implementations
+      # for examples)
+      #
+      # ==== Returns
+      #
+      # String:: Boolean phrase for restriction in the positive
+      #
+      def to_positive_boolean_phrase
+        "#{@field.indexed_name}:#{to_solr_conditional}"
       end
 
-      def to_solr_query
-        "#{field.indexed_name}:#{to_solr_conditional}"
+      # 
+      # Boolean phrase representing this restriction in the negative. Subclasses
+      # may choose to implement this method, but it is not necessary, as the
+      # base implementation delegates to #to_positive_boolean_phrase.
+      #
+      # ==== Returns
+      #
+      # String:: Boolean phrase for restriction in the negative
+      #
+      def to_negative_boolean_phrase
+        "-#{to_positive_boolean_phrase}"
       end
 
       protected
-      attr_accessor :field, :value
 
-      def solr_value(value = self.value)
-        escape field.to_indexed(value)
+      # 
+      # Whether this restriction should be negated from its original meaning
+      #
+      def negative?
+        !!@negative
       end
 
-      def escape(value)
-        Solr::Util.query_parser_escape value
+      # 
+      # Return escaped Solr API representation of given value
+      #
+      # ==== Parameters
+      #
+      # value<Object>::
+      #   value to convert to Solr representation (default: @value)
+      #
+      # ==== Returns
+      #
+      # String:: Solr API representation of given value
+      #
+      def solr_value(value = @value)
+        Solr::Util.query_parser_escape(@field.to_indexed(value))
       end
     end
 
+    # 
+    # Results must have field with value equal to given value. If the value
+    # is nil, results must have no value for the given field.
+    #
     class EqualTo < Base
+      def to_positive_boolean_phrase
+        unless @value.nil?
+          super
+        else
+          "-#{@field.indexed_name}:[* TO *]"
+        end
+      end
+
+      def to_negative_boolean_phrase
+        unless @value.nil?
+          super
+        else
+          "#{@field.indexed_name}:[* TO *]"
+        end
+      end
+
       private
 
       def to_solr_conditional
@@ -29,6 +143,9 @@ module Sunspot
       end
     end
 
+    # 
+    # Results must have field with value less than given value
+    #
     class LessThan < Base
       private
 
@@ -37,6 +154,9 @@ module Sunspot
       end
     end
 
+    # 
+    # Results must have field with value greater than given value
+    #
     class GreaterThan < Base
       private
 
@@ -45,27 +165,51 @@ module Sunspot
       end
     end
 
+    # 
+    # Results must have field with value in given range
+    #
     class Between < Base
       private
 
       def to_solr_conditional
-        "[#{solr_value value.first} TO #{solr_value value.last}]"                  
+        "[#{solr_value(@value.first)} TO #{solr_value(@value.last)}]"
       end
     end
 
+    # 
+    # Results must have field with value included in given collection
+    #
     class AnyOf < Base
       private
 
       def to_solr_conditional
-        "(#{value.map { |v| solr_value v } * ' OR '})"
+        "(#{@value.map { |v| solr_value v } * ' OR '})"
       end
     end
 
+    #
+    # Results must have field with values matching all values in given
+    # collection (only makes sense for fields with multiple values)
+    #
     class AllOf < Base
       private
 
       def to_solr_conditional
-        "(#{value.map { |v| solr_value v } * ' AND '})"
+        "(#{@value.map { |v| solr_value v } * ' AND '})"
+      end
+    end
+
+    # 
+    # Result must be the exact instance given (only useful when negated).
+    #
+    class SameAs < Base
+      def initialize(object, negative = false)
+        @object, @negative = object, negative
+      end
+
+      def to_positive_boolean_phrase
+        adapter = Adapters::InstanceAdapter.adapt(@object)
+        "id:#{Solr::Util.query_parser_escape(adapter.index_id)}"
       end
     end
   end

data/lib/sunspot/search.rb

@@ -1,33 +1,41 @@
 module Sunspot
+  # 
+  # This class encapsulates the results of a Solr search. It provides access
+  # to search results, total result count, facets, and pagination information.
+  # Instances of Search are returned by the Sunspot.search method.
+  #
   class Search
-    attr_reader :builder
+    RawResult = Struct.new(:class_name, :primary_key)
 
-    def initialize(connection, configuration, *types, &block)
+    def initialize(connection, configuration, *types, &block) #:nodoc:
       @connection = connection
       params = types.last.is_a?(Hash) ? types.pop : {}
-      @query = Sunspot::Query.new(types, params, configuration)
-      @builder = build_with(::Sunspot::Builder::StandardBuilder, params)
+      @query = Query.new(types, params, configuration)
       @query.dsl.instance_eval(&block) if block
       @types = types
     end
 
-    def build_with(builder_class, *args)
-      @query.build_with(builder_class, *args)
-    end
-
-    def execute!
-      query_options = {}
-      query_options[:filter_queries] = query.filter_queries
-      query_options[:rows] = query.rows
-      query_options[:start] = query.start if query.start
-      query_options[:sort] = query.sort if query.sort
-      @solr_result = connection.query(query.to_solr, query_options)
+    #
+    # Execute the search on the Solr instance and store the results
+    #
+    def execute! #:nodoc:
+      params = @query.to_params
+      @solr_result = @connection.query(params.delete(:q), params)
       self
     end
 
+    # 
+    # Get the collection of results as instantiated objects. If WillPaginate is
+    # available, the results will be a WillPaginate::Collection instance; if
+    # not, it will be a vanilla Array.
+    #
+    # ==== Returns
+    #
+    # WillPaginate::Collection or Array:: Instantiated result objects
+    #
     def results
-      @results ||= if query.page && defined?(WillPaginate::Collection)
-        WillPaginate::Collection.create(query.page, query.per_page, @solr_result.total_hits) do |pager|
+      @results ||= if @query.page && defined?(WillPaginate::Collection)
+        WillPaginate::Collection.create(@query.page, @query.per_page, @solr_result.total_hits) do |pager|
           pager.replace(result_objects)
         end
       else
@@ -35,32 +43,75 @@ module Sunspot
       end
     end
 
+    # 
+    # Access raw results without instantiating objects from persistent storage.
+    # This may be useful if you are using search as an intermediate step in data
+    # retrieval. Returns an ordered collection of objects that respond to
+    # #class_name and #primary_key
+    #
+    # ==== Returns
+    #
+    # Array:: Ordered collection of raw results
+    #
+    def raw_results
+      @raw_results ||= hit_ids.map { |hit_id| RawResult.new(*hit_id.match(/([^ ]+) (.+)/)[1..2]) }
+    end
+
+    # 
+    # The total number of documents matching the query parameters
+    #
+    # ==== Returns
+    #
+    # Integer:: Total matching documents
+    #
     def total
       @total ||= @solr_result.total_hits
     end
 
-    protected
-    attr_reader :query, :types, :connection
+    # 
+    # Get the facet object for the given field. This field will need to have
+    # been requested as a field facet inside the search block.
+    #
+    # ==== Parameters
+    #
+    # field_name<Symbol>:: field name for which to get the facet
+    #
+    # ==== Returns
+    #
+    # Sunspot::Facet:: Facet object for the given field
+    #
+    def facet(field_name)
+      (@facets_cache ||= {})[field_name.to_sym] ||=
+        begin
+          field = @query.field(field_name)
+          Facet.new(@solr_result.field_facets(field.indexed_name), field)
+        end
+    end
 
     private
 
+    # 
+    # Collection of instantiated result objects corresponding to the results
+    # returned by Solr.
+    #
+    # ==== Returns
+    #
+    # Array:: Collection of instantiated result objects
+    #
     def result_objects
-      hit_ids = @solr_result.hits.map { |hit| hit['id'] }
-      hit_ids.inject({}) do |type_id_hash, hit_id|
-        match = /([^ ]+) (.+)/.match hit_id
-        (type_id_hash[match[1]] ||= []) << match[2]
+      raw_results.inject({}) do |type_id_hash, raw_result|
+        (type_id_hash[raw_result.class_name] ||= []) << raw_result.primary_key
         type_id_hash
       end.inject([]) do |results, pair|
         type_name, ids = pair
-        results.concat ::Sunspot::Adapters.adapt_class(type_with_name(type_name)).load_all(ids)
+        results.concat(Adapters::DataAccessor.create(Util.full_const_get(type_name)).load_all(ids))
       end.sort_by do |result|
-        hit_ids.index(::Sunspot::Adapters.adapt_instance(result).index_id)
+        hit_ids.index(Adapters::InstanceAdapter.adapt(result).index_id)
       end
     end
 
-    def type_with_name(type_name)
-      @types_cache ||= {}
-      @types_cache[type_name] ||= type_name.split('::').inject(Module) { |namespace, name| namespace.const_get(name) }
+    def hit_ids
+      @hit_ids ||= @solr_result.hits.map { |hit| hit['id'] }
     end
   end
 end