A simple, extensible Ruby client for Apache Solr.


gem sources -a
sudo gem install rsolr


require 'rubygems'
require 'rsolr'
solr = RSolr.connect :url=>''

# send a request to /select
response = :q=>'*:*'

# send a request to a custom request handler; /catalog
response = rsolr.request '/catalog', :q=>'*:*'

# alternative to above:
response = rsolr.catalog :q=>'*:*'


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

response ={

The params sent into the method are sent to Solr as-is. The one exception is if a value is an array. When an array is used, multiple parameters *with the same name* are generated for the Solr query. Example: :q=>'roses', :fq=>['red', 'violet']

The above statement generates this Solr query:


Use the #request method for a custom request handler path:

response = solr.request '/documents', :q=>'test'

A shortcut for the above example use a method call instead:

response = solr.documents :q=>'test'

Updating Solr

Updating uses 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”. Raw XML strings can also be used.

Raw XML via #update

solr.update '</commit>'
solr.update '</optimize>'

Single document via #add

solr.add :id=>1, :price=>1.00

Multiple documents via #add

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

When adding, you can also supply “add” xml element attributes and/or a block for manipulating other “add” related elements (docs and fields) when using the #add method:

doc = {:id=>1, :price=>1.00}
add_attributes = {:allowDups=>false, :commitWithin=>10.0}
solr.add(doc, add_attributes) do |doc|
  # boost each document
  doc.attrs[:boost] = 1.5
  # boost the price field:
  doc.field_by_name(:price).attrs[:boost] = 2.0

Delete by id

solr.delete_by_id 1

or an array of ids

solr.delete_by_id [1, 2, 3, 4]

Delete by query:

solr.delete_by_query 'price:1.00'

Delete by array of queries

solr.delete_by_query ['price:1.00', 'price:10.00']

Commit & optimize shortcuts


Response Formats

The default response format is Ruby. When the :wt param is set to :ruby, the response is eval'd resulting in a Hash. You can get a raw response by setting the :wt to “ruby” - notice, the string – not a symbol. RSolr will eval the Ruby string ONLY if the :wt value is :ruby. All other response formats are available as expected, :wt=>'xml' etc..

Evaluated Ruby (default)>:ruby) # notice :ruby is a Symbol

Raw Ruby>'ruby') # notice 'ruby' is a String



You can access the original request context (path, params, url etc.) by calling the #raw method:

response = :q=>'*:*'

The raw is a hash that contains the generated params, url, path, post data, headers etc., very useful for debugging and testing.

Related Resources & Projects

  • RSolr Google Group – The RSolr discussion group

  • rsolr-ext – An extension kit for RSolr

  • rsolr-direct – JRuby direct connection for RSolr

  • SunSpot – An awesome Solr DSL, built with RSolr

  • Blacklight – A “next generation” Library OPAC, built with RSolr

  • java_bin – Provides javabin/binary parsing for RSolr

  • Solr – The Apache Solr project

  • solr-ruby – The original Solr Ruby Gem!

Note on Patches/Pull Requests

  • Fork the project.

  • Make your feature addition or bug fix.

  • Add tests for it. This is important so I don't break it in a future version unintentionally.

  • Commit, do not mess with rakefile, version, or history (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)

  • Send me a pull request. Bonus points for topic branches.


  • mperham

  • Mat Brown

  • shairontoledo

  • Matthew Rudy

  • Fouad Mardini