benjaminkrause-sunspot 0.9.7

data/lib/sunspot/query.rb

@@ -0,0 +1,108 @@
+%w(base_query fulltext_base_query scope field_query connective dynamic_query
+   field_facet query_facet query_facet_row query_field_facet boost_query local
+   pagination restriction sort sort_composite text_field_boost
+   highlighting).each do |file|
+  require File.join(File.dirname(__FILE__), 'query', file)
+end
+
+module Sunspot
+  module Query #:nodoc:
+    # 
+    # 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. It can also be accessed directly by calling
+    # #query on a Search object (presumably a not-yet-run one created using
+    # Sunspot#new_search), which might be more suitable than the DSL when an
+    # intermediate object has responsibility for building the query dynamically.
+    #--
+    # 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 < FieldQuery #:nodoc:
+      attr_reader :query_facets #:nodoc:
+
+      def initialize(types, setup, configuration) #:nodoc:
+        super(setup)
+        @query_facets = {}
+        @components[0] = @base_query = BaseQuery.new(types, setup)
+        @components << @pagination = Pagination.new(configuration)
+        @components << @sort = SortComposite.new
+      end
+
+      #
+      # 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) #:nodoc:
+        @pagination.page, @pagination.per_page = page, per_page
+      end
+
+      def add_location_restriction(coordinates, miles) #:nodoc:
+        @components << Local.new(coordinates, miles)
+      end
+
+      def add_text_fields_scope
+        @components << scope = Scope.new(TextFieldSetup.new(@setup))
+        scope
+      end
+
+      # 
+      # Page that this query will return (used by Sunspot::Search to expose
+      # pagination)
+      #
+      # ==== Returns
+      #
+      # Integer:: Page number
+      #
+      def page #:nodoc:
+        @pagination.page
+      end
+
+      #
+      # 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 #:nodoc:
+        @pagination.per_page
+      end
+
+      # 
+      # Get the query facet with the given name. Used by the Search object to
+      # match query facet results with the requested query facets.
+      #
+      def query_facet(name) #:nodoc:
+        @query_facets[name.to_sym]
+      end
+
+      # 
+      # Add a Sort object into this query's sort composite.
+      #
+      def add_sort(sort) #:nodoc:
+        @sort << sort
+      end
+
+      # 
+      # Set the keywords for this query, along with keyword options. See
+      # Query::FulltextBaseQuery for information on what the options do. Returns
+      # a FulltextBaseQuery object.
+      #
+      def set_keywords(keywords, options = {}) #:nodoc:
+        if keywords.to_s =~ /\S/
+          @components[0] = @base_query =
+            FulltextBaseQuery.new(keywords, options, @base_query.types, @setup)
+        end
+      end
+    end
+  end
+end

data/lib/sunspot/schema.rb

