acts_as_ferret 0.4.1 → 0.4.2

data/README

@@ -22,6 +22,9 @@ project's config/environment.rb:
 
 <tt>require 'acts_as_ferret'</tt>
 
+Call the aaf_install script inside your project directory to install the sample
+config file and the drb server start/stop script.
+
 
 == Usage
 

data/bin/aaf_install

@@ -0,0 +1,23 @@
+# acts_as_ferret gem install script
+# Use inside the root of your Rails project
+require 'fileutils'
+
+@basedir = File.join(File.dirname(__FILE__), '..')
+
+def install(dir, file, executable=false)
+  puts "Installing: #{file}"
+  target = File.join('.', dir, file)
+  if File.exists?(target)
+    puts "#{target} already exists, skipping"
+  else
+    FileUtils.cp File.join(@basedir, dir, file), target
+    FileUtils.chmod 0755, target if executable
+  end
+end
+
+
+install 'script', 'ferret_server', true
+install 'config', 'ferret_server.yml'
+
+puts IO.read(File.join(@basedir, 'README'))
+

data/config/ferret_server.yml

@@ -1,12 +1,23 @@
+# configuration for the acts_as_ferret DRb server
+# host: where to reach the DRb server (used by application processes to contact the server)
+# port: which port the server should listen on
+# pid_file: location of the server's pid file (relative to RAILS_ROOT)
+# log_file: log file (default: RAILS_ROOT/log/ferret_server.log
+# log_level: log level for the server's logger
 production:
-  host: ferret.yourdomain.com
-  port: 9010
-  pid_file: log/ferret.pid
-development:
   host: localhost
   port: 9010
   pid_file: log/ferret.pid
-test:
-  host: localhost
-  port: 9009
-  pid_file: log/ferret.pid
+  log_file: log/ferret_server.log
+  log_level: warn
+
+# aaf won't try to use the DRb server in environments that are not 
+# configured here.
+#development:
+#  host: localhost
+#  port: 9010
+#  pid_file: log/ferret.pid
+#test:
+#  host: localhost
+#  port: 9009
+#  pid_file: log/ferret.pid

data/doc/README.win32

@@ -0,0 +1,23 @@
+Credits
+=======
+
+The Win32 service support scripts have been written by
+Herryanto Siatono <herryanto@pluitsolutions.com>. 
+
+See his accompanying blog posting at
+http://www.pluitsolutions.com/2007/07/30/acts-as-ferret-drbserver-win32-service/
+
+
+Usage
+=====
+
+There are two scripts:
+
+script/ferret_service is used to install/remove/start/stop the win32 service.
+
+script/ferret_daemon is to be called by Win32 service to start/stop the
+DRbServer.
+
+Run 'ruby script/ferret_service -h' for more info.
+
+

data/doc/monit-example

@@ -0,0 +1,22 @@
+# monit configuration snippet to watch the Ferret DRb server shipped with
+# acts_as_ferret
+check process ferret with pidfile /path/to/ferret.pid
+
+    # username is the user the drb server should be running as (It's good practice
+    # to run such services as a non-privileged user)
+    start program = "/bin/su -c 'cd /path/to/your/app/current/ && script/ferret_server -e production start' username"
+    stop program = "/bin/su -c 'cd /path/to/your/app/current/ && script/ferret_server -e production stop' username"
+
+    # cpu usage boundaries
+    if cpu > 60% for 2 cycles then alert
+    if cpu > 90% for 5 cycles then restart
+
+    # memory usage varies with index size and usage scenarios, so check how
+    # much memory your DRb server uses up usually and add some spare to that
+    # before enabling this rule:
+    # if totalmem > 50.0 MB for 5 cycles then restart
+
+    # adjust port numbers according to your setup:
+    if failed port 9010 then alert
+    if failed port 9010 for 2 cycles then restart
+    group ferret

data/install.rb

@@ -11,8 +11,7 @@ def install(file)
   end
 end
 
-install File.join( 'script', 'ferret_start' )
-install File.join( 'script', 'ferret_stop' )
+install File.join( 'script', 'ferret_server' )
 install File.join( 'config', 'ferret_server.yml' )
 
 puts IO.read(File.join(File.dirname(__FILE__), 'README'))

data/lib/act_methods.rb

@@ -38,6 +38,9 @@ module ActsAsFerret #:nodoc:
     #                    named class_name
     #
     # reindex_batch_size:: reindexing is done in batches of this size, default is 1000
