sunspot¶ ↑

github.com/outoftime/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 against them.

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

Sunspot is currently under active development and is not feature-complete.

Sunspot already has these 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

• Ability to pass dynamic conditions in as a hash, and define which operator to use for each condition

• Full compatibility with will_paginate

• Ordering

Sunspot will have these features:¶ ↑

• Adapters for DataMapper, ActiveRecord, and File objects

• Extensible adapter architecture for easy integration of other ORMs or non-model classes

• High-power integration with ORM features for maximum efficiency (e.g., specify AR :include argument for eager loading associations when hydrating search results)

• Intuitive interface for requesting facets on indexed fields

• Define association facets, which return model objects as row values

• Access search parameters as hash or object attributes, for easy integration with form helpers or query string builders

• Plugins for drop-in integration with Merb and Rails

Installation¶ ↑

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

You will find an installation of Solr in the gem directory. You can start it on port 8983 by doing:

cd /path/to/gems/outoftime-sunspot/solr
java -jar start.jar

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'

I will be endeavoring to make setting up Solr less of a pain with future versions.

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
  time :published_at
  string :sort_title do
    title.downcase.sub(/^(an?|the)\W+/, ''/) if title = self.title
  end
end

Search for objects:¶ ↑

search = Sunspot.search Post, :conditions => { :average_rating => 3.0 } 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

  conditions.interpret :average_rating, :greater_than
  conditions.default :average_rating, 4.0

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

Get data and parameters from search:¶ ↑

search.results
search.total
search.page
search.per_page
search.keywords
search.conditions.average_rating
search.attributes[:conditions]

Requirements¶ ↑

1. extlib

2. solr-ruby

3. Java

LICENSE:¶ ↑

(The MIT License)

Copyright © 2008 Mat Brown

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the ‘Software’), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED ‘AS IS’, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.