Skip to content


Subversion checkout URL

You can clone with
Download ZIP
High level Ruby library for interacting with Xapian, a full text search engine.
Branch: master
Failed to load latest commit information.
features add ability to limit results based on relevance
lib make reported total include relevance limit
spec make reported total include relevance limit
.autotest adding LocalDatabase wrapper so we can make a remote database wrapper
.gitignore upgrading to RSpec 2 and getting specs passing for the most part
.rspec initial implementation of a rack app server
.rvmrc switching to Ruby 1.9.2
Gemfile adding model adapter
LICENSE removing unused whitespace
README.rdoc renaming per to per_page
Rakefile removing unused code from previous version
xapit.gemspec bump version



Xapit (pronounced “zap it”) is a Ruby gem for doing full text searching through Xapian. This project was recently rewritten and is not yet ready for production. Please try it out and let me know if there are any issues.


First, install Xapian with the Ruby bindings. The easiest way is through Homebrew.

brew install xapian --ruby

Note: this is tied to the current version of Ruby you have installed. If you use RVM be certain you're in the correct version. See Installing Xapian for other methods.

Next add Xapit to your Gemfile and run the bundle command.

gem "xapit", "~> 0.3"

Then if you are in a Rails application, run the installation generator.

rails g xapit:install

This creates a configuration file and a rackup file for production use.


To make a model searchable you must define an index through the xapit method. Here is an example of the four methods you can call there.

class Article < ActiveRecord::Base
  xapit do
    text :name, :content
    field :category_id
    sortable :id, :created_at
    facet :author_name, "Author"

This indexes the model to be searched in a variety of ways (shown below). See the Indexing wiki page for details.

Currently only Active Record is supported, but expect support for other libraries soon.

The index will automatically be updated when records are added or removed. You can regenerate the index manually to fill it with any existing records.

rake xapit:index


Use the search class method to perform a full text search on the index. This returns a Xapit scope where additional scoping methods can be called similar to Active Record scopes.

# simple full text search
@articles ="phone")

# full text search with basic boolean matching
@articles ="phone OR fax NOT email")

# pagination works with kaminari and will_paginate
@articles ="phone").page(10).per_page(20)

# search based on a specific field
@articles ="phone").where(:category_id => params[:category_id])

# search for multiple negative conditions (doesn't match 3, 5, or 8)
@articles ="phone").not_where(:category_id => [3, 5, 8])

# search for range of conditions by number
@articles = =>

# order based on sortable fields, sorting defaults to most relevant
@articles ="phone").order(:created_at, :desc)

Simply iterate through the returned set to display the results.

<% for article in @articles %>
  <%= %>
<% end %>

See the Searching wiki page for more details.


Spelling suggestions are available when there is a simlarly indexed term.

<% if @articles.spelling_suggestion %>
  Did you mean <%= link_to @articles.spelling_suggestion, :overwrite_params => { :keywords => @articles.spelling_suggestion } %>?
<% end %>

Note: the spelling feature is disabled by default in the test environment because it uses an in-memory database.


Facets allow you to further filter the result set based on certain attributes.

<% for facet in @articles.facets %>
  <%= %>
  <% for option in facet.options %>
    <%= link_to, :overwrite_params => { :facets => option } %>
    (<%= option.count %>)
  <% end %>
<% end %>

The facet option is passed in through the URL which you can add to the search."phone").with_facets(params[:facets])

You can also list the applied facets along with a remove link.

<% for option in @articles.applied_facet_options %>
  <%= %>
  <%= link_to "remove", :overwrite_params => { :facets => option } %>
<% end %>


To use Xapit in the test environment, you will need to reload the configuration before each test. For example, you can do this in RSpec:

config.before(:each) do

Xapit is also disabled by default in the test environment so you can enable it on a per-test basis. This way it doesn't slow down tests which don't need Xapit search.

# create records and test searching functionality

If you have existing records in the database you want to search (maybe loaded by fixtures) you can index those.

Xapit.index(Article, Comment) # or whatever models you need

By default, the test environment keeps the Xapian database in memory which makes it much faster and easier to reset. The problem is that the spelling suggestion feature does not work with in-memory databases, so it is disabled in the test environment by default. All of this can be customized in the configuration file.


The default Xapit setup works well in development because there is only one instance of the Rails app running. However in production you will need to move Xapit to a separate process so all of the instances can communicate to it. To do this, start up the rackup file provided. You will likely want to put this behind a server such as Passenger.


Now when you start up your Rails app in production it will use this server. You can configure the server URL in the configuration file.

Bug Reports

First check out the troubleshooting section when you have problems. If you have found a bug or have a feature to request, please add it to the GitHub issue tracker if it is not there already. Feel free to treat it as a mailing list and discuss new ideas or bring up any confusion you may have.

Something went wrong with that request. Please try again.