+    # mysql_fast_batches:: set this to false to disable the faster mysql batching
+    #                      algorithm if this model uses a non-integer primary key named
+    #                      'id' on MySQL.
     #
     # ferret:: Hash of Options that directly influence the way the Ferret engine works. You 
     #          can use most of the options the Ferret::I class accepts here, too. Among the 
@@ -63,6 +66,8 @@ module ActsAsFerret #:nodoc:
     # For downwards compatibility reasons you can also specify the Ferret options in the 
     # last Hash argument.
     def acts_as_ferret(options={}, ferret_options={})
+      # default to DRb mode
+      options[:remote] = true if options[:remote].nil?
 
       # force local mode if running *inside* the Ferret server - somewhere the
       # real indexing has to be done after all :-)
@@ -71,14 +76,14 @@ module ActsAsFerret #:nodoc:
       # DRb server is started, so this code is executed too early and detection won't 
       # work. In this case you'll get endless loops resulting in "stack level too deep" 
       # errors. 
-      # To get around this, start the server with the environment variable 
+      # To get around this, start the DRb server with the environment variable 
       # FERRET_USE_LOCAL_INDEX set to '1'.
       logger.debug "Asked for a remote server ? #{options[:remote].inspect}, ENV[\"FERRET_USE_LOCAL_INDEX\"] is #{ENV["FERRET_USE_LOCAL_INDEX"].inspect}, looks like we are#{ActsAsFerret::Remote::Server.running || ENV['FERRET_USE_LOCAL_INDEX'] ? '' : ' not'} the server"
       options.delete(:remote) if ENV["FERRET_USE_LOCAL_INDEX"] || ActsAsFerret::Remote::Server.running
 
       if options[:remote] && options[:remote] !~ /^druby/
         # read server location from config/ferret_server.yml
-        options[:remote] = ActsAsFerret::Remote::Config.load("#{RAILS_ROOT}/config/ferret_server.yml")[:uri] rescue nil
+        options[:remote] = ActsAsFerret::Remote::Config.new.uri rescue nil
       end
 
       if options[:remote]
@@ -110,7 +115,9 @@ module ActsAsFerret #:nodoc:
         :single_index => false,
         :reindex_batch_size => 1000,
         :ferret => {},                    # Ferret config Hash
-        :ferret_fields => {}              # list of indexed fields that will be filled later
+        :ferret_fields => {},             # list of indexed fields that will be filled later
+        :enabled => true,                 # used for class-wide disabling of Ferret
+        :mysql_fast_batches => true       # turn off to disable the faster, id based batching mechanism for MySQL
       }
 
       # merge aaf options with args
@@ -206,6 +213,10 @@ module ActsAsFerret #:nodoc:
     # helper that defines a method that adds the given field to a ferret 
     # document instance
     def define_to_field_method(field, options = {})
+      if options[:boost].is_a?(Symbol)
+        dynamic_boost = options[:boost]
+        options.delete :boost
+      end
       options.reverse_merge!( :store       => :no, 
                               :highlight   => :yes, 
                               :index       => :yes, 
@@ -213,9 +224,10 @@ module ActsAsFerret #:nodoc:
                               :boost       => 1.0 )
       options[:term_vector] = :no if options[:index] == :no
       aaf_configuration[:ferret_fields][field] = options
+
       define_method("#{field}_to_ferret".to_sym) do
         begin
-          val = content_for_field_name(field)
+          val = content_for_field_name(field, dynamic_boost)
         rescue
           logger.warn("Error retrieving value for field #{field}: #{$!}")
           val = ''

data/lib/acts_as_ferret.rb

@@ -21,10 +21,13 @@
 require 'active_support'
 require 'active_record'
 require 'set'
+require 'enumerator'
 require 'ferret'
 
+require 'bulk_indexer'
 require 'ferret_extensions'
 require 'act_methods'
+require 'search_results'
 require 'class_methods'
 require 'shared_index_class_methods'
 require 'ferret_result'
@@ -66,32 +69,18 @@ require 'ferret_server'
 #
 module ActsAsFerret
 
-    # global Hash containing all multi indexes created by all classes using the plugin
-    # key is the concatenation of alphabetically sorted names of the classes the
-    # searcher searches.
-    @@multi_indexes = Hash.new
-    def self.multi_indexes; @@multi_indexes end
+  # global Hash containing all multi indexes created by all classes using the plugin
+  # key is the concatenation of alphabetically sorted names of the classes the
+  # searcher searches.
+  @@multi_indexes = Hash.new
+  def self.multi_indexes; @@multi_indexes end
 
