Ultrasphinx
Ruby on Rails configurator and client to the Sphinx full text search engine.
License
Copyright 2007 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 at rubyforge.org/frs/download.php/25331/evan_weaver-original-public_cert.pem.
Requirements
-
MySQL (or Postgres, experimental)
-
Sphinx 0.9.8-dev r871 or greater
-
Rails 1.2.3 or greater
Features
Advanced Sphinx usage:
-
searching and ranking across orthogonal models
-
excerpt highlighting
-
field weighting
-
faceting on text, date, and numeric fields
ActiveRecord-style SQL generation:
-
belongs_to
andhas_many
includes -
field merging
-
field aliasing
Good Rails integration:
-
automatic memcached loads via
cache_fu
-
will_paginate
compatibility -
query spellcheck
-
Google-style query parser
-
error recovery
-
multiple deployment environments
-
comprehensive Rake tasks
And some other things.
Usage
Installation
First, install Sphinx itself. Get the 0.9.8 development snapshot (www.sphinxsearch.com), 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 example/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.
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.
Building the index
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. Otherwise the new index will be installed but the daemon will remain stopped.
Make sure to manually stop and restart the daemon if you change the field configuration or model set. It will not reload the configuration file automatically.
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 @search
object has been run
, it is directly compatible with the will_paginate
view helper.
Spell checking
See Ultrasphinx::Spell.
Available Rake tasks
These Rake tasks are made available to your Rails app:
ultrasphinx:configure
-
Rebuild the configuration file for this particular environment.
ultrasphinx:index
-
Reindex the database and send an update signal to the search daemon.
ultrasphinx:daemon:restart
-
Restart the search daemon.
ultrasphinx:daemon:start
-
Start the search daemon.
ultrasphinx:daemon:stop
-
Stop the search daemon.
ultrasphinx:daemon:status
-
Check if the search daemon is running.
ultrasphinx:spelling:build
-
Rebuild the custom spelling dictionary. You may need to use
sudo
if your Aspell folder is not writable by the app user. ultrasphinx:bootstrap
-
Bootstrap a full Sphinx environment by running configure, index, then daemon:start.
All tasks have shortcuts. Use us:conf
, us:in
, us:restart
, us:start
, us:stop
, us:stat
, us:spell
, and us:boot
.
Reporting problems
Patches and contributions are very welcome. Please note that contributors are required to assign copyright for their additions to Cloudburst, LLC.