Sunspot

Sunspot is a Ruby library for expressive, powerful interaction with the Solr search engine. Sunspot is built on top of the RSolr library, 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.

This README provides a high level overview; class-by-class and method-by-method documentation is available in the API reference.

For questions about how to use Sunspot in your app, please use the Sunspot Mailing List or search Stack Overflow.

Quickstart with Rails

Add to Gemfile:

gem'sunspot_rails'gem'sunspot_solr'# optional pre-packaged Solr distribution for use in development. Not for use in production.

Bundle it!

bundle install

Generate a default configuration file:

rails generate sunspot_rails:install

If sunspot_solr was installed, start the packaged Solr distribution with:

bundle exec rake sunspot:solr:start # or sunspot:solr:run to start in foreground

This will generate a /solr folder with default configuration files and indexes.

If you're using source control, it's recommended that the files generated for indexing and running (PIDs) are not checked in. You can do this by adding the following lines to .gitignore:

solr/data
solr/test/data
solr/development/data
solr/default/data
solr/pids

Setting Up Objects

Add a searchable block to the objects you wish to index.

classPost < ActiveRecord::Basesearchabledotext:title,:bodytext:commentsdocomments.map{ |comment| comment.body}endboolean:featuredinteger:blog_idinteger:author_idinteger:category_ids,:multiple=>truedouble:average_ratingtime:published_attime:expired_atstring:sort_titledotitle.downcase.gsub(/^(an?|the)/,'')endendend

text fields will be full-text searchable. Other fields (e.g., integer and string) can be used to scope queries.

Searching Objects

Post.searchdofulltext'best pizza'with:blog_id,1with(:published_at).less_thanTime.nowfield_list:blog_id,:titleorder_by:published_at,:descpaginate:page=>2,:per_page=>15facet:category_ids,:author_idend

Search In Depth

Given an object Post setup in earlier steps ...

Full Text

# All posts with a `text` field (:title, :body, or :comments) containing 'pizza'Post.search{fulltext'pizza'}# Posts with pizza, scored higher if pizza appears in the titlePost.searchdofulltext'pizza'doboost_fields:title=>2.0endend# Posts with pizza, scored higher if featuredPost.searchdofulltext'pizza'doboost(2.0){with(:featured,true)}endend# Posts with pizza *only* in the titlePost.searchdofulltext'pizza'dofields(:title)endend# Posts with pizza in the title (boosted) or in the body (not boosted)Post.searchdofulltext'pizza'dofields(:body,:title=>2.0)endend

Phrases

Solr allows searching for phrases: search terms that are close together.

In the default query parser used by Sunspot (edismax), phrase searches are represented as a double quoted group of words.

# Posts with the exact phrase "great pizza"Post.searchdofulltext'"great pizza"'end

If specified, query_phrase_slop sets the number of words that may appear between the words in a phrase.

# One word can appear between the words in the phrase, so "great big pizza"# also matches, in addition to "great pizza"Post.searchdofulltext'"great pizza"'doquery_phrase_slop1endend

Phrase Boosts

Phrase boosts add boost to terms that appear in close proximity; the terms do not have to appear in a phrase, but if they do, the document will score more highly.

# Matches documents with great and pizza, and scores documents more# highly if the terms appear in a phrase in the title fieldPost.searchdofulltext'great pizza'dophrase_fields:title=>2.0endend# Matches documents with great and pizza, and scores documents more# highly if the terms appear in a phrase (or with one word between them)# in the title fieldPost.searchdofulltext'great pizza'dophrase_fields:title=>2.0phrase_slop1endend

Scoping (Scalar Fields)

Fields not defined as text (e.g., integer, boolean, time, etc...) can be used to scope (restrict) queries before full-text matching is performed.

Positive Restrictions

# Posts with a blog_id of 1Post.searchdowith(:blog_id,1)end# Posts with an average rating between 3.0 and 5.0Post.searchdowith(:average_rating,3.0..5.0)end# Posts with a category of 1, 3, or 5Post.searchdowith(:category_ids,[1,3,5])end# Posts published since a week agoPost.searchdowith(:published_at).greater_than(1.week.ago)end

Negative Restrictions

# Posts not in category 1 or 3Post.searchdowithout(:category_ids,[1,3])end# All examples in "positive" also work negated using `without`

Empty Restrictions

# Passing an empty array is equivalent to a no-op, allowing you to replace this...Post.searchdowith(:category_ids,id_list)ifid_list.present?end# ...with thisPost.searchdowith(:category_ids,id_list)end

Restrictions and Field List

# Posts with a blog_id of 1Post.searchdowith(:blog_id,1)field_list[:title]endPost.searchdowithout(:category_ids,[1,3])field_list[:title,:author_id]end

Disjunctions and Conjunctions