-    # global Hash containing the ferret indexes of all classes using the plugin
-    # key is the index directory.
-    @@ferret_indexes = Hash.new
-    def self.ferret_indexes; @@ferret_indexes end
+  # global Hash containing the ferret indexes of all classes using the plugin
+  # key is the index directory.
+  @@ferret_indexes = Hash.new
+  def self.ferret_indexes; @@ferret_indexes end
 
  
-  # decorator that adds a total_hits accessor to search result arrays
-  class SearchResults
-    attr_reader :total_hits
-    def initialize(results, total_hits)
-      @results = results
-      @total_hits = total_hits
-    end
-    def method_missing(symbol, *args, &block)
-      @results.send(symbol, *args, &block)
-    end
-    def respond_to?(name)
-      self.methods.include?(name) || @results.respond_to?(name)
-    end
-  end
   
   def self.ensure_directory(dir)
     FileUtils.mkdir_p dir unless (File.directory?(dir) || File.symlink?(dir))
@@ -133,6 +122,8 @@ module ActsAsFerret
       end
     end
     fields.each_pair do |field, options|
+      options = options.dup
+      options.delete(:boost) if options[:boost].is_a?(Symbol)
       fi.add_field(field, { :store => :no, 
                             :index => :yes }.update(options)) 
     end

data/lib/bulk_indexer.rb

@@ -0,0 +1,35 @@
+module ActsAsFerret
+  class BulkIndexer
+    def initialize(args = {})
+      @batch_size = args[:batch_size] || 1000
+      @logger = args[:logger]
+      @model = args[:model]
+      @work_done = 0
+      @index = args[:index]
+      if args[:reindex]
+        @reindex = true
+        @model_count  = @model.count.to_f
+      else
+        @model_count = args[:total]
+      end
+    end
+
+    def index_records(records, offset)
+      batch_time = measure_time {
+        records.each { |rec| @index << rec.to_doc if rec.ferret_enabled?(true) }
+      }.to_f
+      @work_done = offset.to_f / @model_count * 100.0 if @model_count > 0
+      remaining_time = ( batch_time / @batch_size ) * ( @model_count - offset + @batch_size )
+      @logger.info "#{@reindex ? 're' : 'bulk '}index model #{@model.name} : #{'%.2f' % @work_done}% complete : #{'%.2f' % remaining_time} secs to finish"
+
+    end
+
+    def measure_time
+      t1 = Time.now
+      yield
+      Time.now - t1
+    end
+
+  end
+
+end

data/lib/class_methods.rb

@@ -2,6 +2,24 @@ module ActsAsFerret
         
   module ClassMethods
 
+    # Disables ferret index updates for this model. When a block is given,
+    # Ferret will be re-enabled again after executing the block.
+    def disable_ferret
+      aaf_configuration[:enabled] = false
+      if block_given?
+        yield
+        enable_ferret
+      end
+    end
+
+    def enable_ferret
+      aaf_configuration[:enabled] = true
+    end
+
+    def ferret_enabled?
+      aaf_configuration[:enabled]
+    end
+
     # rebuild the index from all data stored for this model.
     # This is called automatically when no index exists yet.
     #
@@ -16,13 +34,34 @@ module ActsAsFerret
       index_dir = find_last_index_version(aaf_configuration[:index_base_dir]) unless aaf_configuration[:remote]
     end
 
+    # re-index a number records specified by the given ids. Use for large
+    # indexing jobs i.e. after modifying a lot of records with Ferret disabled.
+    # Please note that the state of Ferret (enabled or disabled at class or
+    # record level) is not checked by this method, so if you need to do so
+    # (e.g. because of a custom ferret_enabled? implementation), you have to do
+    # so yourself.
+    def bulk_index(*ids)
+      options = Hash === ids.last ? ids.pop : {}
+      ids = ids.first if ids.size == 1 && ids.first.is_a?(Enumerable)
+      aaf_index.bulk_index(ids, options)
+    end
+
+    # true if our db and table appear to be suitable for the mysql fast batch
+    # hack (see
+    # http://weblog.jamisbuck.org/2007/4/6/faking-cursors-in-activerecord)
+    def use_fast_batches?
+      if connection.class.name =~ /Mysql/ && primary_key == 'id' && aaf_configuration[:mysql_fast_batches]
+        logger.info "using mysql specific batched find :all. Turn off with  :mysql_fast_batches => false if you encounter problems (i.e. because of non-integer UUIDs in the id column)"
+        true
+      end
+    end
+
     # runs across all records yielding those to be indexed when the index is rebuilt
     def records_for_rebuild(batch_size = 1000)
       transaction do
