Ultrasphinx 

Ruby on Rails configurator and client to the Sphinx full text search engine.

== License

Copyright 2007-2008 Cloudburst, LLC. Licensed under the AFL 3. See the included LICENSE file. Some portions copyright 
Pat Allan, distributed under the MIT license, and used with permission. Some portions copyright PJ Hyett and Mislav 
Marohnić, distributed under the MIT license, and used with permission. 

The public certificate for the gem is 
here[http://rubyforge.org/frs/download.php/25331/evan_weaver-original-public_cert.pem]. 

If you use this software, please {make a donation}[http://blog.evanweaver.com/donate/], or {recommend 
Evan}[http://www.workingwithrails.com/person/7739-evan-weaver] at Working with Rails.

== Requirements

* MySQL 5.0, or PostgreSQL 8.2
* Sphinx 0.9.8-rc2
* Rails 2.0.2
* instead of Rails, Merb 0.9.3 is now supported

More recent versions than listed are usually ok.

== Features

Sphinx/Ultrasphinx is the fastest and most stable Rails fulltext search solution.

Features include:

* searching and ranking across multiple models
* delta index support
* excerpt highlighting
* Google-style query parser
* spellcheck
* faceting on text, date, and numeric fields
* field weighting, merging, and aliasing
* geodistance
* <tt>belongs_to</tt> and <tt>has_many</tt> includes
* drop-in compatibility with will_paginate[http://err.lighthouseapp.com/projects/466/home]
* drop-in compatibility with Interlock[http://blog.evanweaver.com/files/doc/fauna/interlock/]
* multiple deployment environments
* comprehensive Rake tasks

And some other things.

= Usage

== Installation
  
First, install Sphinx itself. Get the {0.9.8 snapshot}[http://www.sphinxsearch.com/downloads.html], then run 
<tt>./configure</tt>, <tt>make</tt>, and <tt>sudo make install</tt>. Make sure to set your <tt>./configure</tt> flags: 
<tt>----prefix</tt> if necessary, and also <tt>----with-pgsql</tt> if you need Postgres support.

You also need the <tt>chronic</tt> gem:
  sudo gem install chronic

Then, install the plugin:
  script/plugin install -x svn://rubyforge.org/var/svn/fauna/ultrasphinx/trunk
 
Next, copy the <tt>examples/default.base</tt> file to <tt>RAILS_ROOT/config/ultrasphinx/default.base</tt>. This file 
sets up the  Sphinx daemon options such as port, host, and index location.
  
If you need per-environment configuration, you can use <tt>RAILS_ROOT/config/ultrasphinx/development.base</tt>, etc. 
Note that ERb is also allowed within the <tt>.base</tt> files, and can be an alternative way to DRY up multiple 
configurations.

Now, in your models, use the <tt>is_indexed</tt> method to configure a model as searchable. For example:
  
  class Post
    is_indexed :fields => ['created_at', 'title', 'body']
  end
  
For more index options, see ActiveRecord::Base .is_indexed.

== Merb Installation

Install Sphinx as above.

Download the latest version of this code from git:
  git clone git://github.com/jamie/ultrasphinx.git

Build the gem:
  rake package

Install the gem into your merb application locally:
  gem install pkg/ultrasphinx-1.11.gem -i ~/projects/sample/gems

In config/init.rb, add these lines:
  require 'erb' # for Ultrasphinx
  require 'active_support' # for Ultrasphinx, mattr_accessor
  dependency 'ultrasphinx'

Finally, copy the example configuration file over, and configure as usual.

Merb support includes ORM support for both DataMapper >0.9.2 and
ActiveRecord >2.1.0, detected automatically.

All other usage and configuration is the same as for Rails.  As sphinx
interacts directly with the database, the actual technology used in an app
is less important than ensuring that the database and configuration file are
correct.

== Building the index

Now run:

  rake ultrasphinx:configure
  rake ultrasphinx:index
  rake ultrasphinx:daemon:start

To rotate the index, just rerun <tt>rake ultrasphinx:index</tt>. If the search daemon is running, it will have its index 
rotated live. Otherwise the new index will be installed but the daemon will remain stopped.

== Running queries
    
Query the daemon as so:

  @search = Ultrasphinx::Search.new(:query => @query)
  @search.run
  @search.results
  
For more query options, including excerpt mode, see Ultrasphinx::Search.
  
= Extras  

== Pagination

Once the <tt>@search</tt> object has been <tt>run</tt>, it is directly compatible with the <tt>will_paginate</tt> view 
helper. In your view, just do:
  <%= will_paginate(@search) %>
  
== Spell checking

See Ultrasphinx::Spell.

== Delta indexing 

Delta indexing speeds up your updates by not reindexing the entire dataset every time. 

First, in your <tt>.base</tt> file, set the indexer option <tt>delta</tt> to your maximum interval between full 
reindexes. A day or a week is good, depending. Add a little bit to account for the time it takes the actual index to 
run:

  delta = <%= 1.day + 30.minutes %> 

Now, configure your models for delta indexing in the <tt>is_indexed</tt> call:

  is_indexed :fields => ['created_at', 'title', 'body'],
    :delta => true

Now you can run <tt>rake ultrasphinx:index:delta</tt> frequently, and only records that were changed within 1 day will 
be reindexed. You will need to run <tt>rake ultrasphinx:index:main</tt> once a day to move the delta contents into the 
main index.

See ActiveRecord::Base .is_indexed and DEPLOYMENT_NOTES[link:files/DEPLOYMENT_NOTES.html] for more.
  
== Available Rake tasks

See RAKE_TASKS[link:files/RAKE_TASKS.html].

== Deployment notes

See DEPLOYMENT_NOTES[link:files/DEPLOYMENT_NOTES.html].

== Gotchas

Note that since Ultrasphinx preloads indexed models, you need to make sure those models have their own dependencies in 
place early in the boot process. This may require adjusting the general plugin load order or moving monkey-patches from 
<tt>lib/</tt> to <tt>vendor/plugins/</tt>.

PostgreSQL 8.2 and higher are well supported. However, make sure the stored procedure migration gets generated 
correctly. If you did not install the plugin via <tt>script/install</tt>, run <tt>script/generate 
ultrasphinx_migration</tt> by hand.

== Reporting problems

The support forum is here[http://rubyforge.org/forum/forum.php?forum_id=14244].

Patches and contributions are very welcome. Please note that contributors are required to assign copyright for their 
additions to Cloudburst, LLC. 

== Further resources

* http://sphinxsearch.com/doc.html
* http://sphinxsearch.com/forum/forum.html?id=1
* http://blog.evanweaver.com/articles/2007/07/09/ultrasphinx-searching-the-world-in-231-seconds