# Posts that do not have an expired time or have not yet expiredPost.searchdoany_ofdowith(:expired_at).greater_than(Time.now)with(:expired_at,nil)endend

# Posts with blog_id 1 and author_id 2Post.searchdoall_ofdowith(:blog_id,1)with(:author_id,2)endend

# Posts scoring with any of the two fields.Post.searchdoanydofulltext"keyword1",:fields=>:titlefulltext"keyword2",:fields=>:bodyendend

Disjunctions and conjunctions may be nested

Post.searchdoany_ofdowith(:blog_id,1)all_ofdowith(:blog_id,2)with(:category_ids,3)endendanydoalldofulltext"keyword",:fields=>:titlefulltext"keyword",:fields=>:bodyendalldofulltext"keyword",:fields=>:first_namefulltext"keyword",:fields=>:last_nameendfulltext"keyword",:fields=>:descriptionendend

Combined with Full-Text

Scopes/restrictions can be combined with full-text searching. The scope/restriction pares down the objects that are searched for the full-text term.

# Posts with blog_id 1 and 'pizza' in the titlePost.searchdowith(:blog_id,1)fulltext("pizza")end

Pagination

All results from Solr are paginated

The results array that is returned has methods mixed in that allow it to operate seamlessly with common pagination libraries like will_paginate and kaminari.

By default, Sunspot requests the first 30 results from Solr.

search=Post.searchdofulltext"pizza"end# Imagine there are 60 *total* results (at 30 results/page, that is two pages)results=search.results# => Array with 30 Post elementssearch.total# => 60results.total_pages# => 2results.first_page?# => trueresults.last_page?# => falseresults.previous_page# => nilresults.next_page# => 2results.out_of_bounds?# => falseresults.offset# => 0

To retrieve the next page of results, recreate the search and use the paginate method.

search=Post.searchdofulltext"pizza"paginate:page=>2end# Again, imagine there are 60 total results; this is the second pageresults=search.results# => Array with 30 Post elementssearch.total# => 60results.total_pages# => 2results.first_page?# => falseresults.last_page?# => trueresults.previous_page# => 1results.next_page# => nilresults.out_of_bounds?# => falseresults.offset# => 30

A custom number of results per page can be specified with the :per_page option to paginate:

search=Post.searchdofulltext"pizza"paginate:page=>1,:per_page=>50end

Cursor-based pagination

Solr 4.7 and above

With default Solr pagination it may turn that same records appear on different pages (e.g. if many records have the same search score). Cursor-based pagination allows to avoid this.

Useful for any kinds of export, infinite scroll, etc.

Cursor for the first page is "*".

search=Post.searchdofulltext"pizza"paginate:cursor=>"*"endresults=search.results# Results will contain cursor for the next pageresults.next_page_cursor# => "AoIIP4AAACxQcm9maWxlIDEwMTk="# Imagine there are 60 *total* results (at 30 results/page, that is two pages)results.current_cursor# => "*"results.total_pages# => 2results.first_page?# => trueresults.last_page?# => false

To retrieve the next page of results, recreate the search and use the paginate method with cursor from previous results.

search=Post.searchdofulltext"pizza"paginate:cursor=>"AoIIP4AAACxQcm9maWxlIDEwMTk="endresults=search.results# Again, imagine there are 60 total results; this is the second pageresults.next_page_cursor# => "AoEsUHJvZmlsZSAxNzY5"results.current_cursor# => "AoIIP4AAACxQcm9maWxlIDEwMTk="results.total_pages# => 2results.first_page?# => false# Last page will be detected only when current page contains less then per_page elements or contains nothingresults.last_page?# => false

:per_page option is also supported.

Faceting

Faceting is a feature of Solr that determines the number of documents that match a given search and an additional criterion. This allows you to build powerful drill-down interfaces for search.

Each facet returns zero or more rows, each of which represents a particular criterion conjoined with the actual query being performed. For field facets, each row represents a particular value for a given field. For query facets, each row represents an arbitrary scope; the facet itself is just a means of logically grouping the scopes.

By default Sunspot will only return the first 100 facet values. You can increase this limit, or force it to return all facets by setting limit to -1.

Field Facets

# Posts that match 'pizza' returning counts for each :author_idsearch=Post.searchdofulltext"pizza"facet:author_idendsearch.facet(:author_id).rows.eachdo |facet|
puts"Author #{facet.value} has #{facet.count} pizza posts!"end

If you are searching by a specific field and you still want to see all the options available in that field you can exclude it in the faceting.

# Posts that match 'pizza' and author with id 42# Returning counts for each :author_id (even those not in the search result)search=Post.searchdofulltext"pizza"author_filter=with(:author_id,42)facet:author_id,exclude: [author_filter]endsearch.facet(:author_id).rows.eachdo |facet|
puts"Author #{facet.value} has #{facet.count} pizza posts!"end

