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.
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
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 conf directory, which should contain at least schema.xml and solrconfig.xml. Be sure to copy the schema.xml out of the Sunspot gem's solr/solr/conf directory. Sunspot relies on the field name patterns defined in the packaged schema.xml, 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'
The Sunspot::Rails plugin makes integrating Sunspot into Rails drop-in easy.
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 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!
Sunspot has been tested with MRI 1.8.6, YARV 1.9.1, and JRuby 1.2.0
Please submit bug reports to outoftime.lighthouseapp.com/projects/20339-sunspot
Sunspot Discussion: groups.google.com/group/ruby-sunspot
IRC: #sunspot-ruby @ Freenode
Posts about Sunspot from my tumblog: outofti.me/tagged/sunspot
Read about it on Linux Magazine: www.linux-mag.com/id/7341
Mat Brown (email@example.com)
Peer Allan (firstname.lastname@example.org)
Dmitriy Dzema (email@example.com)
Sunspot is distributed under the MIT License, copyright © 2008-2009 Mat Brown