acts_as_solr_reloaded 1.0.0

data/lib/acts_as_solr/acts_methods.rb

@@ -0,0 +1,363 @@
+module ActsAsSolr #:nodoc:
+
+  module ActsMethods
+
+    # declares a class as solr-searchable
+    #
+    # ==== options:
+    # fields:: This option can be used to specify only the fields you'd
+    #          like to index. If not given, all the attributes from the
+    #          class will be indexed. You can also use this option to
+    #          include methods that should be indexed as fields
+    #
+    #           class Movie < ActiveRecord::Base
+    #             acts_as_solr :fields => [:name, :description, :current_time]
+    #             def current_time
+    #               Time.now.to_s
+    #             end
+    #           end
+    #
+    #          Each field passed can also be a hash with the value being a field type
+    #
+    #           class Electronic < ActiveRecord::Base
+    #             acts_as_solr :fields => [{:price => :range_float}]
+    #             def current_time
+    #               Time.now
+    #             end
+    #           end
+    #
+    #          The field types accepted are:
+    #
+    #          :float:: Index the field value as a float (ie.: 12.87)
+    #          :integer:: Index the field value as an integer (ie.: 31)
+    #          :boolean:: Index the field value as a boolean (ie.: true/false)
+    #          :date:: Index the field value as a date (ie.: Wed Nov 15 23:13:03 PST 2006)
+    #          :string:: Index the field value as a text string, not applying the same indexing
+    #                    filters as a regular text field
+    #          :range_integer:: Index the field value for integer range queries (ie.:[5 TO 20])
+    #          :range_float:: Index the field value for float range queries (ie.:[14.56 TO 19.99])
+    #
+    #          Setting the field type preserves its original type when indexed
+    #
+    #          The field may also be passed with a hash value containing options
+    #
+    #          class Author < ActiveRecord::Base
+    #            acts_as_solr :fields => [{:full_name => {:type => :text, :as => :name}}]
+    #            def full_name
+    #              self.first_name + ' ' + self.last_name
+    #            end
+    #          end
+    #
+    #          The options accepted are:
+    #
+    #          :type:: Index the field using the specified type
+    #          :as:: Index the field using the specified field name
+    #
+    # additional_fields:: This option takes fields to be include in the index
+    #                     in addition to those derived from the database. You
+    #                     can also use this option to include custom fields
+    #                     derived from methods you define. This option will be
+    #                     ignored if the :fields option is given. It also accepts
+    #                     the same field types as the option above
+    #
+    #                      class Movie < ActiveRecord::Base
+    #                       acts_as_solr :additional_fields => [:current_time]
+    #                       def current_time
+    #                         Time.now.to_s
+    #                       end
+    #                      end
+    #
+    # exclude_fields:: This option taks an array of fields that should be ignored from indexing:
+    #
+    #                    class User < ActiveRecord::Base
+    #                      acts_as_solr :exclude_fields => [:password, :login, :credit_card_number]
+    #                    end
+    #
+    # include:: This option can be used for association indexing, which
+    #           means you can include any :has_one, :has_many, :belongs_to
+    #           and :has_and_belongs_to_many association to be indexed:
+    #
+    #            class Category < ActiveRecord::Base
+    #              has_many :books
+    #              acts_as_solr :include => [:books]
+    #            end
+    #
+    #           Each association may also be specified as a hash with an option hash as a value
+    #
+    #           class Book < ActiveRecord::Base
+    #             belongs_to :author
+    #             has_many :distribution_companies
+    #             has_many :copyright_dates
+    #             has_many :media_types
+    #             acts_as_solr(
+    #               :fields => [:name, :description],
+    #               :include => [
+    #                 {:author => {:using => :fullname, :as => :name}},
+    #                 {:media_types => {:using => lambda{|media| type_lookup(media.id)}}}
+    #                 {:distribution_companies => {:as => :distributor, :multivalued => true}},
+    #                 {:copyright_dates => {:as => :copyright, :type => :date}}
+    #               ]
+    #             ]
+    #
+    #           The options accepted are:
+    #
+    #           :type:: Index the associated objects using the specified type
+    #           :as:: Index the associated objects using the specified field name
+    #           :using:: Index the associated objects using the value returned by the specified method or proc.  If a method
+    #                    symbol is supplied, it will be sent to each object to look up the value to index; if a proc is
+    #                    supplied, it will be called once for each object with the object as the only argument
+    #           :multivalued:: Index the associated objects using one field for each object rather than joining them
+    #                          all into a single field
+    #
+    # facets:: This option can be used to specify the fields you'd like to
+    #          index as facet fields
+    #
+    #           class Electronic < ActiveRecord::Base
+    #             acts_as_solr :facets => [:category, :manufacturer]
+    #           end
+    #
+    # boost:: You can pass a boost (float) value that will be used to boost the document and/or a field. To specify a more
+    #         boost for the document, you can either pass a block or a symbol. The block will be called with the record
+    #         as an argument, a symbol will result in the according method being called:
+    #
+    #           class Electronic < ActiveRecord::Base
+    #             acts_as_solr :fields => [{:price => {:boost => 5.0}}], :boost => 10.0
+    #           end
+    #
+    #           class Electronic < ActiveRecord::Base
+    #             acts_as_solr :fields => [{:price => {:boost => 5.0}}], :boost => proc {|record| record.id + 120*37}
+    #           end
+    #
+    #           class Electronic < ActiveRecord::Base
+    #             acts_as_solr :fields => [{:price => {:boost => :price_rating}}], :boost => 10.0
+    #           end
+    #
+    # if:: Only indexes the record if the condition evaluated is true. The argument has to be
+    #      either a symbol, string (to be eval'ed), proc/method, or class implementing a static
+    #      validation method. It behaves the same way as ActiveRecord's :if option.
+    #
+    #        class Electronic < ActiveRecord::Base
+    #          acts_as_solr :if => proc{|record| record.is_active?}
+    #        end
+    #
+    # offline:: Assumes that your using an outside mechanism to explicitly trigger indexing records, e.g. you only
+    #           want to update your index through some asynchronous mechanism. Will accept either a boolean or a block
+    #           that will be evaluated before actually contacting the index for saving or destroying a document. Defaults
+    #           to false. It doesn't refer to the mechanism of an offline index in general, but just to get a centralized point
+    #           where you can control indexing. Note: This is only enabled for saving records. acts_as_solr doesn't always like
+    #           it, if you have a different number of results coming from the database and the index. This might be rectified in
+    #           another patch to support lazy loading.
+    #
+    #             class Electronic < ActiveRecord::Base
+    #               acts_as_solr :offline => proc {|record| record.automatic_indexing_disabled?}
+    #             end
+    #
+    # auto_commit:: The commit command will be sent to Solr only if its value is set to true:
+    #
+    #                 class Author < ActiveRecord::Base
+    #                   acts_as_solr :auto_commit => false
+    #                 end
+    #
+    # dynamic_attributes: Default false. When true, requires a has_many relationship to a DynamicAttribute
+    #                     (:name, :value) model. Then, all dynamic attributes will be mapped as normal attributes
+    #                    in Solr, so you can filter like this: Model.find_by_solr "#{dynamic_attribute.name}:Lorem"
+    # taggable: Default false. When true, indexes tags with field name tag. Tags are taken from taggings.tag
+    # spatial: Default false. When true, indexes model.local.latitude and model.local.longitude as coordinates.
+    def acts_as_solr(options={}, solr_options={}, &deferred_solr_configuration)
+
+      extend ClassMethods
+      include InstanceMethods
+      include CommonMethods
+      include ParserMethods
+
+      define_solr_configuration_methods
+
+      acts_as_taggable_on :tags if options[:taggable]
+      has_many :dynamic_attributes, :as => "dynamicable" if options[:dynamic_attributes]
+      has_one :local, :as => "localizable" if options[:spatial]
+
+      after_save    :solr_save
+      after_destroy :solr_destroy
+
+      if deferred_solr_configuration
+        self.deferred_solr_configuration = deferred_solr_configuration
+      else
+        process_acts_as_solr(options, solr_options)
+      end
+    end
+
+    def process_acts_as_solr(options, solr_options)
+      process_solr_options(options, solr_options)
+    end
+
+    def define_solr_configuration_methods
+      # I'd like to use cattr_accessor, but it does not support lazy loaders and delegation to the class in the instance methods.
+      # TODO: Reconcile with cattr_accessor, or a more appropriate method.
+      class_eval(<<-EOS, __FILE__, __LINE__)
+      @@configuration = nil unless defined?(@@configuration)
+      @@solr_configuration = nil unless defined?(@@solr_configuration)
+      @@deferred_solr_configuration = nil unless defined?(@@deferred_solr_configuration)
+
+      def self.configuration
+        return @@configuration if @@configuration
+        process_deferred_solr_configuration
+        @@configuration
+      end
+      def configuration
+        self.class.configuration
+      end
+      def self.configuration=(value)
+        @@configuration = value
+      end
+      def configuration=(value)
+        self.class.configuration = value
+      end
+
+      def self.solr_configuration
+        return @@solr_configuration if @@solr_configuration
+        process_deferred_solr_configuration
+        @@solr_configuration
+      end
+      def solr_configuration
+        self.class.solr_configuration
+      end
+      def self.solr_configuration=(value)
+        @@solr_configuration = value
+      end
+      def solr_configuration=(value)
+        self.class.solr_configuration = value
+      end
+
+      def self.deferred_solr_configuration
+        return @@deferred_solr_configuration if @@deferred_solr_configuration
+        @@deferred_solr_configuration
+      end
+      def deferred_solr_configuration
+        self.class.deferred_solr_configuration
+      end
+      def self.deferred_solr_configuration=(value)
+        @@deferred_solr_configuration = value
+      end
+      def deferred_solr_configuration=(value)
+        self.class.deferred_solr_configuration = value
+      end
+      EOS
+    end
+
+    def process_deferred_solr_configuration
+      return unless deferred_solr_configuration
+      options, solr_options = deferred_solr_configuration.call
+      self.deferred_solr_configuration = nil
+      self.process_solr_options(options, solr_options)
+    end
+
+    def process_solr_options(options={}, solr_options={})
+      self.configuration = {
+        :fields => nil,
+        :additional_fields => nil,
+        :dynamic_attributes => false,
+        :exclude_fields => [],
+        :auto_commit => true,
+        :include => nil,
+        :facets => nil,
+        :boost => nil,
+        :if => "true",
+        :offline => false,
+        :spatial => false
+      }
+      self.solr_configuration = {
+        :type_field => "type_s",
+        :primary_key_field => "pk_i",
+        :default_boost => 1.0
+      }
+
+      configuration.update(options) if options.is_a?(Hash)
+      solr_configuration.update(solr_options) if solr_options.is_a?(Hash)
+      Deprecation.validate_index(configuration)
+
+      configuration[:solr_fields] = {}
+      configuration[:solr_includes] = {}
+
+      if configuration[:fields].respond_to?(:each)
+        process_fields(configuration[:fields])
+      else
+        process_fields(self.new.attributes.keys.map { |k| k.to_sym })
+        process_fields(configuration[:additional_fields])
+      end
+
+      if configuration[:include].respond_to?(:each)
+        process_includes(configuration[:include])
+      end
+    end
+
+    private
+
+    def get_field_value(field)
+      field_name, options = determine_field_name_and_options(field)
+      configuration[:solr_fields][field_name] = options
+
+      define_method("#{field_name}_for_solr".to_sym) do
+        begin
+          value = self[field_name] || self.instance_variable_get("@#{field_name.to_s}".to_sym) || self.send(field_name.to_sym)
+          case options[:type]
+            # format dates properly; return nil for nil dates
+            when :date
+              value ? (value.respond_to?(:utc) ? value.utc : value).strftime("%Y-%m-%dT%H:%M:%SZ") : nil
+            else value
+          end
+        rescue
+          puts $!
+          logger.debug "There was a problem getting the value for the field '#{field_name}': #{$!}"
+          value = ''
+        end
+      end
+    end
+
+    def process_fields(raw_field)
+      if raw_field.respond_to?(:each)
+        raw_field.each do |field|
+          next if configuration[:exclude_fields].include?(field)
+          get_field_value(field)
+        end
+      end
+    end
+
+    def process_includes(includes)
+      if includes.respond_to?(:each)
+        includes.each do |assoc|
+          field_name, options = determine_field_name_and_options(assoc)
+          configuration[:solr_includes][field_name] = options
+        end
+      end
+    end
+
+    def determine_field_name_and_options(field)
+      if field.is_a?(Hash)
+        name = field.keys.first
+        options = field.values.first
+        if options.is_a?(Hash)
+          [name, {:type => type_for_field(field)}.merge(options)]
+        else
+          [name, {:type => options}]
+        end
+      else
+        [field, {:type => type_for_field(field)}]
+      end
+    end
+
+    def type_for_field(field)
+      if configuration[:facets] && configuration[:facets].include?(field)
+        :facet
+      elsif column = columns_hash[field.to_s]
+        case column.type
+        when :string then :text
+        when :datetime then :date
+        when :time then :date
+        else column.type
+        end
+      else
+        :text
+      end
+    end
+  end
+end