@@ -0,0 +1,147 @@
+require 'erb'
+
+module Sunspot
+  # 
+  # Object that encapsulates schema information for building a Solr schema.xml
+  # file. This class is used by the schema:compile task as well as the
+  # sunspot-configure-solr executable.
+  #
+  class Schema #:nodoc:all
+    FieldType = Struct.new(:name, :class_name, :suffix)
+    FieldVariant = Struct.new(:attribute, :suffix)
+
+    DEFAULT_TOKENIZER = 'solr.StandardTokenizerFactory'
+    DEFAULT_FILTERS = %w(solr.StandardFilterFactory solr.LowerCaseFilterFactory)
+
+    FIELD_TYPES = [
+      FieldType.new('boolean', 'Bool', 'b'),
+      FieldType.new('sfloat', 'SortableFloat', 'f'),
+      FieldType.new('date', 'Date', 'd'),
+      FieldType.new('sint', 'SortableInt', 'i'),
+      FieldType.new('string', 'Str', 's'),
+      FieldType.new('sdouble', 'SortableDouble', 'e'),
+      FieldType.new('slong', 'SortableLong', 'l')
+    ]
+
+    FIELD_VARIANTS = [
+      FieldVariant.new('multiValued', 'm'),
+      FieldVariant.new('stored', 's')
+    ]
+
+    attr_reader :tokenizer, :filters
+
+    def initialize
+      @tokenizer = DEFAULT_TOKENIZER
+      @filters = DEFAULT_FILTERS.dup
+    end
+
+    # 
+    # Attribute field types defined in the schema
+    #
+    def types
+      FIELD_TYPES
+    end
+
+    # 
+    # DynamicField instances representing all the available types and variants
+    #
+    def dynamic_fields
+      fields = []
+      for field_variants in variant_combinations
+        for type in FIELD_TYPES
+          fields << DynamicField.new(type, field_variants)
+        end
+      end
+      fields
+    end
+
+    # 
+    # Which tokenizer to use for text fields
+    #
+    def tokenizer=(tokenizer)
+      @tokenizer = 
+        if tokenizer =~ /\./
+          tokenizer
+        else
+          "solr.#{tokenizer}TokenizerFactory"
+        end
+    end
+
+    # 
+    # Add a filter for text field tokenization
+    #
+    def add_filter(filter)
+      @filters <<
+        if filter =~ /\./
+          filter
+        else
+          "solr.#{filter}FilterFactory"
+        end
+    end
+
+    # 
+    # Return an XML representation of this schema using the ERB template
+    #
+    def to_xml
+      template = File.join(File.dirname(__FILE__), '..', '..', 'templates', 'schema.xml.erb')
+      ERB.new(File.read(template), nil, '-').result(binding)
+    end
+
+    private
+
+    #
+    # All of the possible combinations of variants
+    #
+    def variant_combinations
+      combinations = []
+      0.upto(2 ** FIELD_VARIANTS.length - 1) do |b|
+        combinations << combination = []
+        FIELD_VARIANTS.each_with_index do |variant, i|
+          combination << variant if b & 1<<i > 0
+        end
+      end
+      combinations
+    end
+
+    # 
+    # Represents a dynamic field (in the Solr schema sense, not the Sunspot
+    # sense).
+    #
+    class DynamicField
+      def initialize(type, field_variants)
+        @type, @field_variants = type, field_variants
+      end
+
+      # 
+      # Name of the field in the schema
+      #
+      def name
+        variant_suffixes = @field_variants.map { |variant| variant.suffix }.join
+        "*_#{@type.suffix}#{variant_suffixes}"
+      end
+
+      # 
+      # Name of the type as defined in the schema
+      #
+      def type
+        @type.name
+      end
+
+      # 
+      # Implement magic methods to ask if a field is of a particular variant.
+      # Returns "true" if the field is of that variant and "false" otherwise.
+      #
+      def method_missing(name, *args, &block)
+        if name.to_s =~ /\?$/ && args.empty?
+          if @field_variants.any? { |variant| "#{variant.attribute}?" == name.to_s }
+            'true'
+          else
+            'false'
+          end
+        else
+          super(name.to_sym, *args, &block)
+        end
+      end
+    end
+  end
+end

data/lib/sunspot/search/highlight.rb

@@ -0,0 +1,38 @@
+module Sunspot
+  class Search
+    # 
+    # A Highlight represents a single highlighted fragment of text from a
+    # document. Depending on the highlighting parameters used for search, there
+    # may be more than one Highlight object for a given field in a given result.
+    #
+    class Highlight
+      HIGHLIGHT_MATCHER = /@@@hl@@@(.*?)@@@endhl@@@/ #:nodoc:
+      
+      #
+      # The name of the field in which the highlight appeared.
+      #
+      attr_reader :field_name
+            
+      def initialize(field_name, highlight) #:nodoc:
+        @field_name = field_name.to_sym
+        @highlight = highlight.to_s.strip
+      end
+      
+      #
+      # Returns the highlighted text with formatting according to the template given in &block.
+      # When no block is given, <em> and </em> are used to surround the highlight.
+      #
+      # ==== Example
+      #
+      #   search.highlights(:body).first.format { |word| "<strong>#{word}</strong>" }
+      #
+      def format(&block)
+        block ||= proc { |word| "<em>#{word}</em>" }
+        @highlight.gsub(HIGHLIGHT_MATCHER) do
+          block.call(Regexp.last_match[1])
+        end
+      end
+      alias_method :formatted, :format
+    end
+  end
+end

data/lib/sunspot/search/hit.rb

