Home

Welcome to the acts_as_solr wiki!

Now let’s learn with a simple example how you can use this plugin to add full text search functionality to your models. But before that, let’s check out acts_as_solr and Solr features:

Features

1. Solr features
   1. Based on the proven and widely known Lucene search library
   2. Using the fast and lightweight Jetty HTTP server
   3. Many filters, plugins and complements available from the community (stemmers, charset converters, stop-words filters with lists in many languages)
2. acts_as_solr features
   1. Live updates for your active_record models (no need to have a task reindexing your data, after every save/update the index is updated)
   2. Almost no special configuration needed
   3. Various hooks for error handling when things go bad (your application doesn’t stop working if an index or search can’t be performed)
   4. Fully compatible with will_paginate view helpers and :page/:per_page options (you don’t need to change anything at your views at all)

Warming up

To start using this plugin you’ll have set up a Rails application ( rails -d mysql acts_as_solr_sample ) and then install the plugin like this:

ruby script/plugin install git://github.com/mauricio/acts_as_solr.git

To be sure that the plugin was correctly installed, check if there’s a file at “RAILS_ROOT/config/solr.yml” and a folder at “RAILS_ROOT/config/solr”. If both the config file and folder exist, you’re ready to start using acts_as_solr in your application.

As Solr is based on Lucene that’s a Java full text search engine you’ll also have to install a Java Runtime Environment (JRE) in your machine if you don’t already have one, you can find the latest version here .

Configuration

The first configuration file we have to check out is the solr.yml:

# Config file for the acts_as_solr plugin.
#
# If you change the host or port number here, make sure you update 
# them in your Solr config file
development:
  url: http://localhost:8982/solr
# uncomment this line if you want to have Solr errors raised at your application
# if this property is undefined or set to false the errors will be logged
# using the rails logger but they will not be raised to the application
# raise_error: true
production:
  url: http://localhost:8983/solr
# raise_error: true

This is the configuration to start the Solr server and also the configuration that the plugin will use to make requests to this server so you need to be sure that the host contains the real name of the machine that is going to host the Solr server, specially in production. Every environment can use it’s own configuration and the raise_error config tells acts_as_solr if the errors received when trying to talk to the Solr server should be raised to your application or not. The default value is “false” which means that the errors are not going to be raised to your application but they will be logged using the Rails logger. We’ll get back to error handling later.

The files under “RAILS_ROOT/config/solr” are the heart of your Solr server configuration, they tell Solr which filters and field configurations should be used and that’s also were your index files are going to be stored. The Solr index files live at “RAILS_ROOT/config/solr/data/RAILS_ENV”. Be sure to ignore the index folders when pushing data to your source control system.

Using the plugin

Now it’s time to get your hands dirty using the plugin for real, let’s start building the model that’s going to be searched, the NewsStory:

class NewsStory < ActiveRecord::Base

  acts_as_solr
  validates_presence_of :title, :description

  def to_s
    title
  end

end

And here’s the migration that’s going to create it:

class CreateNewsStories < ActiveRecord::Migration
  def self.up
    create_table :news_stories do |t|
      t.string :title, :null => false
      t.text :description
      t.timestamps
    end
  end

  def self.down
    drop_table :news_stories
  end
end

With our model created and the migration run (rake db:migrate) we’ll have to start the Solr server:

rake solr:start

After this you should get some output like this:

 Solr started successfully on 8982, pid: 12770.
2009-05-29 15:00:09.853::INFO:  Logging to STDERR via org.mortbay.log.StdErrLog
2009-05-29 15:00:09.966::INFO:  jetty-6.1.18
2009-05-29 15:00:10.027::INFO:  Extract file:/home/mauricio/NetBeansProjects/acts_as_solr_sample/vendor/plugins/acts_as_solr/jetty/webapps/solr.war to /tmp/Jetty_localhost_8982_solr.war__solr__6dieve/webapp
2009-05-29 15:00:10.972::INFO:  Opened /home/mauricio/NetBeansProjects/acts_as_solr_sample/log/development_2009_05_29.request.log
2009-05-29 15:00:10.992::INFO:  Started SelectChannelConnector@localhost:8982

The Jetty server that loads the Solr webapp is now ready to begin indexing your data and answering for search calls. Let’s add some news stories do the database (fire your “ruby script/console”):

NewsStory.create( 
  :title => 'acts_as_solr rocks', 
  :description => 'a simple and easy way to do full text searching in your rails app' )
NewsStory.create( 
  :title => 'couchdb is the next big thing', 
  :description => 'you shuld start paying attention to it, nice and easy way to store and search data' )

Now it’s time for us to search for them using Solr:

news_stories = NewsStory.find_by_solr( 'easy' )
news_stories.each { |news_story| puts news_story.title }

You should receive an object ( a ActsAsSolr::SearchResults ) with the two news stories you just persisted to your dabase, this object behaves just like a common Array, so you can use it anywhere you’d expect to use an Array but it also implements the same methods found at the will_paginate collection so you can also use it at your will_paginate view helpers.

And guess what? That’s it!

Now you have full text search working in your application in an almost effortless way. Read the plugin docs to get a better feel of the options you can use at the acts_as_solr and find_by_solr methods and you’re ready to go live using one of the most advanced open source search tools available today.

Found a bug? Raise an issue. Has questions? Send a message. Want to send a fix or add new functionalities? Contact us! We’re eager to help and be helped.