Eric Hodel <[email protected]>


File bugs:


Sphincter was named by David Yeu.


Sphincter is an ActiveRecord extension for full-text searching with Sphinx.

Sphincter uses Dmytro Shteflyuk's sphinx Ruby API and automatic
configuration to make totally rad ActiveRecord searching. Well, you
still have to tell Sphincter what models you want to search. It
doesn't read your mind.

For complete documentation:

ri Sphincter


* Automatically configures itself.
* Handy set of rake tasks for easy, automatic management.
* Automatically adds has_many metadata for searching across the
* Stub for testing without connecting to searchd, Sphincter::SearchStub.
* Easy pagination support.
* Filtering by index metadata and ranges, including dates.


* Setting match mode not supported.
* Setting sort mode not supported.
* Setting per-field weights not supported.
* Setting id range not supported.
* Setting group-by not supported.


Download and install Sphinx from http://www.sphinxsearch.com/downloads.html

Install Sphincter:

$ gem install Sphincter

Load Sphincter tasks in Rakefile:

require 'sphincter/tasks'

Setup the Dmytro Shteflyuk's Sphinx client:

$ rake sphincter:setup_sphinx

Add vendor/plugins/sphinx to your SCM system.

Load Sphincter in config/environment.rb:

require 'sphincter'

Add indexes to models:

class Post < ActiveRecord::Base
belongs_to :blog
add_index :fields => %w[title body published]

Add searching UI:

class BlogController < ApplicationController
def search
@blog = Blog.find params[:id]

@results = @blog.posts.search params[:q]

<% @results.records.each do |post| -%>
<div><%= link_to post.title, post_path(post) %></div>
<div><%= truncate post.body, 250 %></div>
<% end -%>

Start searchd:

$ rake sphincter:start_searchd

Then test it out in your browser.

NOTE: By default, Sphincter will run searchd on the same port for all
environments. See Sphincter::Configure for how to configure different
environments to use different ports.


See Sphinx::SearchStub.


See Sphincter::Search#search for full documentation.

Example ActiveRecord model:

class Post < ActiveRecord::Base
belongs_to :blog
belongs_to :user

# published is a boolean and title and body are string or text fields
# user.name is automatically fetched via the user association
add_index :fields => %w[title body published]

Simple search:

Post.search 'words'

Only search published posts:

Post.search 'words', :conditions => { :published => 1 }

Only search posts created in the last week:

now = Time.now
ago = now - 1.weeks
Post.search 'words', :between => { :created_on => [ago, now] }

Pagination (defaults to ten records/page):

Post.search 'words', :page => 2

Pagination with custom page size:

Post.search 'words', :page => 2, :per_page => 20

Pagination with custom page size (better):

Add to config/sphincter.yml:

per_page: 20

Then search:

Post.search 'words', :page => 2