=RSolr

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: http://github.com/mwmitchell/rsolr/tree/v0.12.1

A simple, extensible Ruby client for Apache Solr.

== Installation:
  gem sources -a http://gemcutter.org
  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', :q=>'*:*'
  
  # send a request to a custom request handler; /catalog
  response = solr.get 'catalog', :q=>'*:*'
  
== Querying
Use the #select method to send requests to the /select handler:
  response = solr.get('select', {
    :q=>'washington',
    :start=>0,
    :rows=>10
  })

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:
  
  solr.get 'select', :q=>'roses', :fq=>['red', 'violet']

The above statement generates this Solr query:
  
  select?q=roses&fq=red&fq=violet

There may be cases where the query string is too long for a GET request. RSolr solves this issue by providing a simple way to POST a query to Solr:
  response = solr.post "select", nil, enormous_params_hash

nil is passed in as the query string data. The enormous_params_hash variable ends up serialized as a form-encoded query string, and the correct content-type headers are sent along to Solr.

== Updating Solr
Updating us 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.

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
  end

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
  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', :wt=>:ruby # notice :ruby is a Symbol
===Raw Ruby
  solr.get 'select', :wt=>'ruby' # notice 'ruby' is a String

===XML:
  solr.get 'select', :wt=>:xml
===JSON:
  solr.get 'select', :wt=>:json

You can access the original request context (path, params, url etc.) by calling the #request method:
  result = solr.get 'select', :q=>'*:*'
  result.request[:uri]
  result.request[:params]
  etc..

Similarly, the object returned has a response object. This contains any headers that Solr returned, along with the raw response body:
  result = solr.get 'select', :q=>'*:*'
  result.response[:headers]
  result.response[:status]
  result.response[:body]

==Related Resources & Projects
* {RSolr Google Group}[http://groups.google.com/group/rsolr] -- The RSolr discussion group
* {rsolr-ext}[http://github.com/mwmitchell/rsolr-ext] -- An extension kit for RSolr
* {rsolr-direct}[http://github.com/mwmitchell/rsolr-direct] -- JRuby direct connection for RSolr
* {rsolr-nokogiri}[http://github.com/mwmitchell/rsolr-nokogiri] -- Gives RSolr Nokogiri for XML generation.
* {SunSpot}[http://github.com/outoftime/sunspot] -- An awesome Solr DSL, built with RSolr
* {Blacklight}[http://blacklightopac.org] -- A "next generation" Library OPAC, built with RSolr
* {java_bin}[http://github.com/kennyj/java_bin] -- Provides javabin/binary parsing for RSolr
* {Solr}[http://lucene.apache.org/solr/] -- The Apache Solr project
* {solr-ruby}[http://wiki.apache.org/solr/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.

== 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
* Lorenzo Riccucci
* Mike Perham
* Mat Brown
* Shairon Toledo
* Matthew Rudy
* Fouad Mardini
* Jeremy Hinegardner
* Nathan Witmer
* Craig Smith

==Author

Matt Mitchell <mailto:goodieboy@gmail.com>

==Copyright

Copyright (c) 2008-2010 mwmitchell. See LICENSE for details.