-        if connection.class.name =~ /Mysql/ && primary_key == 'id'
-          logger.info "using mysql specific batched find :all"
+        if use_fast_batches?
           offset = 0
-          while (rows = find :all, :conditions => ["id > ?", offset ], :limit => batch_size).any?
+          while (rows = find :all, :conditions => [ "#{table_name}.id > ?", offset ], :limit => batch_size).any?
             offset = rows.last.id
             yield rows, offset
           end
@@ -36,6 +75,21 @@ module ActsAsFerret
       end
     end
 
+    # yields the records with the given ids, in batches of batch_size
+    def records_for_bulk_index(ids, batch_size = 1000)
+      transaction do
+        offset = 0
+        ids.each_slice(batch_size) do |id_slice|
+          logger.debug "########## slice: #{id_slice.join(',')}"
+          records = find( :all, :conditions => ["id in (?)", id_slice] )
+          logger.debug "########## slice records: #{records.inspect}"
+          #yield records, offset
+          yield find( :all, :conditions => ["id in (?)", id_slice] ), offset
+          offset += batch_size
+        end
+      end
+    end
+
     # Switches this class to a new index located in dir.
     # Used by the DRb server when switching to a new index version.
     def index_dir=(dir)
@@ -59,7 +113,15 @@ module ActsAsFerret
     # OR between terms for ORed queries. Or specify +:or_default => true+ in the
     # +:ferret+ options hash of acts_as_ferret.
     #
+    # You may either use the +offset+ and +limit+ options to implement your own
+    # pagination logic, or use the +page+ and +per_page+ options to use the
+    # built in pagination support which is compatible with will_paginate's view
+    # helpers. If +page+ and +per_page+ are given, +offset+ and +limit+ will be
+    # ignored.
+    #
     # == options:
+    # page::        page of search results to retrieve
+    # per_page::    number of search results that are displayed per page
     # offset::      first hit to retrieve (useful for paging)
     # limit::       number of hits to retrieve, or :all to retrieve
     #               all results
@@ -71,6 +133,10 @@ module ActsAsFerret
     #               work here)
     # models::      only for single_index scenarios: an Array of other Model classes to 
     #               include in this search. Use :all to query all models.
+    # multi::       Specify additional model classes to search through. Each of
+    #               these, as well as this class, has to have the
+    #               :store_class_name option set to true. This option replaces the
+    #               multi_search method.
     #
     # +find_options+ is a hash passed on to active_record's find when
     # retrieving the data from db, useful to i.e. prefetch relationships with
@@ -78,25 +144,69 @@ module ActsAsFerret
     #
     # This method returns a +SearchResults+ instance, which really is an Array that has 
     # been decorated with a total_hits attribute holding the total number of hits.
+    # Additionally, SearchResults is compatible with the pagination helper
+    # methods of the will_paginate plugin.
     #
-    # Please keep in mind that the number of total hits might be wrong if you specify 
-    # both ferret options and active record find_options that somehow limit the result 
-    # set (e.g. +:num_docs+ and some +:conditions+).
+    # Please keep in mind that the number of results delivered might be less than 
+    # +limit+ if you specify any active record conditions that further limit 
+    # the result. Use +limit+ and +offset+ as AR find_options instead.
+    # +page+ and +per_page+ are supposed to work regardless of any 
+    # +conitions+ present in +find_options+.
     def find_with_ferret(q, options = {}, find_options = {})