@@ -0,0 +1,113 @@
+module Sunspot
+  class Search
+    # 
+    # Hit objects represent the raw information returned by Solr for a single
+    # document. As well as the primary key and class name, hit objects give
+    # access to stored field values, keyword relevance score, and geographical
+    # distance (for geographical search).
+    #
+    class Hit
+      SPECIAL_KEYS = Set.new(%w(id type score)) #:nodoc:
+
+      # 
+      # Primary key of object associated with this hit, as string.
+      #
+      attr_reader :primary_key
+      # 
+      # Class name of object associated with this hit, as string.
+      #
+      attr_reader :class_name
+      # 
+      # Keyword relevance score associated with this result. Nil if this hit
+      # is not from a keyword search.
+      #
+      attr_reader :score
+      #
+      # For geographical searches, this is the distance between the search
+      # centerpoint and the document's location. Otherwise, it's nil.
+      # 
+      attr_reader :distance
+
+      attr_writer :instance #:nodoc:
+
+      def initialize(raw_hit, highlights, search) #:nodoc:
+        @class_name, @primary_key = *raw_hit['id'].match(/([^ ]+) (.+)/)[1..2]
+        @score = raw_hit['score']
+        @distance = raw_hit['geo_distance'].to_f if raw_hit['geo_distance']
+        @search = search
+        @stored_values = raw_hit
+        @stored_cache = {}
+        @highlights = highlights
+      end
+      
+      #
+      # Returns all highlights for this hit when called without parameters.
+      # When a field_name is provided, returns only the highlight for this field.
+      #
+      def highlights(field_name = nil)
+        if field_name.nil?
+          highlights_cache.values.flatten 
+        else
+          highlights_cache[field_name.to_sym]
+        end
+      end
+
+      # 
+      # Retrieve stored field value. For any attribute field configured with
+      # :stored => true, the Hit object will contain the stored value for
+      # that field. The value of this field will be typecast according to the
+      # type of the field.
+      #
+      # ==== Parameters
+      #
+      # field_name<Symbol>::
+      #   The name of the field for which to retrieve the stored value.
+      #
+      def stored(field_name)
+        @stored_cache[field_name.to_sym] ||=
+          begin
+            field = setup.field(field_name)
+            field.cast(@stored_values[field.indexed_name])
+          end
+      end
+
+      # 
+      # Retrieve the instance associated with this hit. This is lazy-loaded, but
+      # the first time it is called on any hit, all the hits for the search will
+      # load their instances using the adapter's #load_all method.
+      #
+      def instance
+        if @instance.nil?
+          @search.populate_hits!
+        end
+        @instance
+      end
+
+      def inspect #:nodoc:
+        "#<Sunspot::Search::Hit:#{@class_name} #{@primary_key}>"
+      end
+
+      private
+
+      def setup
+        @setup ||= Sunspot::Setup.for(@class_name)
+      end
+
+      def highlights_cache
+        @highlights_cache ||=
+          begin
+            cache = {}
+            if @highlights
+              @highlights.each_pair do |indexed_field_name, highlight_strings|
+                field_name = indexed_field_name.sub(/_[a-z]+$/, '').to_sym
+                cache[field_name] = highlight_strings.map do |highlight_string|
+                  Highlight.new(field_name, highlight_string)
+                end
+              end
+            end
+            cache
+          end
+      end
+    end
+  end
+end

data/lib/sunspot/search.rb

