Ruby on Rails configurator and client to the Sphinx full text search engine
Ruby JavaScript
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
examples Hack on the token_stream_to_hash to account for searching for URL Feb 2, 2009
generators/ultrasphinx_migration
lib Url change Nov 15, 2011
tasks Changed rake tasks to work on windows Apr 28, 2009
test Added test to verify the filter exclude behaviour (should have included Nov 12, 2009
vendor Update to Sphinx rc2. Apr 16, 2008
CHANGELOG Update to Sphinx rc2. Apr 16, 2008
DEPLOYMENT_NOTES Remove extra asterisk in documentation (agile). Mar 11, 2008
LICENSE sphinx? did i hear a noise? May 8, 2007
Manifest
RAKE_TASKS Add merge rake task; add test and documentation for same; DRY up some… Mar 9, 2008
README.rdoc Deprecation Nov 15, 2011
Rakefile docs Feb 23, 2011
TODO Import 1.9 from private branch. Adds delta index support. Mar 8, 2008
init.rb Added additional require to fix occasional Missing Module error. Feb 2, 2009
install.rb Use a migration generator for installing Postgres stored procedures (… Mar 31, 2008

README.rdoc

Ultrasphinx

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

DEPRECATED

Please use Thinking Sphinx instead.

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.

Requirements

  • MySQL 5.0, or PostgreSQL 8.2

  • Sphinx 0.9.8-rc2

  • Rails 2.0.2

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

  • belongs_to and has_many includes

  • drop-in compatibility with will_paginate

  • drop-in compatibility with Interlock

  • multiple deployment environments

  • comprehensive Rake tasks

And some other things.

Usage

Installation

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 git://github.com/fauna/ultrasphinx.git

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.

Building the index

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.

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

Available Rake tasks

See RAKE_TASKS.

Deployment notes

See DEPLOYMENT_NOTES.

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

Reporting problems

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.

Further resources