acts_as_ferret plugin for Ruby on Rails

About

This is the home of the acts_as_ferret plugin for Ruby on Rails.

Acts_as_ferret is a plugin for Ruby on Rails which makes it simple to implement full text search for Rails. It builds on Ferret which is a ruby port of Apache Lucene. It is a technology suitable for nearly any application that requires full-text search. For more information about Ferret, visit its website, search the mailing list at ruby-forum.com or (very recommended) buy the book.

If you have any questions please ask them on the Ferret mailing list (ferret-talk@rubyforge.org) or via ruby-forum.com: http://www.ruby-forum.com/forum/5

RDoc-generated API documentation is available for the current trunk and the latest stable release.

Features

• High speed full text search across the contents of any Rails model class, without any hassles. The index will be kept up to date automagically while you work with your Rails model classes as usual.
• Each Model class calling acts_as_ferret gets its own Ferret index on disk, but you can search multiple models at once using the multi_search method.
• Supports Rails' single table inheritance mechanism (just declare acts_as_ferret in the base class, and be able to search across all inheriting classes, see TypoWithFerret for an example)
• Aaf is not limited to indexing the attributes of your model: You can tell it to index the result of any instance method of your model class.
• Further customization of the indexing process can be achieved by overriding the to_doc instance method in your model class, which is supposed to return the Ferret document object to be stored in the index.
• Use my_model_instance#more_like_this to retrieve objects having similar contents like my_model_instance. Great for suggesting related pages to your readers, or related products to your customers.
• DRb Server for centralized index access in production environments. This is required as soon as more than one process needs to update the Ferret index, which is true for most deployments with multiple Mongrel / fastCGI instances.

Installation

Prerequisites

Install ferret gem. In most cases

gem install ferret

should do. More instructions here.

System-wide installation

From Version 0.3.1 onwards, acts_as_ferret is available as a gem, too. So you can use

gem install acts_as_ferret

to install the latest version it into your local gem repository. In your Rails project, you have to

require 'acts_as_ferret'

in your environment.rb to hook the plugin into Rails. Additionally, you have to copy the DRb server start/stop scripts and config from your gem repository to your Rails project:

cp /usr/lib/ruby/gems/1.8/gems/acts_as_ferret-0.4.1/script/ferret_st* script/
cp /usr/lib/ruby/gems/1.8/gems/acts_as_ferret-0.4.1/config/ferret_server.yml config/

The directory where your gems get installed may actually be different from the example above. If nothing helps, do find / -name ferret_server.yml to find out where the gem went. Sorry for the inconvenience, things will get better with 0.4.2.

Inside your Rails project

Please use

script/plugin install svn://projects.jkraemer.net/acts_as_ferret/tags/stable/acts_as_ferret

for easy installation of the current stable version of the plugin. At the moment this is version 0.4.1 based on Subversion Rev. 211. This is supposed to work with Ferret Versions from 0.10.4 upwards, and Rails >= 1.0.

The last version of the plugin compatible with Ferret 0.3.2 is 0.2.0, located at svn://projects.jkraemer.net/acts_as_ferret/tags/0.2.0/.

The last version of the plugin compatible with Ferret 0.9.x is 0.2.3, located at svn://projects.jkraemer.net/acts_as_ferret/tags/0.2.3/.

If you want to use bleeding edge version of the plugin, use

script/plugin install svn://projects.jkraemer.net/acts_as_ferret/trunk/plugin/acts_as_ferret

Please note that the trunk usually requires the latest version of Ferret.

There's also a whole demo Rails project (containing the acts_as_ferret test suite, a simple model class, scaffolded CRUD GUI and a search form) available at svn://projects.jkraemer.net/acts_as_ferret/trunk/demo The demo project runs on Edge Rails.

Updating your installation (optional)

After the plugin is already installed, you might want to get the latest plugin version. Do this by typing:

script/plugin update

This will automatically get updated versions of your acts_as_ferret plugin (and all plugins that were installed from svn repositories.)

