Skip to content
This repository


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Rails full text search plugin

tree: 478af88667

Fetching latest commit…

Cannot retrieve the latest commit at this time

= acts_as_ferret

This ActiveRecord mixin adds full text search capabilities to any Rails model.

It is heavily based on the original acts_as_ferret plugin done by
Kasper Weibel and a modified version done by Thomas Lockney, which 
both can be found on

== Project URLs

Please post issues on Lighthouse:
API docs:

== Supported Rails versions

From version 0.5 onwards acts_as_ferret requires Rails 3. For earlier Rails versions (2.3.x, ymmv for earlier versions)
please use acts_as_ferret versions 0.4.x or the rails-2.3.x branch on github.

== Installation

Aaf is available as a gem (gem install acts_as_ferret), or via git from
Github also offers tarball downloads, check out .

=== Rails 3


<tt>gem 'acts_as_ferret', '>= 0.5'</tt>

to your Gemfile. Bundler will pull in the jk-ferret gem as a dependency, which is an 'unofficial'
Ferret gem built by me based on Ferret's master branch on github (the latest official ferret gem is 0.11.6
and is missing quite some bug fixes that happened since then).

After running 'bundle install', have bundler execute the aaf_install script:

<tt>bundle exec aaf_install</tt>

This will copy the capistrano recipe, the ferret server config and it's startup script
into your project.

In order to have the capistrano recipe loaded you'll have to patch your Capfile a bit. I use to have
a line like that in my Capfiles, loading everything found below RAILS_ROOT/lib/recipes:

<tt>Dir['lib/recipes/**/*.rb'].each { |plugin| load(plugin) }</tt>

=== Rails 2.x

To set up your Rails project to use the acts_as_ferret gem, add this to your project's config/environment.rb:

<tt>config.gem 'acts_as_ferret', :version => '~> 0.4.8'</tt>

With the gem installed, change into your RAILS_ROOT and run the supplied aaf_install script.
This will copy rake tasks, capistrano recipes and the ferret server config and startup script
into your project.

If you're using Capistrano, patch your Capfile as described above for Rails 3.

=== Installation inside your Rails project via script/plugin

script/plugin install git://

No additional setup needed.

== Usage

There are two ways to make your models searchable with aaf. The option to configure acts_as_ferret with
a single configuration file has been introduced because it makes more sense when a single index holds multiple
models - it's simply more logicl to define that index and tell which models should go into it than to call
acts_as_ferret in each model pointing to the same index every time.

=== central configuration file

With this option, all acts_as_ferret indexes are configured in a single file, RAILS_ROOT/config/aaf.rb:

ActsAsFerret::define_index( 'my_index',
                            :models => {
                              SomeModel => {
                                :fields => {
                                  :name => { :boost => 4, :store => :yes, :via => :ferret_title },
                                  :foo => { :store => :no,  :index => :untokenized },
                                  :baz => { :store => :yes, :via => :ferret_content }
                            } )

ActsAsFerret::define_index( 'some_other_index',
                            :models => {
                              Foo => { :fields => { ... } },
                              Bar => { ... },
                            } )

As you can see for every index you want to define there's a single call, and each model that should go
into the index gets it's own ferret options hash (see the acts_as_ferret class method docs for all available options).

=== In your models (the old fashioned way)
include the following in your model class (specifiying the fields you want to get indexed):

<tt>acts_as_ferret :fields => [ :title, :description ]</tt>

now you can use ModelClass.find_with_ferret(query) to find instances of your model
whose indexed fields match a given query. All query terms are required by default, 
but explicit OR queries are possible. This differs from the ferret default, but 
imho is the more often needed/expected behaviour (more query terms result in 
less results).

Please see ActsAsFerret::ActMethods#acts_as_ferret for more information.

== Known issues

aaf is not yet ready for Rails3. Feel free to submit patches!

== License

Released under the MIT license.

== Authors

* Kasper Weibel Nielsen-Refs (original author)
* Jens Kraemer <> (current maintainer)

Something went wrong with that request. Please try again.