Query Facets

# Posts faceted by ranges of average ratingssearch=Post.searchdofacet(:average_rating)dorow(1.0..2.0)dowith(:average_rating,1.0..2.0)endrow(2.0..3.0)dowith(:average_rating,2.0..3.0)endrow(3.0..4.0)dowith(:average_rating,3.0..4.0)endrow(4.0..5.0)dowith(:average_rating,4.0..5.0)endendend# e.g.,# Number of posts with rating within 1.0..2.0: 2# Number of posts with rating within 2.0..3.0: 1search.facet(:average_rating).rows.eachdo |facet|
puts"Number of posts with rating within #{facet.value}: #{facet.count}"end

Range Facets

# Posts faceted by range of average ratingsSunspot.search(Post)dofacet:average_rating,:range=>1..5,:range_interval=>1end

Json Facets

The json facet can be used with the following syntax:

Sunspot.search(Post)dojson_facet(:title)end

There are some options you can pass to the json facet:

:limit
:minimum_count
:sort
:prefix
:missing
:all_buckets
:method

Some examples

# limit the results to 10Sunspot.search(Post)dojson_facet(:title,limit: 10)end# returns only the results with a minimum count of 10Sunspot.search(Post)dojson_facet(:title,minimum_count: 10)end# sort by countSunspot.search(Post)dojson_facet(:title,sort: :count)end# filter titles by prefix 't'Sunspot.search(Post)dojson_facet(:title,prefix: 't')end# compute the total number of records in all buckets# accessible via search.other_count('allBuckets')search=Sunspot.search(Post)dojson_facet(:title,all_buckets: true)end# compute the total number of records that do not have a title value# accessible via search.other_count('missing')search=Sunspot.search(Post)dojson_facet(:title,missing: true)end# force usage of the dv faceting algorithmsearch=Sunspot.search(Post)dojson_facet(:title,method: 'dv')end

Json Range Facets

Range facets are supported on numeric, date, or time fields. The range parameter is required. gap may be optionally specified to control the size of each bucket (defaults to 86400):

# minimum of 1 and maximum of 10 in steps of 3# by default the lower bound is inclusive and the upper bound is exclusive# [1-4], [4-7], [7-9], [9-10]search=Sunspot.search(Post)dojson_facet(:blog_id,range: [1,10],gap: 3)end

The other parameter may also be specified to compute additional counts besides the ones in each bucket:

# compute total count of records with blog_id less than 1search=Sunspot.search(Post)dojson_facet(:blog_id,range: [1,10],gap: 3,other: 'before')endsearch.other_count('before')# 3# compute total count of records with blog_id 10 or greatersearch=Sunspot.search(Post)dojson_facet(:blog_id,range: [1,10],gap: 3,other: 'after')endsearch.other_count('after')# 2# compute total count of records between the specified rangesearch=Sunspot.search(Post)dojson_facet(:blog_id,range: [1,10],gap: 3,other: 'between')endsearch.other_count('between')# 4# compute before/between/after countssearch=Sunspot.search(Post)dojson_facet(:blog_id,range: [1,10],gap: 3,other: 'all')endsearch.other_count('before')# 3search.other_count('after')# 2search.other_count('between')# 4

For date or time fields, you may also specify gap_unit, which controls how gap is interpreted. A list of supported units can be found here. Defaults to SECONDS:

# minimum of 2 years ago, maximum of 1 year ago# group into buckets of 3 months eachsearch=Sunspot.search(Post)dojson_facet(:published_at,range: [2.years.ago,1.year.ago],gap: 3,gap_unit: 'MONTHS')end

Json Facet Distinct

The json facet count distinct can be used with the following syntax:

# Get posts with distinct title# available stategies: :unique, :hllSunspot.search(Post)dojson_facet(:blog_id,distinct: {group_by: :title,strategy: :unique})end

Json Facet nested

The nested facets can be used with the following syntax:

Sunspot.search(Post)dojson_facet(:title,nested: {field: :author_name})end

You can nest the nested facet also recursively:

