sunspot 1.0.5 → 1.1.0

data/lib/sunspot/query/{query.rb → common_query.rb}

@@ -1,12 +1,10 @@
 module Sunspot
-  module Query
-    class Query
-      attr_accessor :scope, :fulltext, :parameter_adjustment
-
+  module Query #:nodoc:
+    class CommonQuery
       def initialize(types)
         @scope = Scope.new
         @sort = SortComposite.new
-        @components = []
+        @components = [@scope, @sort]
         if types.length == 1
           @scope.add_restriction(TypeField.instance, Restriction::EqualTo, types.first)
         else
@@ -14,18 +12,10 @@ module Sunspot
         end
       end
 
-      def set_fulltext(keywords)
-        @fulltext = Dismax.new(keywords)
-      end
-      
-      def set_solr_parameter_adjustment( block )
+      def solr_parameter_adjustment=(block)
         @parameter_adjustment = block
       end
 
-      def add_location_restriction(coordinates, radius)
-        @local = Local.new(coordinates, radius)
-      end
-
       def add_sort(sort)
         @sort << sort
       end
@@ -40,21 +30,22 @@ module Sunspot
         facet
       end
 
+      def add_function(function)
+        @components << function
+        function
+      end
+
       def paginate(page, per_page)
         if @pagination
           @pagination.page = page
           @pagination.per_page = per_page
         else
-          @pagination = Pagination.new(page, per_page)
+          @components << @pagination = Pagination.new(page, per_page)
         end
       end
 
       def to_params
-        params = @scope.to_params
-        Sunspot::Util.deep_merge!(params, @fulltext.to_params) if @fulltext
-        Sunspot::Util.deep_merge!(params, @sort.to_params)
-        Sunspot::Util.deep_merge!(params, @pagination.to_params) if @pagination
-        Sunspot::Util.deep_merge!(params, @local.to_params) if @local
+        params = {}
         @components.each do |component|
           Sunspot::Util.deep_merge!(params, component.to_params)
         end
@@ -74,6 +65,21 @@ module Sunspot
       def per_page
         @pagination.per_page if @pagination
       end
+
+
+      private
+
+      #
+      # If we have a single fulltext query, merge is normally. If there are
+      # multiple nested queries, serialize them as `_query_` subqueries.
+      #
+      def merge_fulltext(params)
+        return nil if @fulltexts.empty?
+        return Sunspot::Util.deep_merge!(params, @fulltexts.first.to_params) if @fulltexts.length == 1
+        subqueries = @fulltexts.map {|fulltext| fulltext.to_subquery }.join(' ')
+        Sunspot::Util.deep_merge!(params, {:q => subqueries})
+      end
+
     end
   end
 end

data/lib/sunspot/query/composite_fulltext.rb

@@ -0,0 +1,31 @@
+module Sunspot
+  module Query
+    class CompositeFulltext
+      def initialize
+        @components = []
+      end
+
+      def add(keywords)
+        @components << dismax = Dismax.new(keywords)
+        dismax
+      end
+
+      def to_params
+        case @components.length
+        when 0
+          {}
+        when 1
+          @components.first.to_params
+        else
+          to_subqueries
+        end
+      end
+
+      private
+
+      def to_subqueries
+        { :q => @components.map { |dismax| dismax.to_subquery }.join(' ') }
+      end
+    end
+  end
+end

data/lib/sunspot/query/dismax.rb

@@ -1,5 +1,11 @@
 module Sunspot
   module Query
+
+    #
+    # Solr full-text queries use Solr's DisMaxRequestHandler, a search handler
+    # designed to process user-entered phrases, and search for individual
+    # words across a union of several fields.
+    #
     class Dismax
       attr_writer :minimum_match, :phrase_slop, :query_phrase_slop, :tie
 
@@ -7,10 +13,11 @@ module Sunspot
         @keywords = keywords
         @fulltext_fields = {}
         @boost_queries = []
+        @boost_functions = []
         @highlights = []
       end
 
-      # 
+      #
       # The query as Solr parameters
       #
       def to_params
@@ -26,6 +33,11 @@ module Sunspot
             boost_query.to_boolean_phrase
           end
         end
