A port of Ultrasphinx for Merb
Ruby
Switch branches/tags
Nothing to show
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
examples
lib
spec
vendor/riddle
DEPLOYMENT_NOTES
LICENSE
RAKE_TASKS
README
Rakefile
TODO
gitignore

README

Ultraminx (a Merb port of Ultrasphinx)

Merb 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. 

Merb port by Fabien Franzen <info@loobmedia.com>

== Requirements

* MySQL 5.0, or PostgreSQL 8.2
* Sphinx 0.9.8-rc1
* Merb 0.9.3

More recent versions than listed are usually ok.

== Features

Sphinx/Ultraminx is the fastest and most stable Merb fulltext search solution.

Features include:

* searching and ranking across orthogonal models
* delta index support
* excerpt highlighting
* Google-style query parser
* spellcheck
* faceting on text, date, and numeric fields
* field weighting, merging, and aliases
* <tt>belongs_to</tt> and <tt>has_many</tt> includes
* 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/ultraminx/trunk
 
Next, copy the <tt>examples/default.base</tt> file to <tt>[Merb.root]/config/ultraminx/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>[Merb.root]/config/ultraminx/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.

== Building the index

Now run:

  rake ultraminx:configure
  rake ultraminx:index
  rake ultraminx:daemon:start

To rotate the index, just rerun <tt>rake ultraminx: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 = Ultraminx::Search.new(:query => @query)
  @search.run
  @search.results
  
For more query options, including excerpt mode, see Ultraminx::Search.
  
= Extras  

== Spell checking

See Ultraminx::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 ultraminx:index:delta</tt> frequently, and only records that were changed within 1 day will be reindexed. You will need to run <tt>rake ultraminx: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

== Deployment notes

See DEPLOYMENT_NOTES

== Gotchas

Note that since Ultraminx 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 you have executed <tt>CREATE LANGUAGE plpgsql;</tt> at least once. This step does not need to be repeated, so depending on your DB permissions, you might be able to put it in a migration.

== 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