Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
A Ruby client for Apache Solr
Ruby

This branch is 223 commits behind master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
jetty
lib
spec
tasks
.gitignore
LICENSE
README.rdoc
Rakefile
VERSION
example.rb
rsolr.gemspec

README.rdoc

RSolr

A simple, extensible Ruby client for Apache Solr.

Notice: This document is only for the the 1.0 (pre-release) in the master branch. The last stable gem release documentation can be found here: github.com/mwmitchell/rsolr/tree/v0.12.1

Installation:

sudo gem install rsolr

Example:

require 'rubygems'
require 'rsolr'

# Direct connection
solr = RSolr.connect 'http://solrserver.com'

# Connecting over a proxy server
solr = RSolr.connect 'http://solrserver.com', :proxy=>'http://user:pass@proxy.example.com:8080'

# send a request to /select
response = solr.get 'select', :params => {:q => '*:*'}

# send a request to /catalog
response = solr.get 'catalog', :params => {:q => '*:*'}

Querying

Use the #get / #post method to send search requests to the /select handler:

response = solr.get 'select', :params => {
  :q=>'washington',
  :start=>0,
  :rows=>10
}

The :params sent into the method are sent to Solr as-is. When an array is used, multiple parameters *with the same name* are generated for the Solr query. Example:

solr.get 'select', :params => {:q=>'roses', :fq=>['red', 'violet']}

The above statement generates this Solr query:

select?q=roses&fq=red&fq=violet

Using POST for Search Queries

There may be cases where the query string is too long for a GET request. RSolr solves this issue by converting hash objects into form-encoded strings:

response = solr.post "select", :data => enormous_params_hash

The :data hash is serialized as a form-encoded query string, and the correct content-type headers are sent along to Solr.

Method Missing

The RSolr::Client class also uses method_missing for setting the request handler/path:

solr.paintings :params => {:q=>'roses', :fq=>['red', 'violet']}

This is sent to Solr as:

paintings?q=roses&fq=red&fq=violet

Updating Solr

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

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

Raw XML via #update

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

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}
solr.add(doc, :add_attrs => 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
end

Deleting

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

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 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)

solr.get 'select', :params => {:wt => :ruby} # notice :ruby is a Symbol

Raw Ruby

solr.get 'select', :params => {:wt => 'ruby'} # notice 'ruby' is a String

XML:

solr.get 'select', :params => {:wt => :xml}

JSON:

solr.get 'select', :params => {:wt => :json}

Original Request and Response Data

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

result = solr.get 'select', :params => {:q => '*:*'}
result.request[:uri]
result.request[:params]
etc..

Similarly, the object returned has a :response method. This contains any headers that Solr returned, along with the raw response body and status code:

result = solr.get 'select', :params => {:q => '*:*'}
result.response[:headers]
result.response[:status]
result.response[:body]

NOOP

You can get the request context sent to Solr without actually sending it… if you set :noop => true:

request_context = solr.delete_by_id [1, 2, 3, 4], :noop => true

GET, POST, HEAD

RSolr can send GET, POST and HEAD requests to Solr:

response = solr.head "admin/"

Related Resources & Projects

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.

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.

Contributors

  • Colin Steele

  • Lorenzo Riccucci

  • Mike Perham

  • Mat Brown

  • Shairon Toledo

  • Matthew Rudy

  • Fouad Mardini

  • Jeremy Hinegardner

  • Nathan Witmer

  • Craig Smith

Author

Matt Mitchell <goodieboy@gmail.com>

Copyright

Copyright © 2008-2010 Matt Mitchell. See LICENSE for details.

Something went wrong with that request. Please try again.