+        unless @boost_functions.empty?
+          params[:bf] = @boost_functions.map do |boost_function|
+            boost_function.to_s
+          end
+        end
         if @minimum_match
           params[:mm] = @minimum_match
         end
@@ -44,7 +56,18 @@ module Sunspot
         params
       end
 
-      # 
+      #
+      # Serialize the query as a Solr nested subquery.
+      #
+      def to_subquery
+        params = self.to_params
+        params.delete :defType
+        keywords = params.delete(:q)
+        options = params.map { |key, value| "#{key}='#{escape_quotes(value)}'"}.join(' ')
+        "_query_:\"{!dismax #{options}}#{escape_quotes(keywords)}\""
+      end
+
+      #
       # Assign a new boost query and return it.
       #
       def create_boost_query(factor)
@@ -53,21 +76,28 @@ module Sunspot
       end
 
       # 
-      # Add a fulltext field to be searched, with optional boost
+      # Add a boost function
+      #
+      def add_boost_function(function_query)
+        @boost_functions << function_query
+      end
+
+      #
+      # Add a fulltext field to be searched, with optional boost.
       #
       def add_fulltext_field(field, boost = nil)
         @fulltext_fields[field.indexed_name] = TextFieldBoost.new(field, boost)
       end
 
       #
-      # Add a phrase field for extra boost
+      # Add a phrase field for extra boost.
       #
       def add_phrase_field(field, boost = nil)
         @phrase_fields ||= []
         @phrase_fields << TextFieldBoost.new(field, boost)
       end
 
-      # 
+      #
       # Set highlighting options for the query. If fields is empty, the
       # Highlighting object won't pass field names at all, which means
       # the dismax's :qf parameter will be used by Solr.
@@ -76,13 +106,22 @@ module Sunspot
         @highlights << Highlighting.new(fields, options)
       end
 
-      # 
+      #
       # Determine if a given field is being searched. Used by DSL to avoid
       # overwriting boost parameters when injecting defaults.
       #
       def has_fulltext_field?(field)
         @fulltext_fields.has_key?(field.indexed_name)
       end