Also, an interesting note from trunk/railties/lib/commands/plugin.rb:

#   * If `vendor/plugins` is under subversion control, the script will
#     modify the svn:externals property and perform an update. You can
#     use normal subversion commands to keep the plugins up to date.

If you installed the acts_as_ferret gem, upgrading is even easier:

gem update acts_as_ferret

Usage

Basic usage is as follows:

In any model.rb add acts_as_ferret

 class Foo < ActiveRecord::Base
   acts_as_ferret :remote => true
 end

All CRUD operations will be performed on both ActiveRecord? (as usual) and a ferret index for further searching. The remote option lets aaf connect to the indexing server if one is configured in config/ferret_server.yml for the current environment. The DRb server is required for acts_as_ferret to work reliably if your application is running with more than one process (read: mongrel or fastcgi listener).

Now you can use

 Foo.find_by_contents(query) # Query is a string representing your query

in your controller logic.

More documentation can be found in the API documentation.

Read about AdvancedUsage with aaf.

Resources on the web

• 2008-04-29 Brandon Keepers made a nice tutorial on using shared indexes
• 2008-01-17 Although pagination is built into acts_as_ferret, it's possible to use other approaches to pagination as this post suggests
• 2007-02-19 Be sure to check out Gregg Pollack's great tutorial. He covers all the important features of Ferret/ActsAsFerret - from simple searches to custom fields to match highlighting.
• 2006-10-18 Roman Mackovcak posted a nice Introduction to Acts_as_ferret including info on how to do paging across search results.

Read how to integrate Ferret with the Typo blogging engine: TypoWithFerret

UTF-8 support

With recent Ferret versions (0.9.x) acts_as_ferret should provide UTF-8 support for indexing and searching out of the box. See test_unicode in content_test.rb. Unfortunately this UTF-8 support is not available in the ruby-only version of Ferret 0.9.x.

Read here about configuring a complete Debian/Rails/MySQL/Ferret stack to use UTF8

Read this for a discussion of non-latin character handling

The following resources describe how to set up and integrate a custom analyzer that replaces accentuated characters with their ascii counter parts for use with acts_as_ferret. This approach is useful when using older Ferret versions or the Ruby-only version of Ferret 0.9.x, which aren't able to handle such characters properly:

For acts_as_ferret unicode support see Albert Delamednolls code example on his blog.

Here's a sample method to transform western european accentuated chars to ascii (thanks to Bernd Schmeil)

  def strip_diacritics(s)
    # latin1 subset only
    s.tr("ÀÁÂÃÄÅÇÈÉÊËÌÍÎÏÑÒÓÔÕÖØÙÚÛÜÝàáâãäåçèéêëìíîïñòóôõöøùúûüýÿ",
         "AAAAAACEEEEIIIINOOOOOOUUUUYaaaaaaceeeeiiiinoooooouuuuyy").
      gsub(/Æ/, "AE").
      gsub(/Ð/, "Eth").
      gsub(/Þ/, "THORN").
      gsub(/ß/, "ss").
      gsub(/æ/, "ae").
      gsub(/ð/, "eth").
      gsub(/þ/, "thorn")
  end

Multi language support

Analysis is language dependent. If you have to handle documents containing multilingual text, the MultiLingualFerretTools plugin built by Lingr.com might be useful.

Using Multiple Databases (Database Hijacking) and one ferret index

See Multiple Databases for information on how to index multiple databases into one ferret index.

Prior Versions of this plugin

Before the creation of this repository there were several different versions of this plugin floating around, mainly inside the Ferret Wiki at http://ferret.davebalmain.com/trac/wiki. Have a look at them: OriginalVersions

Acts_as_ferret combines the efforts by Kasper Weibel, Thomas Lockney and Jens Kraemer, who each made a version of the plugin based on Kaspers original code from December 2005. The three versions were unified by Jens in February 2006 and put it into SVN.

The intention is for the SVN to be the main acts_as_ferret source.

Gotchas

A page of Gotchas and other possible issues.