-      total_hits, result = find_records_lazy_or_not q, options, find_options
+      if options[:per_page]
+        options[:page] = options[:page] ? options[:page].to_i : 1
+        limit = options[:per_page]
+        offset = (options[:page] - 1) * limit
+        if find_options[:conditions] && !options[:multi]
+          find_options[:limit] = limit
+          find_options[:offset] = offset
+          options[:limit] = :all
+          options.delete :offset
+        else
+          # do pagination with ferret (or after everything is done in the case
+          # of multi_search)
+          options[:limit] = limit
+          options[:offset] = offset
+        end
+      elsif find_options[:conditions]
+        if options[:multi]
+          # multisearch ignores find_options limit and offset
+          options[:limit] ||= find_options.delete(:limit)
+          options[:offset] ||= find_options.delete(:offset)
+        else
+          # let the db do the limiting and offsetting for single-table searches
+          find_options[:limit] ||= options.delete(:limit)
+          find_options[:offset] ||= options.delete(:offset)
+          options[:limit] = :all
+        end
+      end
+
+      total_hits, result = if options[:multi].blank?
+        find_records_lazy_or_not q, options, find_options
+      else
+        _multi_search q, options.delete(:multi), options, find_options
+      end
       logger.debug "Query: #{q}\ntotal hits: #{total_hits}, results delivered: #{result.size}"
-      return SearchResults.new(result, total_hits)
+      SearchResults.new(result, total_hits, options[:page], options[:per_page])
     end 
     alias find_by_contents find_with_ferret
 
    
 
     # Returns the total number of hits for the given query 
-    # To count the results of a multi_search query, specify an array of 
-    # class names with the :models option.
+    # To count the results of a query across multiple models, specify an array of 
+    # class names with the :multi option.
+    #
+    # Note that since we don't query the database here, this method won't deliver 
+    # the expected results when used on an AR association.
     def total_hits(q, options={})
-      if models = options[:models]
-        options[:models] = add_self_to_model_list_if_necessary(models).map(&:to_s)
+      if options[:models]
+        # backwards compatibility
+        logger.warn "the :models option of total_hits is deprecated, please use :multi instead"
+        options[:multi] = options[:models] 
+      end
+      if models = options[:multi]
+        options[:multi] = add_self_to_model_list_if_necessary(models).map(&:to_s)
       end
       aaf_index.total_hits(q, options)
     end
@@ -120,9 +230,22 @@ module ActsAsFerret
       aaf_index.find_id_by_contents(q, options, &block)
     end
 
-    # requires the store_class_name option of acts_as_ferret to be true
-    # for all models queried this way.
-    def multi_search(query, additional_models = [], options = {}, find_options = {})
+    
+    # returns an array of hashes, each containing :class_name,
+    # :id and :score for a hit.
+    #
+    # if a block is given, class_name, id and score of each hit will 
+    # be yielded, and the total number of hits is returned.
+    def id_multi_search(query, additional_models = [], options = {}, &proc)
+      deprecated_options_support(options)
+      models = add_self_to_model_list_if_necessary(additional_models)
+      aaf_index.id_multi_search(query, models.map(&:to_s), options, &proc)
+    end
+    
+
+    protected
+
+    def _multi_search(query, additional_models = [], options = {}, find_options = {})
       result = []
 
       if options[:lazy]
@@ -133,33 +256,28 @@ module ActsAsFerret
       else
         id_arrays = {}
         rank = 0
+
+        limit = options.delete(:limit)
+        offset = options.delete(:offset) || 0
+        options[:limit] = :all
         total_hits = id_multi_search(query, additional_models, options) do |model, id, score, data|
           id_arrays[model] ||= {}
           id_arrays[model][id] = [ rank += 1, score ]
         end
         result = retrieve_records(id_arrays, find_options)
+        total_hits = result.size if find_options[:conditions]
+ #       total_hits += offset if offset
+        if limit && limit != :all
+          result = result[offset..limit+offset-1]
+        end
       end
-
-      SearchResults.new(result, total_hits)
+      [total_hits, result]
     end
-    
-    # returns an array of hashes, each containing :class_name,
-    # :id and :score for a hit.
-    #
-    # if a block is given, class_name, id and score of each hit will 
-    # be yielded, and the total number of hits is returned.
-    def id_multi_search(query, additional_models = [], options = {}, &proc)
-      deprecated_options_support(options)
-      additional_models = add_self_to_model_list_if_necessary(additional_models)
-      aaf_index.id_multi_search(query, additional_models.map(&:to_s), options, &proc)
-    end
-    
-
-    protected
 
     def add_self_to_model_list_if_necessary(models)
       models = [ models ] unless models.is_a? Array
       models << self unless models.include?(self)
+      models
     end
 
     def find_records_lazy_or_not(q, options = {}, find_options = {})
@@ -174,23 +292,30 @@ module ActsAsFerret
     def ar_find_by_contents(q, options = {}, find_options = {})
       result_ids = {}
       total_hits = find_id_by_contents(q, options) do |model, id, score, data|
