Path: | README |
Last Update: | Thu Mar 12 18:41:09 -0700 2009 |
Ruby on Rails configurator and client to the Sphinx full text search engine.
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.
If you use this software, please make a donation, or recommend Evan at Working with Rails.
More recent versions than listed are usually ok.
Sphinx/Ultrasphinx is the fastest and most stable Rails fulltext search solution.
Features include:
And some other things.
First, install Sphinx itself. Get the 0.9.8 snapshot, then run ./configure, make, and sudo make install. Make sure to set your ./configure flags: —-prefix if necessary, and also —-with-pgsql if you need Postgres support.
You also need the chronic gem:
sudo gem install chronic
Then, install the plugin:
script/plugin install -x svn://rubyforge.org/var/svn/fauna/ultrasphinx/trunk
Next, copy the examples/default.base file to RAILS_ROOT/config/ultrasphinx/default.base. This file sets up the Sphinx daemon options such as port, host, and index location.
If you need per-environment configuration, you can use RAILS_ROOT/config/ultrasphinx/development.base, etc. Note that ERb is also allowed within the .base files, and can be an alternative way to DRY up multiple configurations.
Now, in your models, use the is_indexed 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.
Now run:
rake ultrasphinx:configure rake ultrasphinx:index rake ultrasphinx:daemon:start
To rotate the index, just rerun rake ultrasphinx:index. 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.
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.
Once the @search object has been run, it is directly compatible with the will_paginate view helper. In your view, just do:
<%= will_paginate(@search) %>
See Ultrasphinx::Spell.
Delta indexing speeds up your updates by not reindexing the entire dataset every time.
First, in your .base file, set the indexer option delta 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 is_indexed call:
is_indexed :fields => ['created_at', 'title', 'body'], :delta => true
Now you can run rake ultrasphinx:index:delta frequently, and only records that were changed within 1 day will be reindexed. You will need to run rake ultrasphinx:index:main once a day to move the delta contents into the main index.
See ActiveRecord::Base .is_indexed and DEPLOYMENT_NOTES for more.
See RAKE_TASKS.
See DEPLOYMENT_NOTES.
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 lib/ to vendor/plugins/.
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 script/install, run script/generate ultrasphinx_migration by hand.
The support forum is here.
Patches and contributions are very welcome. Please note that contributors are required to assign copyright for their additions to Cloudburst, LLC.