RSolr

A Ruby client for Apache Solr. Has transparent JRuby support by using “org.apache.solr.servlet.DirectSolrConnection” as a connection adapter.

Installation:

gem sources -a http://gems.github.com
sudo gem install mwmitchell-rsolr

Simple usage:

require 'rubygems'
require 'rsolr'
rsolr = RSolr.connect
response = rsolr.query(:q=>'*:*') # becomes /solr/select?q=*:*
# can also set the request handler path like:
response = rsolr.query('catalog', :q=>'*:*') # becomes /solr/catalog?q=*:*

To run tests:

Copy an Apache Solr 1.3.0/or later (http://apache.seekmeup.com/lucene/solr/1.3.0/) distribution into this directory and rename to "apache-solr"
Start Solr HTTP:    rake rsolr:start_test_server
MRI Ruby:           rake
JRuby:              jruby -S rake

To get a connection in MRI/standard Ruby:

solr = RSolr.connect

To get a direct connection (no http) in jRuby using DirectSolrConnection:

solr = RSolr.connect(:adapter=>:direct, :home_dir=>'/path/to/solr/home', :dist_dir=>'/path/to/solr/distribution')

You can set the request handler paths for every request:

solr = RSolr.connect(:select_path=>'select', :update_path=>'update', :luke_path=>'admin/luke')

Requests

Once you have a connection, you can execute queries, updates etc..

You can optionally specify the request handler path by sending it in as the first argument:

solr.query 'catalog', :q=>'object_type:"book"'
solr.update 'my/update', '<xml/>'

The default request handler path value for each of the different methods are as follows:

find_by_id, query == 'select'
add, update, commit, optimize, rollback, delete_by_id, delete_by_query == 'update'
index_info == 'admin/luke'

Please note that the path you specify should be relative.

Querying

Use the #query method to send requests to the /select handler:

response = solr.query(:q=>'washington', :facet=>true, 'facet.limit'=>-1, 'facet.field'=>'cat', 'facet.field'=>'inStock', :start=>0, :rows=>10)
response = solr.find_by_id(1)

Pagination is simplified by having a few helpful response methods:

response = solr.query(:start=>0, :rows=>10, :q=>'*:*')
response.per_page
response.total_pages
response.current_page
response.previous_page
response.next_page

If you use WillPaginate, just pass-in the response to the #will_paginate view helper:

<%= will_paginate(@response) %>

Updating Solr

Updating is done using native Ruby structures. Hashes are used for single documents and arrays are used for a collection of documents (hashes). These structures get turned into simple XML “messages”.

Single document

response = solr.add(:id=>1, :price=>1.00)

Multiple documents

response = solr.add([{:id=>1, :price=>1.00}, {:id=>2, :price=>10.50}])

When adding, you can also supply “add” attributes and/or a block for digging into the Solr “add” params:

doc = {:id=>1, :price=>1.00}
solr.add(doc, {:allowDups=>false, :commitWithin=>10.0}) do |doc_attrs|
  doc_attrs[:boost] = 10.0
end

Delete by id

response = solr.delete_by_id(1)

or an array of ids

response = solr.delete_by_id([1, 2, 3, 4])

Delete by query:

response = solr.delete_by_query('price:1.00')

Delete by array of queries

response = solr.delete_by_query(['price:1.00', 'price:10.00'])

Commit & Optimize

solr.commit
solr.optimize

Response Formats

The default response format is Ruby. When the :wt param is set to :ruby, the response is eval’d and wrapped up in a nice RSolr::Response class. You can get an unwrapped response by setting the :wt to “ruby” - notice, the string – not a symbol. All other response formats are available as expected, :wt=>‘xml’ etc.. Currently, the only response format that gets eval’d and wrapped is :ruby.

You can access the original request context (path, params, url etc.) from response.request. The response.request is a hash that contains the generated params, url, path, post data, headers etc., very useful for debugging and testing.

HTTP Client Adapter

You can specify the http client adapter to use by setting RSolr::Connection::Adapter::HTTP.client_adapter to one of:

:net_http     uses the standard Net::HTTP library
:curb         uses the Ruby "curl" bindings

Example:

RSolr::Connection::Adapter::HTTP.client_adapter = :curb

Example of using the HTTP client only:

hclient = RSolr::HTTPClient.connect(url, :curb)
hclient = RSolr::HTTPClient.connect(url, :net_http)

After reading this apocryph.org/2008/11/09/more_indepth_analysis_ruby_http_client_performance - I would recommend using the :curb adapter. NOTE: You can’t use the :curb adapter under jRuby. To install curb:

sudo gem install curb