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 and has_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.

Further resources