+
+
+      private
+
+      def escape_quotes(value)
+        return value unless value.is_a? String
+        value.gsub(/(['"])/, '\\\\\1')
+      end
+
     end
   end
 end

data/lib/sunspot/query/function_query.rb

@@ -0,0 +1,52 @@
+module Sunspot
+  module Query
+    # 
+    # Abstract class for function queries.
+    #
+    class FunctionQuery 
+      include RSolr::Char
+    end
+
+    #
+    # Function query which represents a constant.
+    #
+    class ConstantFunctionQuery < FunctionQuery
+      def initialize(constant)
+        @constant = constant
+      end
+
+      def to_s
+        Type.to_literal(@constant)
+      end
+    end
+
+    #
+    # Function query which represents a field.
+    #
+    class FieldFunctionQuery < FunctionQuery
+      def initialize(field)
+        @field = field
+      end
+
+      def to_s
+        "#{escape(@field.indexed_name)}"
+      end
+    end
+
+    #
+    # Function query which represents an actual function invocation.
+    # Takes a function name and arguments as parameters.
+    # Arguments are in turn FunctionQuery objects.
+    #
+    class FunctionalFunctionQuery < FunctionQuery
+      def initialize(function_name, function_args)
+        @function_name, @function_args = function_name, function_args
+      end
+
+      def to_s
+        params = @function_args.map { |arg| arg.to_s }.join(",")
+        "#{@function_name}(#{params})"
+      end
+    end
+  end
+end

data/lib/sunspot/query/more_like_this.rb

@@ -0,0 +1,60 @@
+module Sunspot
+  module Query
+    class MoreLikeThis
+      attr_reader :fields
+
+      def initialize(document)
+        @document_scope = Restriction::EqualTo.new(
+          IdField.instance,
+          Adapters::InstanceAdapter.adapt(document).index_id
+        )
+        @fields = {}
+        @params = {}
+      end
+
+      def add_field(field, boost = nil)
+        raise(ArgumentError, "Field #{field.name} is not set up for more_like_this") unless field.more_like_this?
+        @fields[field.indexed_name] = TextFieldBoost.new(field, boost)
+      end
+
+      def minimum_term_frequency=(mintf)
+        @params[:"mlt.mintf"] = mintf
+      end
+
+      def minimum_document_frequency=(mindf)
+        @params[:"mlt.mindf"] = mindf
+      end
+
+      def minimum_word_length=(minwl)
+        @params[:"mlt.minwl"] = minwl
+      end
+
+      def maximum_word_length=(maxwl)
+        @params[:"mlt.maxwl"] = maxwl
+      end
+      
+      def maximum_query_terms=(maxqt)
+        @params[:"mlt.maxqt"] = maxqt
+      end
+
+      def boost_by_relevance=(should_boost)
+        @params[:"mlt.boost"] = should_boost
+      end
+
+      def to_params
+        params = Sunspot::Util.deep_merge(
+          @params,
+          :q => @document_scope.to_boolean_phrase
+        )
+        params[:"mlt.fl"] = @fields.keys.join(",")
+        boosted_fields = @fields.values.select { |field| field.boost }
+        unless boosted_fields.empty?
+          params[:qf] = boosted_fields.map do |field|
+            field.to_boosted_field
+          end.join(' ')
+        end
+        params
+      end
+    end
+  end
+end

data/lib/sunspot/query/more_like_this_query.rb

@@ -0,0 +1,12 @@
+module Sunspot
+  module Query
+    class MoreLikeThisQuery < CommonQuery
+      attr_accessor :scope, :more_like_this
+
+      def initialize(document, types)
+        super(types)
+        @components << @more_like_this = MoreLikeThis.new(document)
+      end
+    end
+  end
+end

data/lib/sunspot/query/standard_query.rb

@@ -0,0 +1,20 @@
+module Sunspot
+  module Query
+    class StandardQuery < CommonQuery
+      attr_accessor :scope, :fulltext
+
+      def initialize(types)
+        super
+        @components << @fulltext = CompositeFulltext.new
+      end
+
+      def add_fulltext(keywords)
+        @fulltext.add(keywords)
+      end
+
+      def add_location_restriction(coordinates, radius)
+        @components << @local = Local.new(coordinates, radius)
+      end
+    end
+  end
+end

data/lib/sunspot/query/text_field_boost.rb

@@ -1,6 +1,8 @@
 module Sunspot
   module Query
     class TextFieldBoost #:nodoc:
+      attr_reader :boost
+
       def initialize(field, boost = nil)
         @field, @boost = field, boost
       end

data/lib/sunspot/query.rb

@@ -1,6 +1,7 @@
 %w(filter abstract_field_facet connective boost_query date_field_facet dismax
-   field_facet highlighting local pagination restriction query
-   query_facet scope sort sort_composite text_field_boost).each do |file|
+   field_facet highlighting local pagination restriction common_query
+   standard_query more_like_this more_like_this_query query_facet scope sort
+   sort_composite text_field_boost function_query composite_fulltext).each do |file|
   require(File.join(File.dirname(__FILE__), 'query', file))
 end
 module Sunspot

data/lib/sunspot/search/abstract_search.rb

@@ -0,0 +1,302 @@
+module Sunspot
+  module Search #:nodoc:
+    # 
+    # 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 and
+    # Sunspot.new_search methods.
+    #
+    class AbstractSearch
+      # 
+      # Retrieve all facet objects defined for this search, in order they were
+      # defined. To retrieve an individual facet by name, use #facet()
+      #
+      attr_reader :facets
+      attr_reader :query #:nodoc:
+      attr_accessor :request_handler
+  
+      def initialize(connection, setup, query, configuration) #:nodoc:
+        @connection, @setup, @query = connection, setup, query
+        @query.paginate(1, configuration.pagination.default_per_page)
+        @facets = []
+        @facets_by_name = {}
+      end
+  
+      #
+      # Execute the search on the Solr instance and store the results. If you
+      # use Sunspot#search() to construct your searches, there is no need to call
+      # this method as it has already been called. If you use
+      # Sunspot#new_search(), you will need to call this method after building the
+      # query.
+      #
+      def execute
+        reset
+        params = @query.to_params
+        @solr_result = @connection.request("/#{request_handler}", params)
+        self
+      end
+
+      def execute! #:nodoc: deprecated
+        execute
+      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.
+      #
+      # If not all of the results referenced by the Solr hits actually exist in
+      # the data store, Sunspot will only return the results that do exist.
+      #
+      # ==== Returns
+      #
+      # WillPaginate::Collection or Array:: Instantiated result objects
+      #
+      def results
+        @results ||= maybe_will_paginate(verified_hits.map { |hit| hit.instance })
+      end
+  
+      # 
+      # Access raw Solr result information. Returns a collection of Hit objects
+      # that contain the class name, primary key, keyword relevance score (if
+      # applicable), and any stored fields.
+      #
+      # ==== Options (options)
+      #
+      # :verify::
+      #   Only return hits that reference objects that actually exist in the data
+      #   store. This causes results to be eager-loaded from the data store,
+      #   unlike the normal behavior of this method, which only loads the
+      #   referenced results when Hit#result is first called.
+      #
+      # ==== Returns
+      #
+      # Array:: Ordered collection of Hit objects
+      #
+      def hits(options = {})
+        if options[:verify]
+          verified_hits
+        else
+          @hits ||=
+            begin
+              hits = if solr_response && solr_response['docs']
+                solr_response['docs'].map do |doc|
+                  Hit.new(doc, highlights_for(doc), distance_for(doc), self)
+                end
+              end
+              maybe_will_paginate(hits || [])
+            end
+        end
+      end
+      alias_method :raw_results, :hits
+  
+      #
+      # Convenience method to iterate over hit and result objects. Block is
+      # yielded a Sunspot::Server::Hit instance and a Sunspot::Server::Result
+      # instance.
+      #
+      # Note that this method iterates over verified hits (see #hits method
+      # for more information).
+      #
+      def each_hit_with_result
+        verified_hits.each do |hit|
+          yield(hit, hit.result)
+        end
+      end
+  
+      # 
+      # The total number of documents matching the query parameters
+      #
+      # ==== Returns
+      #
+      # Integer:: Total matching documents
+      #
+      def total
+        @total ||= solr_response['numFound'] || 0
+      end
+  
+      # 
+      # Get the facet object for the given name. `name` can either be the name
+      # given to a query facet, or the field name of a field facet. Returns a
+      # Sunspot::Facet object.
+      #
+      # ==== Parameters
+      #
+      # name<Symbol>::
+      #   Name of the field to return the facet for, or the name given to the
+      #   query facet when the search was constructed.
+      # dynamic_name<Symbol>::
+      #   If faceting on a dynamic field, this is the dynamic portion of the field
+      #   name.
+      #
+      # ==== Example:
+      #
+      #   search = Sunspot.search(Post) do
+      #     facet :category_ids
+      #     dynamic :custom do
+      #       facet :cuisine
+      #     end
+      #     facet :age do
+      #       row 'Less than a month' do
+      #         with(:published_at).greater_than(1.month.ago)
+      #       end
+      #       row 'Less than a year' do
+      #         with(:published_at, 1.year.ago..1.month.ago)
+      #       end
+      #       row 'More than a year' do
+      #         with(:published_at).less_than(1.year.ago)
+      #       end
+      #     end
+      #   end
+      #   search.facet(:category_ids)
+      #     #=> Facet for :category_ids field
+      #   search.facet(:custom, :cuisine)
+      #     #=> Facet for the dynamic field :cuisine in the :custom field definition
+      #   search.facet(:age)
+      #     #=> Facet for the query facet named :age
+      #
+      def facet(name, dynamic_name = nil)
+        if name
+          if dynamic_name
+            @facets_by_name[:"#{name}:#{dynamic_name}"]
+          else
+            @facets_by_name[name.to_sym]
+          end
+        end
+      end
+  
+      # 
+      # Deprecated in favor of optional second argument to #facet
+      #
+      def dynamic_facet(base_name, dynamic_name) #:nodoc:
+        facet(base_name, dynamic_name)
+      end
+  
+      def facet_response #:nodoc:
+        @solr_result['facet_counts']
+      end
+  
+      # 
+      # Get the data accessor that will be used to load a particular class out of
+      # persistent storage. Data accessors can implement any methods that may be
+      # useful for refining how data is loaded out of storage. When building a
+      # search manually (e.g., using the Sunspot#new_search method), this should
+      # be used before calling #execute(). Use the
+      # Sunspot::DSL::Search#data_accessor_for method when building searches using
+      # the block DSL.
+      #
+      def data_accessor_for(clazz) #:nodoc:
+        (@data_accessors ||= {})[clazz.name.to_sym] ||=
+          Adapters::DataAccessor.create(clazz)
+      end
+  
+      # 
+      # Build this search using a DSL block. This method can be called more than
+      # once on an unexecuted search (e.g., Sunspot.new_search) in order to build
+      # a search incrementally.
+      #
+      # === Example
+      #
+      #   search = Sunspot.new_search(Post)
+      #   search.build do
+      #     with(:published_at).less_than Time.now
+      #   end
+      #   search.execute
+      #
+      def build(&block)
+        Util.instance_eval_or_call(dsl, &block)
+        self
+      end
+  
+      # 
+      # Populate the Hit objects with their instances. This is invoked the first
+      # time any hit has its instance requested, and all hits are loaded as a
+      # batch.
+      #
+      def populate_hits #:nodoc:
+        id_hit_hash = Hash.new { |h, k| h[k] = {} }
+        hits.each do |hit|
+          id_hit_hash[hit.class_name][hit.primary_key] = hit
+        end
+        id_hit_hash.each_pair do |class_name, hits|
+          ids = hits.map { |id, hit| hit.primary_key }
+          data_accessor = data_accessor_for(Util.full_const_get(class_name))
+          hits_for_class = id_hit_hash[class_name]
+          data_accessor.load_all(ids).each do |result|
+            hit = hits_for_class.delete(Adapters::InstanceAdapter.adapt(result).id.to_s)
+            hit.result = result
+          end
+          hits_for_class.values.each { |hit| hit.result = nil }
+        end
+      end
+  
+      def inspect #:nodoc:
+        "<Sunspot::Search:#{query.to_params.inspect}>"
+      end
+  
+      def add_field_facet(field, options = {}) #:nodoc:
+        name = (options[:name] || field.name)
+        add_facet(name, FieldFacet.new(field, self, options))
+      end
+  
+      def add_query_facet(name, options) #:nodoc:
+        add_facet(name, QueryFacet.new(name, self, options))
+      end
+  
+      def add_date_facet(field, options) #:nodoc:
+        name = (options[:name] || field.name)
+        add_facet(name, DateFacet.new(field, self, options))
+      end
+  
+      private
+  
+      def dsl
+        raise NotImplementedError 
+      end
+  
+      def execute_request(params)
+        raise NotImplementedError
+      end
+  
+      def solr_response
+        @solr_response ||= @solr_result['response'] || {}
+      end
+  
+      def highlights_for(doc)
+        if @solr_result['highlighting']
+          @solr_result['highlighting'][doc['id']]
+        end
+      end
+  
+      def distance_for(doc)
+        if @solr_result['distances']
+          @solr_result['distances'][doc['id']]
+        end
+      end
+  
+      def verified_hits
+        @verified_hits ||= maybe_will_paginate(hits.select { |hit| hit.instance })
+      end
+  
+      def maybe_will_paginate(collection)
+        if defined?(WillPaginate::Collection)
+          WillPaginate::Collection.create(@query.page, @query.per_page, total) do |pager|
+            pager.replace(collection)
+          end
+        else
+          collection
+        end
+      end
+  
+      def add_facet(name, facet)
+        @facets << facet
+        @facets_by_name[name.to_sym] = facet
+      end
+      
+      # Clear out all the cached ivars so the search can be called again.
+      def reset
+        @results = @hits = @verified_hits = @total = @solr_response = @doc_ids = nil
+      end
+    end
+  end
+end

data/lib/sunspot/search/date_facet.rb

@@ -1,5 +1,5 @@
 module Sunspot
-  class Search
+  module Search
     class DateFacet
       def initialize(field, search, options)
         @field, @search, @options = field, search, options