data/lib/acts_as_solr/class_methods.rb

@@ -0,0 +1,240 @@
+module ActsAsSolr #:nodoc:
+
+  module ClassMethods
+    include CommonMethods
+    include ParserMethods
+    
+    # Finds instances of a model. Terms are ANDed by default, can be overwritten 
+    # by using OR between terms
+    # 
+    # Here's a sample (untested) code for your controller:
+    # 
+    #  def search
+    #    results = Book.find_by_solr params[:query]
+    #  end
+    # 
+    # You can also search for specific fields by searching for 'field:value'
+    # 
+    # ====options:
+    # offset:: - The first document to be retrieved (offset)
+    # limit:: - The number of rows per page
+    # order:: - Orders (sort by) the result set using a given criteria:
+    #
+    #             Book.find_by_solr 'ruby', :order => 'description asc'
+    # 
+    # field_types:: This option is deprecated and will be obsolete by version 1.0.
+    #               There's no need to specify the :field_types anymore when doing a 
+    #               search in a model that specifies a field type for a field. The field 
+    #               types are automatically traced back when they're included.
+    # 
+    #                 class Electronic < ActiveRecord::Base
+    #                   acts_as_solr :fields => [{:price => :range_float}]
+    #                 end
+    # 
+    # facets:: This option argument accepts the following arguments:
+    #          fields:: The fields to be included in the faceted search (Solr's facet.field)
+    #          query:: The queries to be included in the faceted search (Solr's facet.query)
+    #          zeros:: Display facets with count of zero. (true|false)
+    #          sort:: Sorts the faceted resuls by highest to lowest count. (true|false)
+    #          browse:: This is where the 'drill-down' of the facets work. Accepts an array of
+    #                   fields in the format "facet_field:term"
+    #          mincount:: Replacement for zeros (it has been deprecated in Solr). Specifies the
+    #                     minimum count necessary for a facet field to be returned. (Solr's
+    #                     facet.mincount) Overrides :zeros if it is specified. Default is 0.
+    #
+    #          dates:: Run date faceted queries using the following arguments:
+    #            fields:: The fields to be included in the faceted date search (Solr's facet.date).
+    #                     It may be either a String/Symbol or Hash. If it's a hash the options are the
+    #                     same as date_facets minus the fields option (i.e., :start:, :end, :gap, :other,
+    #                     :between). These options if provided will override the base options.
+    #                     (Solr's f.<field_name>.date.<key>=<value>).
+    #            start:: The lower bound for the first date range for all Date Faceting. Required if
+    #                    :fields is present
+    #            end:: The upper bound for the last date range for all Date Faceting. Required if
+    #                  :fields is prsent
+    #            gap:: The size of each date range expressed as an interval to be added to the lower
+    #                  bound using the DateMathParser syntax.  Required if :fields is prsent
+    #            hardend:: A Boolean parameter instructing Solr what do do in the event that
+    #                      facet.date.gap does not divide evenly between facet.date.start and facet.date.end.
+    #            other:: This param indicates that in addition to the counts for each date range
+    #                    constraint between facet.date.start and facet.date.end, other counds should be
+    #                    calculated. May specify more then one in an Array. The possible options are:
+    #              before:: - all records with lower bound less than start
+    #              after:: - all records with upper bound greater than end
+    #              between:: - all records with field values between start and end
+    #              none:: - compute no other bounds (useful in per field assignment)
+    #              all:: - shortcut for before, after, and between
+    #            filter:: Similar to :query option provided by :facets, in that accepts an array of
+    #                     of date queries to limit results. Can not be used as a part of a :field hash.
+    #                     This is the only option that can be used if :fields is not present.
+    # 
+    # Example:
+    # 
+    #   Electronic.find_by_solr "memory", :facets => {:zeros => false, :sort => true,
+    #                                                 :query => ["price:[* TO 200]",
+    #                                                            "price:[200 TO 500]",
+    #                                                            "price:[500 TO *]"],
+    #                                                 :fields => [:category, :manufacturer],
+    #                                                 :browse => ["category:Memory","manufacturer:Someone"]}
+    # 
+    #
+    # Examples of date faceting:
+    #
+    #  basic:
+    #    Electronic.find_by_solr "memory", :facets => {:dates => {:fields => [:updated_at, :created_at],
+    #      :start => 'NOW-10YEARS/DAY', :end => 'NOW/DAY', :gap => '+2YEARS', :other => :before}}
+    #
+    #  advanced:
+    #    Electronic.find_by_solr "memory", :facets => {:dates => {:fields => [:updated_at,
+    #    {:created_at => {:start => 'NOW-20YEARS/DAY', :end => 'NOW-10YEARS/DAY', :other => [:before, :after]}
+    #    }], :start => 'NOW-10YEARS/DAY', :end => 'NOW/DAY', :other => :before, :filter =>
+    #    ["created_at:[NOW-10YEARS/DAY TO NOW/DAY]", "updated_at:[NOW-1YEAR/DAY TO NOW/DAY]"]}}
+    #
+    #  filter only:
+    #    Electronic.find_by_solr "memory", :facets => {:dates => {:filter => "updated_at:[NOW-1YEAR/DAY TO NOW/DAY]"}}
+    #
+    #
+    #
+    # scores:: If set to true this will return the score as a 'solr_score' attribute
+    #          for each one of the instances found. Does not currently work with find_id_by_solr
+    # 
+    #            books = Book.find_by_solr 'ruby OR splinter', :scores => true
+    #            books.records.first.solr_score
+    #            => 1.21321397
+    #            books.records.last.solr_score
+    #            => 0.12321548
+    # 
+    # lazy:: If set to true the search will return objects that will touch the database when you ask for one
+    #        of their attributes for the first time. Useful when you're using fragment caching based solely on
+    #        types and ids.
+    #
+    # relevance:: Sets fields relevance
+    #
+    #            Book.find_by_solr "zidane", :relevance => {:title => 5, :author => 2}
+    #
+    def find_by_solr(query, options={})
+      data = parse_query(query, options)
+      return parse_results(data, options)
+    end
+    alias :search :find_by_solr
+    
+    # Finds instances of a model and returns an array with the ids:
+    #  Book.find_id_by_solr "rails" => [1,4,7]
+    # The options accepted are the same as find_by_solr
+    # 
+    def find_id_by_solr(query, options={})
+      data = parse_query(query, options)
+      return parse_results(data, {:format => :ids})
+    end
+    
+    # This method can be used to execute a search across multiple models:
+    #   Book.multi_solr_search "Napoleon OR Tom", :models => [Movie]
+    # 
+    # ====options:
+    # Accepts the same options as find_by_solr plus:
+    # models:: The additional models you'd like to include in the search
+    # results_format:: Specify the format of the results found
+    #                  :objects :: Will return an array with the results being objects (default). Example:
+    #                               Book.multi_solr_search "Napoleon OR Tom", :models => [Movie], :results_format => :objects
+    #                  :ids :: Will return an array with the ids of each entry found. Example:
+    #                           Book.multi_solr_search "Napoleon OR Tom", :models => [Movie], :results_format => :ids
+    #                           => [{"id" => "Movie:1"},{"id" => Book:1}]
+    #                          Where the value of each array is as Model:instance_id
+    # scores:: If set to true this will return the score as a 'solr_score' attribute
+    #          for each one of the instances found. Does not currently work with find_id_by_solr
+    # 
+    #            books = Book.multi_solr_search 'ruby OR splinter', :scores => true
+    #            books.records.first.solr_score
+    #            => 1.21321397
+    #            books.records.last.solr_score
+    #            => 0.12321548
+    # 
+    def multi_solr_search(query, options = {})
+      models = multi_model_suffix(options)
+      options.update(:results_format => :objects) unless options[:results_format]
+      data = parse_query(query, options, models)
+      
+      if data.nil? or data.total_hits == 0
+        return SearchResults.new(:docs => [], :total => 0)
+      end
+
+      result = find_multi_search_objects(data, options)
+      if options[:scores] and options[:results_format] == :objects
+        add_scores(result, data) 
+      end
+      SearchResults.new :docs => result, :total => data.total_hits
+    end
+
+    def find_multi_search_objects(data, options)
+      result = []
+      if options[:results_format] == :objects
+        data.hits.each do |doc| 
+          k = doc.fetch('id').first.to_s.split(':')
+          result << k[0].constantize.find_by_id(k[1])
+        end
+      elsif options[:results_format] == :ids
+        data.hits.each{|doc| result << {"id" => doc["id"].to_s}}
+      end
+      result
+    end
+    
+    def multi_model_suffix(options)
+      models = "AND (#{solr_configuration[:type_field]}:#{self.name}"
+      models << " OR " + options[:models].collect {|m| "#{solr_configuration[:type_field]}:" + m.to_s}.join(" OR ") if options[:models].is_a?(Array)
+      models << ")"
+    end
+    
+    # returns the total number of documents found in the query specified:
+    #  Book.count_by_solr 'rails' => 3
+    # 
+    def count_by_solr(query, options = {})        
+      data = parse_query(query, options)
+      data.total_hits
+    end
+            
+    # It's used to rebuild the Solr index for a specific model. 
+    #  Book.rebuild_solr_index
+    # 
+    # If batch_size is greater than 0, adds will be done in batches.
+    # NOTE: If using sqlserver, be sure to use a finder with an explicit order.
+    # Non-edge versions of rails do not handle pagination correctly for sqlserver
+    # without an order clause.
+    # 
+    # If a finder block is given, it will be called to retrieve the items to index.
+    # This can be very useful for things such as updating based on conditions or
+    # using eager loading for indexed associations.
+    def rebuild_solr_index(batch_size=0, &finder)
+      finder ||= lambda { |ar, options| ar.find(:all, options.merge({:order => self.primary_key})) }
+      start_time = Time.now
+
+      if batch_size > 0
+        items_processed = 0
+        limit = batch_size
+        offset = 0
+        begin
+          iteration_start = Time.now
+          items = finder.call(self, {:limit => limit, :offset => offset})
+          add_batch = items.collect { |content| content.to_solr_doc }
+    
+          if items.size > 0
+            solr_add add_batch
+            solr_commit
+          end
+    
+          items_processed += items.size
+          last_id = items.last.id if items.last
+          time_so_far = Time.now - start_time
+          iteration_time = Time.now - iteration_start         
+          logger.info "#{Process.pid}: #{items_processed} items for #{self.name} have been batch added to index in #{'%.3f' % time_so_far}s at #{'%.3f' % (items_processed / time_so_far)} items/sec (#{'%.3f' % (items.size / iteration_time)} items/sec for the last batch). Last id: #{last_id}"
+          offset += items.size
+        end while items.nil? || items.size > 0
+      else
+        items = finder.call(self, {})
+        items.each { |content| content.solr_save }
+        items_processed = items.size
+      end
+      solr_optimize
+      logger.info items_processed > 0 ? "Index for #{self.name} has been rebuilt" : "Nothing to index for #{self.name}"
+    end
+  end
+end