@@ -0,0 +1,240 @@
+%w(hit highlight).each do |file|
+  require File.join(File.dirname(__FILE__), 'search', file)
+end
+
+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 and
+  # Sunspot.new_search methods.
+  #
+  class Search
+    # Query information for this search. If you wish to build the query without
+    # using the search DSL, this method allows you to access the query API
+    # directly. See Sunspot#new_search for how to construct the search object
+    # in this case.
+    attr_reader :query 
+
+    def initialize(connection, setup, query) #:nodoc:
+      @connection, @setup, @query = connection, setup, query
+    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
+      params = @query.to_params
+      @solr_result = @connection.select(params)
+      self
+    end
+    alias_method :execute!, :execute #:nodoc: deprecated
+
+    # 
+    # 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, total) do |pager|
+          pager.replace(hits.map { |hit| hit.instance })
+        end
+      else
+        hits.map { |hit| hit.instance }
+      end
+    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.
+    #
+    # ==== Returns
+    #
+    # Array:: Ordered collection of Hit objects
+    #
+    def hits
+      @hits ||= solr_response['docs'].map { |doc| Hit.new(doc, highlights_for(doc), self) }
+    end
+    alias_method :raw_results, :hits
+
+    # 
+    # The total number of documents matching the query parameters
+    #
+    # ==== Returns
+    #
+    # Integer:: Total matching documents
+    #
+    def total
+      @total ||= solr_response['numFound']
+    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.
+    #
+    def facet(name)
+      (@facets_cache ||= {})[name.to_sym] ||=
+        begin
+          facet_data = query_facet_data(name) ||
+            begin
+              field = field(name)
+              date_facet_data(field) ||
+                FacetData::FieldFacetData.new(@solr_result['facet_counts']['facet_fields'][field.indexed_name], field)
+            end
+          facet_class = facet_data.reference ? InstantiatedFacet : Facet
+          facet_class.new(facet_data)
+        end
+    end
+
+    # 
+    # Get the facet object for a given dynamic field. This dynamic field will
+    # need to have been requested as a field facet inside the search block.
+    #
+    # ==== Parameters
+    #
+    # base_name<Symbol>::
+    #   Base name of the dynamic field definiton (as specified in the setup
+    #   block)
+    # dynamic_name<Symbol>::
+    #   Dynamic field name to facet on
+    # 
+    # ==== Returns
+    #
+    # Sunspot::Facet:: Facet object for given dynamic field
+    # 
+    # ==== Example
+    #
+    #   search = Sunspot.search(Post) do
+    #     dynamic :custom do
+    #       facet :cuisine
+    #     end
+    #   end
+    #   search.dynamic_facet(:custom, :cuisine)
+    #     #=> Facet for the dynamic field :cuisine in the :custom field definition
+    # 
+    def dynamic_facet(base_name, dynamic_name)
+      (@dynamic_facets_cache ||= {})[[base_name.to_sym, dynamic_name.to_sym]] ||=
+        begin
+          field = @setup.dynamic_field_factory(base_name).build(dynamic_name)
+          Facet.new(FacetData::FieldFacetData.new(@solr_result['facet_counts']['facet_fields'][field.indexed_name], field))
+        end
+    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_for(Util.full_const_get(class_name)).load_all(ids).each do |instance|
+          hit = id_hit_hash[class_name][Adapters::InstanceAdapter.adapt(instance).id.to_s]
+          hit.instance = instance
+        end
+      end
+    end
+
+    def inspect #:nodoc:
+      "<Sunspot::Search:#{query.to_params.inspect}>"
+    end
+
+    private
+
+    def solr_response
+      @solr_response ||= @solr_result['response']
+    end
+
+    def doc_ids
+      @doc_ids ||= solr_response['docs'].map { |doc| doc['id'] }
+    end
+
+    def dsl
+      DSL::Search.new(self)
+    end
+
+    def raw_facet(field)
+      if field.type == Type::TimeType
+        @solr_result['facet_counts']['facet_dates'][field.indexed_name]
+      end || @solr_result['facet_counts']['facet_fields'][field.indexed_name]
+    end
+
+    def date_facet_data(field)
+      if field.type == Type::TimeType
+        if @solr_result['facet_counts'].has_key?('facet_dates')
+          if facet_result = @solr_result['facet_counts']['facet_dates'][field.indexed_name]
+            FacetData::DateFacetData.new(facet_result, field)
+          end
+        end
+      end
+    end
+
+    def query_facet_data(name)
+      if query_facet = @query.query_facet(name.to_sym)
+        if @solr_result['facet_counts'].has_key?('facet_queries')
+            FacetData::QueryFacetData.new(
+              query_facet,
+              @solr_result['facet_counts']['facet_queries']
+            )
+        end
+      end
+    end
+
+    def highlights_for(doc)
+      if @solr_result['highlighting']
+        @solr_result['highlighting'][doc['id']]
+      end
+    end
+
+    def field(name)
+      @setup.field(name)
+    end
+  end
+end