= Sunspot

http://outoftime.github.com/sunspot

Sunspot is a Ruby library for expressive, powerful interaction with the Solr search engine.
Sunspot is built on top of the solr-ruby gem, which provides a low-level interface for Solr
interaction; Sunspot provides a simple, intuitive, expressive DSL backed by powerful
features for indexing objects and searching for them.

Sunspot is designed to be easily plugged in to any ORM, or even non-database-backed
objects such as the filesystem.

=== Features:

* Define indexing strategy for each searchable class using intuitive block-based API
* Clean separation between keyword-searchable fields and fields for scoping/ordering
* Define fields based on existing attributes or "virtual fields" for custom indexing
* Indexes each object's entire superclass hierarchy, for easy searching for all objects inheriting from a parent class
* Intuitive DSL for scoping searches, with all the usual boolean operators available
* Intuitive interface for requesting facets on indexed fields
* Extensible adapter architecture for easy integration of other ORMs or non-model classes
* Full compatibility with will_paginate
* Ordering

== Installation

  gem sources -a http://gems.github.com
  gem install outoftime-sunspot

In order to start the packaged Solr installation, run:

  sunspot-solr start -- [-d /path/to/data/directory] [-p port] [-s path/to/solr/home]

If you don't specify a data directory, your Solr index will be stored in your operating system's temporary directory.

If you specify a solr home, the directory must contain a <code>conf</code>
directory, which should contain at least <code>schema.xml</code> and
<code>solrconfig.xml</code>. Be sure to copy the <code>schema.xml</code> out of
the Sunspot gem's <code>solr/solr/conf</code> directory. Sunspot relies on the
field name patterns defined in the packaged <code>schema.xml</code>, so those
cannot be modified.

You can also run your own instance of Solr wherever you'd like; just copy the solr/config/schema.xml file out of the gem's solr into your installation.
You can change the URL at which Sunspot accesses Solr with:

  Sunspot.config.solr.url = 'http://solr.my.host:9818/solr'

== Rails Integration

The {Sunspot::Rails}[http://github.com/outoftime/sunspot_rails] plugin makes
integrating Sunspot into Rails drop-in easy.

== Using Sunspot

=== Define an index:

  class Post
    #...
  end

  Sunspot.setup(Post) do
    text :title, :body
    string :author_name
    integer :blog_id
    integer :category_ids
    float :average_rating, :using => :ratings_average
    time :published_at
    string :sort_title do
      title.downcase.sub(/^(an?|the)\W+/, ''/) if title = self.title
    end
  end

See Sunspot.setup for more information.

Note that in order for a class to be searchable, it must have an adapter
registered for itself or one of its subclasses. Adapters allow Sunspot to load
objects out of persistent storage, and to determine their primary key for
indexing. {Sunspot::Rails}[http://github.com/outoftime/sunspot_rails] comes with
an adapter for ActiveRecord objects, but for other types of models you will need
to define your own. See Sunspot::Adapters for more information.

=== Search for objects:
  
  search = Sunspot.search Post do
    keywords 'great pizza'
    with :author_name, 'Mark Twain'
    with(:blog_id).any_of [2, 14]
    with(:category_ids).all_of [4, 10]
    with(:published_at).less_than Time.now
    without :title, 'Bad Title'
    without bad_instance # specifically exclude this instance from results

    paginate :page => 3, :per_page => 15
    order_by :average_rating, :desc

    facet :blog_id
  end

See Sunspot.search for more information.

=== Get data from search:

  search.results
  search.total
  search.page
  search.per_page
  search.facet(:blog_id)

=== Building searches manually:

The search DSL is great for building searches from fairly static parameters,
but a highly dynamic search might want to leverage an intermediate approach
(such as an application of the Builder pattern). For these cases, Sunspot
exposes direct access to the Query object:

  search = Sunspot.new_search(Post)
  search.query.keywords = 'great pizza'
  search.query.add_restriction(:author_name, :equal_to, 'Mark Twain')
  search.query.add_restriction(:title, :equal_to, 'Bad Title', true) # negate the restriction
  search.query.exclude_instance(bad_instance)
  search.query.paginate(3, 15)
  search.query.order_by(:average_rating, :desc)
  search.query.add_field_facet(:blog_id)
  search.execute! 

== About the API documentation

All of the methods documented in the RDoc are considered part of Sunspot's
public API. Methods that are not part of the public API are documented in the
code, but excluded from the RDoc. If you find yourself needing to access methods
that are not part of the public API in order to do what you need, please contact
me so I can rectify the situation!

== Dependencies

1. solr-ruby
2. Java

Sunspot has been tested with MRI 1.8.6, YARV 1.9.1, and JRuby 1.2.0

== Bugs

Please submit bug reports to
http://outoftime.lighthouseapp.com/projects/20339-sunspot

== Further Reading

* Sunspot Discussion: http://groups.google.com/group/ruby-sunspot
* Posts about Sunspot from my tumblog: http://outofti.me/tagged/sunspot
* Read about it on Linux Magazine: http://www.linux-mag.com/id/7341

== Contributors

* Mat Brown (mat@patch.com)
* Peer Allan (peer.allan@gmail.com)
* Dmitriy Dzema (dima@dzema.name)

== License

Sunspot is distributed under the MIT License, copyright (c) 2008-2009 Mat Brown