Sunspot.search(Post)dojson_facet(:title,nested: {field: :author_name,nested: {field: :title})end

Nested facets have the same options of json facets

Ordering

By default, Sunspot orders results by "score": the Solr-determined relevancy metric. Sorting can be customized with the order_by method:

# Order by average rating, descendingPost.searchdofulltext("pizza")order_by(:average_rating,:desc)end# Order by relevancy score and in the case of a tie, average ratingPost.searchdofulltext("pizza")order_by(:score,:desc)order_by(:average_rating,:desc)end# Randomized orderingPost.searchdofulltext("pizza")order_by(:random)end

Solr 3.1 and above

Solr supports sorting on multiple fields using custom functions. Supported operators and more details are available on the Solr Wiki

To sort results by a custom function use the order_by_function method. Functions are defined with prefix notation:

# Order by sum of two example fields: rating1 + rating2Post.searchdofulltext("pizza")order_by_function(:sum,:rating1,:rating2,:desc)end# Order by nested functions: rating1 + (rating2*rating3)Post.searchdofulltext("pizza")order_by_function(:sum,:rating1,[:product,:rating2,:rating3],:desc)end# Order by fields and constants: rating1 + (rating2 * 5)Post.searchdofulltext("pizza")order_by_function(:sum,:rating1,[:product,:rating2,'5'],:desc)end# Order by average of three fields: (rating1 + rating2 + rating3) / 3Post.searchdofulltext("pizza")order_by_function(:div,[:sum,:rating1,:rating2,:rating3],'3',:desc)end

Grouping

Solr 3.3 and above

Solr supports grouping documents, similar to an SQL GROUP BY. More information about result grouping/field collapsing is available on the Solr Wiki.

Grouping is only supported on string fields that are not multivalued. To group on a field of a different type (e.g., integer), add a denormalized string type

classPost < ActiveRecord::Basesearchabledo# Denormalized `string` field because grouping can only be performed# on string fieldsstring(:blog_id_str){ |p| p.blog_id.to_s}endend# Returns only the top scoring document per blog_idsearch=Post.searchdogroup:blog_id_strendsearch.group(:blog_id_str).matches# Total number of matches to the querysearch.group(:blog_id_str).groups.eachdo |group|
putsgroup.value# blog_id of the each document in the group# By default, there is only one document per group (the highest# scoring one); if `limit` is specified (see below), multiple# documents can be returned per groupgroup.results.eachdo |result|
# ...endend

Additional options are supported by the DSL:

# Returns the top 3 scoring documents per blog_idPost.searchdogroup:blog_id_strdolimit3ngroupsfalse# If you don't need the total groups counterendend# Returns document ordered within each group by published_at (by# default, the ordering is score)Post.searchdogroup:blog_id_strdoorder_by(:average_rating,:desc)endend# Facet count is based on the most relevant document of each group# matching the query (>= Solr 3.4)Post.searchdogroup:blog_id_strdotruncateendfacet:blog_id_str,:extra=>:anyend

Grouping by Queries

It is also possible to group by arbitrary queries instead of on a specific field, much like using query facets instead of field facets. For example, we can group by average rating.

# Returns the top post for each range of average ratingssearch=Post.searchdogroupdoquery("1.0 to 2.0")dowith(:average_rating,1.0..2.0)endquery("2.0 to 3.0")dowith(:average_rating,2.0..3.0)endquery("3.0 to 4.0")dowith(:average_rating,3.0..4.0)endquery("4.0 to 5.0")dowith(:average_rating,4.0..5.0)endendendsearch.group(:queries).matches# Total number of matches to the queriessearch.group(:queries).groups.eachdo |group|
putsgroup.value# The argument to query - "1.0 to 2.0", for examplegroup.results.eachdo |result|
# ...endend

This can also be used to query multivalued fields, allowing a single item to be in multiple groups.

# This finds the top 10 posts for each category in category_ids.search=Post.searchdogroupdolimit10category_ids.eachdo |category_id|
querycategory_iddowith(:category_id,category_id)endendendend

Geospatial

Sunspot 2.0 only

Sunspot 2.0 supports geospatial features of Solr 3.1 and above.

Geospatial features require a field defined with latlon:

classPost < ActiveRecord::Basesearchabledo# ...latlon(:location){Sunspot::Util::Coordinates.new(lat,lon)}endend

Filter By Radius

# Searches posts within 100 kilometers of (32, -68)Post.searchdowith(:location).in_radius(32, -68,100)end

Filter By Radius (inexact with bbox)

# Searches posts within 100 kilometers of (32, -68) with `bbox`. This is# an approximation so searches run quicker, but it may include other# points that are slightly outside of the required distancePost.searchdowith(:location).in_radius(32, -68,100,:bbox=>true)end

Filter By Bounding Box

# Searches posts within the bounding box defined by the corners (45,# -94) to (46, -93)Post.searchdowith(:location).in_bounding_box([45, -94],[46, -93])end

Sort By Distance

# Orders documents by closeness to (32, -68)Post.searchdoorder_by_geodist(:location,32, -68)end

Joins

Solr 4 and above

Solr joins allow you to filter objects by joining on additional documents. More information can be found on the Solr Wiki.

classPhoto < ActiveRecord::Basesearchabledotext:descriptionstring:caption,:default_boost=>1.5time:created_atinteger:photo_container_idendendclassPhotoContainer < ActiveRecord::Basesearchabledotext:namejoin(:description,:target=>Photo,:type=>:text,:join=>{:from=>:photo_container_id,:to=>:id})join(:caption,:target=>Photo,:type=>:string,:join=>{:from=>:photo_container_id,:to=>:id})join(:photos_created,:target=>Photo,:type=>:time,:join=>{:from=>:photo_container_id,:to=>:id},:as=>'created_at_d')endendPhotoContainer.searchdowith(:caption,'blah')with(:photos_created).between(Date.new(2011,3,1)..Date.new(2011,4,1))fulltext("keywords",:fields=>[:name,:description])end# ...orPhotoContainer.searchdowith(:caption,'blah')with(:photos_created).between(Date.new(2011,3,1)..Date.new(2011,4,1))anydofulltext("keyword1",:fields=>:name)fulltext("keyword2",:fields=>:description)# will be joined from the Photo modelendend

If your models have fields with the same name

classTweet < ActiveRecord::Basesearchabledotext:keywordsinteger:profile_idendendclassRss < ActiveRecord::Basesearchabledotext:keywordsinteger:profile_idendendclassProfile < ActiveRecord::Basesearchabledotext:namejoin(:keywords,:prefix=>"tweet",:target=>Tweet,:type=>:text,:join=>{:from=>:profile_id,:to=>:id})join(:keywords,:prefix=>"rss",:target=>Rss,:type=>:text,:join=>{:from=>:profile_id,:to=>:id})endendProfile.searchdoanydofulltext("keyword1 keyword2",:fields=>[:tweet_keywords])dominimum_match1endfulltext("keyword3",:fields=>[:rss_keywords])endend# ...produces:# sort: "score desc", fl: "* score", start: 0, rows: 20,# fq: ["type:Profile"],# q: (_query_:"{!join from=profile_ids_i to=id_i v=$qTweet91755700}" OR _query_:"{!join from=profile_ids_i to=id_i v=$qRss91753840}"),# qTweet91755700: _query_:"{!field f=type}Tweet"+_query_:"{!edismax qf='keywords_text' mm='1'}keyword1 keyword2",# qRss91753840: _query_:"{!field f=type}Rss"+_query_:"{!edismax qf='keywords_text'}keyword3"

Composite ID

SolrCloud only

If you use the compositeId router (the default), you can send documents with a prefix in the document ID which will be used to calculate the hash Solr uses to determine the shard a document is sent to for indexing. The prefix can be anything you’d like it to be (it doesn’t have to be the shard name, for example), but it must be consistent so Solr behaves consistently.

For example, if you want to co-locate documents for a customer, you could use the customer name or ID as the prefix. If your customer is IBM, for example, with a document with the ID 12345, you would insert the prefix into the document id field: IBM!12345. The exclamation mark (!) is critical here, as it distinguishes the prefix used to determine which shard to direct the document to.

classPost < ActiveRecord::Basesearchabledoid_prefix"IBM!"# ...endend

The compositeId router supports prefixes containing up to 2 levels of routing. For example: a prefix routing first by region, then by customer: USA!IBM!12345

classPost < ActiveRecord::Basesearchabledoid_prefix"USA!IBM!"# ...endend

Usage with Joins

This feature is also useful with joins, which require joined collections to be single-sharded. For example, if you have Blog and Post models and want to join fields from Posts when searching Blogs, you need these two collections to stay on the same shard. In this case the configuration would be:

classBlog < ActiveRecord::Basehas_many:postssearchabledoid_prefix"BLOGDATA!"# ...endendclassPost < ActiveRecord::Basebelongs_to:blogsearchabledoid_prefix"BLOGDATA!"# ...endend

As a result, all Blogs and Posts will be stored on a single shard. But since other Blogs will generate other prefixes Solr will distribute them evenly across the available shards.

If you have large collections that you want to use joins with and still want to utilize sharding instead of storing everything on a single shard, it's also possible to only ensure a single Blog and its associated Posts stored on a signle shard, while the whole collections could still be distributed across multiple shards. The thing is that Solr can do distributed joins across multiple shards, but the records that have to be joined should be stored on a single shard. To achieve this your configuration would look like this:

classBlog < ActiveRecord::Basehas_many:postssearchabledoid_prefixdo"BLOGDATA#{self.id}!"end# ...endendclassPost < ActiveRecord::Basebelongs_to:blogsearchabledoid_prefixdo"BLOGDATA#{self.blog_id}!"end# ...endend

This way a single Blog and its Ports have the same ID prefix and will go to a single Shard.

NOTE: Solr developers also recommend adjusting replication factor so every shard node contains replicas of all shards in the cluster. If you have 4 shards on separate nodes each of these nodes should have 4 replicas (one replica of each shard).

More information and usage examples could be found here: https://lucene.apache.org/solr/guide/6_6/shards-and-indexing-data-in-solrcloud.html

Highlighting

Highlighting allows you to display snippets of the part of the document that matched the query.

The fields you wish to highlight must be stored.

classPost < ActiveRecord::Basesearchabledo# ...text:body,:stored=>trueendend

Highlighting matches on the body field, for instance, can be achieved like:

search=Post.searchdofulltext"pizza"dohighlight:bodyendend# Will output something similar to:# Post #1# I really love *pizza*# *Pizza* is my favorite thing# Post #2# Pepperoni *pizza* is delicioussearch.hits.eachdo |hit|
puts"Post ##{hit.primary_key}"hit.highlights(:body).eachdo |highlight|
puts" " + highlight.format{ |word| "*#{word}*"}endend

Stats

Solr can return some statistics on indexed numeric fields. Fetching statistics for average_rating:

search=Post.searchdostats:average_ratingendputs"Minimum average rating: #{search.stats(:average_rating).min}"puts"Maximum average rating: #{search.stats(:average_rating).max}"

Stats on multiple fields

search=Post.searchdostats:average_rating,:blog_idend

Faceting on stats

It's possible to facet field stats on another field:

search=Post.searchdostats:average_ratingdofacet:featuredendendsearch.stats(:average_rating).facet(:featured).rows.eachdo |row|
puts"Minimum average rating for featured=#{row.value}: #{row.min}"end

Take care when requesting facets on a stats field, since all facet results are returned by Solr!

Json facets stats

search=Post.searchdostats:average_ratingdojson_facet:featuredendendsearch.json_facet_stats(:featured).rows.eachdo |row|
puts"Minimum average rating for featured=#{row.value}: #{row.min}"end

Multiple stats and selective faceting

search=Post.searchdostats:average_ratingdofacet:featuredendstats:blog_iddofacet:average_ratingendend

Functions

Functions in Solr make it possible to dynamically compute values for each document. This gives you more flexability and you don't have to only deal with static values. For more details, please read Fuction Query documentation.

Sunspot supports functions in two ways:

1. You can use functions to dynamically count boosting for field:

#Posts with pizza, scored higher (square promotion field) if is_promotedPost.searchdofulltext'pizza'doboost(function{sqrt(:promotion)}){with(:is_promoted,true)}end# adds boost query (bq parameter)boost(0.5)dowith(:is_promoted,true)end# adds a boost function (bf parameter)boost(function{sqrt(:promotion)})# adds a multiplicative boost function (boost parameter)boost_multiplicative(function{sqrt(:promotion)})end

2. You're able to use functions for ordering (see examples for order_by_function)

Atomic updates

Atomic Updates is a feature in Solr 4.0 that allows you to update on a field level rather than on a document level. This means that you can update individual fields without having to send the entire document to Solr with the un-updated fields values. For more details, please read Atomic Update documentation.

All fields of the model must be stored, otherwise non-stored values will be lost after an update.

classPost < ActiveRecord::Basesearchabledo# all fields storedtext:body,:stored=>truestring:title,:stored=>trueendendpost1=Post.create#...post2=Post.create#...# atomic update on class levelPost.atomic_updatepost1.id=>{title: 'A New Title'},post2.id=>{body: 'A New Body'}# atomic update on instance levelpost1.atomic_updatebody: 'A New Body',title: 'Another New Title'

Important

If you are using Composite ID you should pass instance as key, not id.

Post.atomic_updatepost1=>{title: 'A New Title'},post2=>{body: 'A New Body'}

It's required only for atomic updates on class level.

More Like This

Sunspot can extract related items using more_like_this. When searching for similar items, you can pass a block with the following options:

• fields :field_1[, :field_2, ...]
• minimum_term_frequency ##
• minimum_document_frequency ##
• minimum_word_length ##
• maximum_word_length ##
• maximum_query_terms ##
• boost_by_relevance true/false

classPost < ActiveRecord::Basesearchabledo# The :more_like_this option must be set to truetext:body,:more_like_this=>trueendendpost=Post.firstresults=Sunspot.more_like_this(post)dofields:bodyminimum_term_frequency5end

To use more_like_this you need to have the MoreLikeThis handler enabled in solrconfig.xml.

Example handler will look like this:

<requestHandler class="solr.MoreLikeThisHandler" name="/mlt">
<lst name="defaults">
<str name="mlt.mintf">1</str>
<str name="mlt.mindf">2</str>
</lst>
</requestHandler>

Spellcheck

Solr supports spellchecking of search results against a dictionary. Sunspot supports turning on the spellchecker via the query DSL and parsing the response. Read the solr docs for more information on how this all works inside Solr.

Solr's default spellchecking engine expects to use a dictionary comprised of values from an indexed field. This tends to work better than a static dictionary file, since it includes proper nouns in your index. The default in sunspot's solrconfig.xml is textSpell (note that buildOnCommit isn't recommended in production):

<lst name="spellchecker">
<str name="name">default</str>
<!-- change field to textSpell and use copyField in schema.xml
to spellcheck multiple fields -->
<str name="field">textSpell</str>
<str name="buildOnCommit">true</str>
</lst>

Define the textSpell field in your schema.xml.

<field name="textSpell" stored="false" type="textSpell" multiValued="true" indexed="true"/>

To get some data into your spellchecking field, you can use copyField in schema.xml:

<copyField source="*_text" dest="textSpell" />
<copyField source="*_s" dest="textSpell" />

copyField works before any analyzers you have set up on the source fields. You can add your own analyzer by customizing the textSpell field type in schema.xml:

<fieldType name="textSpell" class="solr.TextField" positionIncrementGap="100" omitNorms="true">
<analyzer>
<tokenizer class="solr.StandardTokenizerFactory"/>
<filter class="solr.StandardFilterFactory"/>
<filter class="solr.LowerCaseFilterFactory"/>
</analyzer>
</fieldType>

It's dangerous to add too much to this analyzer chain. It runs before words are inserted into the spellcheck dictionary, which means the suggestions that come back from solr are post-analyzer. With the default above, that means all spelling suggestions will be lower-case.

Once you have solr configured, you can turn it on for a given query using the query DSL (see spellcheck_spec.rb for more examples):

search = Sunspot.search(Post) do
keywords 'Cofee'
spellcheck :count => 3
end

Access the suggestions via the spellcheck_suggestions or spellcheck_suggestion_for (for just the top one) methods:

search.spellcheck_suggestion_for('cofee') # => 'coffee'
search.spellcheck_suggestions # => [{word: 'coffee', freq: 10}, {word: 'toffee', freq: 1}]

If you've turned on collation, you can also get that result:

search = Sunspot.search(Post) do
keywords 'Cofee market'
spellcheck :count => 3
end
search.spellcheck_collation # => 'coffee market'

Indexes In Depth

TODO

Index-Time Boosts

To specify that a field should be boosted in relation to other fields for all queries, you can specify the boost at index time:

classPost < ActiveRecord::Basesearchabledotext:title,:boost=>5.0text:bodyendend

Stored Fields

Stored fields keep an original (untokenized/unanalyzed) version of their contents in Solr.

Stored fields allow data to be retrieved without also hitting the underlying database (usually an SQL server). They are also required for highlighting and more like this queries.

Stored fields come at some performance cost in the Solr index, so use them wisely.

classPost < ActiveRecord::Basesearchabledotext:body,:stored=>trueendend# Retrieving stored contents without hitting the databasePost.search.hits.eachdo |hit|
putshit.stored(:body)end

Please note that when you have stored fields declared, they are all going to be retrieved from Solr every time, even if you don't really need them. You can reduce returned stored dataset by using field lists, or you can skip all of them entirely:

Post.searchdowithout_stored_fieldsend

Hits vs. Results

Sunspot simply stores the type and primary key of objects in Solr. When results are retrieved, those primary keys are used to load the actual object (usually from an SQL database).

# Using #results pulls in the records from the object-relational# mapper (e.g., ActiveRecord + a SQL server)Post.search.results.eachdo |result|
putsresult.bodyend

To access information about the results without querying the underlying database, use hits:

# Using #hits gives back all information requested from Solr, but does# not load the object from the object-relational mapperPost.search.hits.eachdo |hit|
putshit.stored(:body)end

If you need both the result (ORM-loaded object) and Hit (e.g., for faceting, highlighting, etc...), you can use the convenience method each_hit_with_result:

Post.search.each_hit_with_resultdo |hit,result|
# ...end

Reindexing Objects

If you are using Rails, objects are automatically indexed to Solr as a part of the save callbacks.

There are a number of ways to index manually within Ruby:

# On a class itselfPerson.reindexSunspot.commit# or commit(true) for a soft commit (Solr4)# On mixed objectsSunspot.index[post1,item2]Sunspot.indexperson3Sunspot.commit# or commit(true) for a soft commit (Solr4)# With autocommitSunspot.index![post1,item2,person3]

If you make a change to the object's "schema" (code in the searchable block), you must reindex all objects so the changes are reflected in Solr:

bundle exec rake sunspot:reindex
# or, to be specific to a certain model with a certain batch size:
bundle exec rake sunspot:reindex[500,Post] # some shells will require escaping [ with \[ and ] with \]# to skip the prompt asking you if you want to proceed with the reindexing:
bundle exec rake sunspot:reindex[,,true] # some shells will require escaping [ with \[ and ] with \]

Use Without Rails

TODO

Threading

The default Sunspot Session is not thread-safe. If used in a multi-threaded environment (such as sidekiq), you should configure Sunspot to use the ThreadLocalSessionProxy:

Sunspot.session=Sunspot::SessionProxy::ThreadLocalSessionProxy.new

Within a Rails app, to ensure your config/sunspot.yml settings are properly setup in this session you can use Sunspot::Rails.build_session to mirror the normal Sunspot setup process:

session=Sunspot::Rails.build_sessionSunspot::Rails::Configuration.newSunspot.session=session

Manually Adjusting Solr Parameters

To add or modify parameters sent to Solr, use adjust_solr_params:

Post.searchdoadjust_solr_paramsdo |params|
params[:q] += " AND something_s:more"endend

Eager Loading

If you want to do eager loading on your sunspot search all you have to do is add this:

Sunspot.searchPostdodata_accessor_for(Post).include=[:comment]end

This is as long as you have the relationship in the model as a has_many etc.

In this case you could call the Post.comment and not have any sql queries

Session Proxies

TODO

Type Reference

The following FieldTypes are used in sunspot. sunspot_solr will create schema.xml file inside Project for FieldType reference.

• Boolean
• SortableFloat
• Date
• SortableInt
• String
• SortableDouble
• SortableLong
• TrieInteger
• TrieFloat
• TrieInt
• LatlonField

Configuration

Configure Sunspot by creating a config/sunspot.yml file or by setting a SOLR_URL or a WEBSOLR_URL environment variable. The defaults are as follows.

development:
solr:
hostname: localhostport: 8982log_level: INFOtest:
solr:
hostname: localhostport: 8981log_level: WARNING

You may want to use SSL for production environments with a username and password. For example, set SOLR_URL to https://username:password@production.solr.example.com/solr.

You can examine the value of Sunspot::Rails.configuration at runtime.

Running Solr in production environment

sunspot_solr gem is a convenient way to start working with Solr in development. However, it is not suitable for production use. Below are some options for deploying Solr:

1. Standalone or
2. Docker Solr setup (also a good alternative for development)
3. Chef (can be used with solr 7 as well)
4. Ansible
5. Kubernetes This deploys a Zookeeper cluster so you will need to convert cores to collections in order to use it.

You can also use Docker Solr for development which, regardless of how you deploy in production, will let you match the version you have deployed in production with the version you develop against. This can simplify maintenance of your cores. See the examples directory for a suitable starting point for a core you can use.

You can run solr in a docker container with the following commands:

docker pull solr:7.7.2
docker run -p 8983:8983 solr:7.7.2 #Add -d to run it in the background

Or in a docker-compose environment:

solr:
image: solr:7.7.2ports:
- "8983:8983"volumes:
- ./solr/init:/docker-entrypoint-initdb.d/
- data:/opt/solr/server/solr/mycoresrestart:
unless-stopped

where the ./solr/init directory contains a shell script that does any initial setup like downloading and unzipping your cores. In both cases, the solr images by default expects cores to be placed in /opt/solr/server/solr/mycores.

Development

Running Tests

To run all the specs just call rake from the library root folder. To run specs related to individual gems, consider using one of the following commands:

GEM=sunspot ci/travis.sh
GEM=sunspot_rails ci/travis.sh
GEM=sunspot_solr ci/travis.sh

Generating Documentation

Install the yard and redcarpet gems:

$ gem install yard redcarpet

Uninstall the rdiscount gem, if installed:

$ gem uninstall rdiscount

Generate the documentation from topmost directory:

$ yardoc -o docs */lib/**/*.rb - README.md

Tutorials and Articles

• Using Sunspot, Websolr, and Solr on Heroku (mrdanadams)
• Full Text Searching with Solr and Sunspot (Collective Idea)
• Full-text search in Rails with Sunspot (Tropical Software Observations)
• Sunspot: A Solr-Powered Search Engine for Ruby (Linux Magazine)
• Sunspot Showed Me the Light (ben koonse)
• RubyGems.org — A case study in upgrading to full-text search (Websolr)
• How to Implement Spatial Search with Sunspot and Solr (Code Quest)
• Sunspot 1.2 with Spatial Solr Plugin 2.0 (joelmats)
• rails3 + heroku + sunspot : madness (anhaminha)
• heroku + websolr + sunspot (Onemorecloud)
• How to get full text search working with Sunspot (Hobo Cookbook)
• Full text search with Sunspot in Rails (hemju)
• Using Sunspot for Free-Text Search with Redis (While I Pondered...)
• Default scope with Sunspot (Cloudspace)
• Index External Models with Sunspot/Solr (Medihack)
• Testing with Sunspot and Cucumber (Collective Idea)
• The Saga of the Switch (mrb -- includes comparison of Sunspot and Ultrasphinx)
• Conditional Indexing with Sunspot (mikepack)
• Introduction to Full Text Search for Rails Developers (Valve's)

License

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