-        # stores ids, index of each id for later ordering of
-        # results, and score
+        # stores ids, index and score of each hit for later ordering of
+        # results
         result_ids[id] = [ result_ids.size + 1, score ]
       end
 
       result = retrieve_records( { self.name => result_ids }, find_options )
       
-      if find_options[:conditions]
-        if options[:limit] != :all
-          # correct result size if the user specified conditions
-          #  wenn conditions: options[:limit] != :all --> ferret-query mit :all wiederholen und select count machen
+      # count total_hits via sql when using conditions or when we're called
+      # from an ActiveRecord association.
+      if find_options[:conditions] or caller.find{ |call| call =~ %r{active_record/associations} }
+        # chances are the ferret result count is not our total_hits value, so
+        # we correct this here.
+        if options[:limit] != :all || options[:page] || options[:offset] || find_options[:limit] || find_options[:offset]
+          # our ferret result has been limited, so we need to re-run that
+          # search to get the full result set from ferret.
           result_ids = {}
-          find_id_by_contents(q, options.update(:limit => :all)) do |model, id, score, data|
+          find_id_by_contents(q, options.update(:limit => :all, :offset => 0)) do |model, id, score, data|
             result_ids[id] = [ result_ids.size + 1, score ]
           end
+          # Now ask the database for the total size of the final result set.
           total_hits = count_records( { self.name => result_ids }, find_options )
         else
+          # what we got from the database is our full result set, so take
+          # it's size
           total_hits = result.length
         end
       end
@@ -240,22 +365,24 @@ module ActsAsFerret
           raise "Please use ':store_class_name => true' if you want to use multi_search.\n#{$!}"
         end
 
+        # merge conditions
+        conditions = combine_conditions([ "#{model.table_name}.#{model.primary_key} in (?)", 
+                                          id_array.keys ], 
+                                        find_options[:conditions])
+
         # check for include association that might only exist on some models in case of multi_search
         filtered_include_options = []
         if include_options = find_options[:include]
+          include_options = [ include_options ] unless include_options.respond_to?(:each)
           include_options.each do |include_option|
             filtered_include_options << include_option if model.reflections.has_key?(include_option.is_a?(Hash) ? include_option.keys[0].to_sym : include_option.to_sym)
           end
         end
-        filtered_include_options=nil if filtered_include_options.empty?
+        filtered_include_options = nil if filtered_include_options.empty?
 
         # fetch
-        tmp_result = nil
-        model.send(:with_scope, :find => find_options) do 
-          tmp_result = model.find( :all, :conditions => [ 
-            "#{model.table_name}.#{model.primary_key} in (?)", id_array.keys ],  
-            :include => filtered_include_options ) 
-        end
+        tmp_result = model.find(:all, find_options.merge(:conditions => conditions, 
+                                                         :include => filtered_include_options))
 
         # set scores and rank
         tmp_result.each do |record|
@@ -272,15 +399,20 @@ module ActsAsFerret
     end
 
     def count_records(id_arrays, find_options = {})
+      count_options = find_options.dup
+      count_options.delete :limit
+      count_options.delete :offset
       count = 0
       id_arrays.each do |model, id_array|
         next if id_array.empty?
         begin
           model = model.constantize
-          model.send(:with_scope, :find => find_options) do 
-            count += model.count(:conditions => [ "#{model.table_name}.#{model.primary_key} in (?)",
-                                                  id_array.keys ]) 
-          end
+          # merge conditions
+          conditions = combine_conditions([ "#{model.table_name}.#{model.primary_key} in (?)", id_array.keys ], 
+                                          find_options[:conditions])
+          opts = find_options.merge :conditions => conditions
+          opts.delete :limit; opts.delete :offset
+          count += model.count opts
         rescue TypeError
           raise "#{model} must use :store_class_name option if you want to use multi_search against it.\n#{$!}"
         end
@@ -310,6 +442,17 @@ module ActsAsFerret
       end.new(aaf_configuration)
     end
 
+    # combine our conditions with those given by user, if any
+    def combine_conditions(conditions, additional_conditions = [])
+      returning conditions do
+        if additional_conditions && additional_conditions.any?
+          cust_opts = additional_conditions.respond_to?(:shift) ? additional_conditions.dup : [ additional_conditions ]
+          conditions.first << " and " << cust_opts.shift
+          conditions.concat(cust_opts)
+        end
+      end
+    end
+
   end
   
 end