end
   query += ' ' + opts[:query] if opts[:query]
 
-  qobj, opts = Redwood::Index.parse_user_query_string query
-  query = Redwood::Index.build_query opts.merge(:qobj => qobj)
-
-  results = index.ferret.search query, :limit => :all
-  num_total = results.total_hits
+  docs = Redwood::Index.run_query query
+  num_total = docs.size
 
   $stderr.puts "Found #{num_total} documents across #{source_ids.length} sources. Scanning..."
 
   num_changed = num_scanned = 0
   last_info_time = start_time = Time.now
-  results.hits.each do |hit|
+  docs.each do |id|
     num_scanned += 1
-    id = hit.doc
 
     m = index.build_message id
     old_labels = m.labels.clone
 
     @index_mutex.synchronize { @index.search(q, :limit => 1).total_hits > 0 }
   end
 
+  ## takes a user query string and returns the list of docids for messages
+  ## that match the query.
+  ##
+  ## messages can then be loaded from the index with #build_message.
+  ##
+  ## raises a ParseError if the parsing failed.
+  def run_query query
+    qobj, opts = Redwood::Index.parse_user_query_string query
+    query = Redwood::Index.build_query opts.merge(:qobj => qobj)
+    results = @index.search query, :limit => (opts[:limit] || :all)
+    results.hits.map { |hit| hit.doc }
+  end
+
 protected
 
   class ParseError < StandardError; end