sunspot 1.1.0 → 1.2.0

data/Gemfile

@@ -0,0 +1,10 @@
+source :rubygems
+
+require File.expand_path('../lib/sunspot/version', __FILE__)
+
+gem 'sunspot', Sunspot::VERSION, :path => File.expand_path('..', __FILE__)
+
+group :test do
+  gem 'rspec', '~> 1.3'
+  gem 'ruby-debug'
+end

data/Gemfile.lock

@@ -0,0 +1,32 @@
+PATH
+  remote: .
+  specs:
+    sunspot (1.2.rc4)
+      escape (= 0.0.4)
+      pr_geohash (~> 1.0)
+      rsolr (= 0.12.1)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    builder (3.0.0)
+    columnize (0.3.2)
+    escape (0.0.4)
+    linecache (0.43)
+    pr_geohash (1.0.0)
+    rsolr (0.12.1)
+      builder (>= 2.1.2)
+    rspec (1.3.0)
+    ruby-debug (0.10.3)
+      columnize (>= 0.1)
+      ruby-debug-base (~> 0.10.3.0)
+    ruby-debug-base (0.10.3)
+      linecache (>= 0.3)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  rspec (~> 1.3)
+  ruby-debug
+  sunspot (= 1.2.rc4)!

data/History.txt

@@ -1,3 +1,27 @@
+== 1.2.0 2010-12-28
+* Replace solr-spatial-light with client-side geohash-based spatial search
+* Override Solr field naming conventions using :as option
+* Delegate #id method directly to calling context inside DSL
+* Create a SilentFailSessionProxy that rescues exceptions on write operations.
+* Inclusion by identity
+* Solr optimize command
+* Ignore negative :limit option for query facets
+* Eliminated value sorting for range scopes
+* Correctly cast stored boolean values if they are booleans
+* Correctly cast and return stored values for multi-valued fields
+
+== 1.1.0 2010-04-01
+* MoreLikeThis support
+* Allow multiple fulltext queries in one search
+* Function queries
+* Update solr-spatial-light to 0.0.6 build
+* Support for :prefix when faceting.
+* Allow specification of solr jar
+* Updated reindex task to allow setting of batch size and list of models to index
+* Use a '*:*' query for deleting the entire index
+* Ability to specify custom request handler for queries
+* Gracefully handle nonexistent search result
+
 == 1.0.4 2010-03-19
 * Update solr-spatial-light to 0.0.5
   * Fix NullPointerException in repeated geo search

data/README.rdoc

@@ -63,7 +63,7 @@ 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:
+You can change the URL at which Sunspot accesses Solr by setting <code>SOLR_URL</code> in your application's environment, or assigning it to Sunspot's configuration directly:
 
   Sunspot.config.solr.url = 'http://solr.my.host:9818/solr'
 
@@ -84,7 +84,7 @@ See the README for that gem or the Sunspot Wiki for more information.
   end
 
   Sunspot.setup(Post) do
-    text :title, :body
+    text :title, :description, :stored => true
     string :author_name
     integer :blog_id
     integer :category_ids
@@ -106,8 +106,10 @@ to define your own. See Sunspot::Adapters for more information.
 
 === Search for objects:
   
-  search = Sunspot.search Post do
-    keywords 'great pizza'
+  @search = Sunspot.search Post do
+    keywords 'great pizza' do 
+      hightlight :title, :description
+    end
     with :author_name, 'Mark Twain'
     with(:blog_id).any_of [2, 14]
     with(:category_ids).all_of [4, 10]
@@ -143,7 +145,7 @@ See Sunspot.search for more information.
       - if hit.score
         %span.relevance== (#{hit.score})
       %p= hit.highlight(:description).format { |word| "<span class=\"highlight\">#{word}</span>" }
-  .pagination= will_paginate(search.hits)
+  .pagination= will_paginate(@search.hits)
 
 == About the API documentation
 
@@ -208,14 +210,20 @@ Sunspot repository at `upstream`:
 * {Sunspot Full-text Search for Rails/Ruby}[http://therailworld.com/posts/23-Sunspot-Full-text-Search-for-Rails-Ruby] (The Rail World)
 * {A Few Sunspot Tips}[http://blog.trydionel.com/2009/11/19/a-few-sunspot-tips/] (spiral_code)
 * {Sunspot: A Solr-Powered Search Engine for Ruby}[http://www.linux-mag.com/id/7341] (Linux Magazine)
+* {Sunspot Showed Me the Light}[http://bennyfreshness.com/2010/05/sunspot-helped-me-see-the-light/] (ben koonse)
+* {rails3 + heroku + sunspot : madness}[http://anhaminha.tumblr.com/post/632682537/rails3-heroku-sunspot-madness] (anhaminha)
+* {How to get full text search working with Sunspot}[http://cookbook.hobocentral.net/recipes/57-how-to-get-full-text-search] (Hobo Cookbook)
 * {Using Sunspot for Free-Text Search with Redis}[http://masonoise.wordpress.com/2010/02/06/using-sunspot-for-free-text-search-with-redis/] (While I Pondered...)
+* {Fuzzy searching in SOLR with Sunspot}[http://www.pipetodevnull.com/past/2010/8/5/fuzzy_searching_in_solr_with_sunspot/] (pipe :to => /dev/null)
 * {Default scope with Sunspot}[http://www.cloudspace.com/blog/2010/01/15/default-scope-with-sunspot/] (Cloudspace)
 * {Chef recipe for Sunspot in production}[http://gist.github.com/336403]
+* {Cucumber and Sunspot}[http://opensoul.org/2010/4/7/cucumber-and-sunspot] (opensoul.org)
 * {Testing Sunspot with Cucumber}[http://blog.trydionel.com/2010/02/06/testing-sunspot-with-cucumber/] (spiral_code)
 * {Running cucumber features with sunspot_rails}[http://blog.kabisa.nl/2010/02/03/running-cucumber-features-with-sunspot_rails] (Kabisa Blog)
 * {How To Use Twitter Lists to Determine Influence}[http://www.untitledstartup.com/2010/01/how-to-use-twitter-lists-to-determine-influence/] (Untitled Startup)
 * {Sunspot Quickstart}[http://wiki.websolr.com/index.php/Sunspot_Quickstart] (WebSolr)
 * {Solr, and Sunspot}[http://www.kuahyeow.com/2009/08/solr-and-sunspot.html] (YT!)
+* {The Saga of the Switch}[http://mrb.github.com/2010/04/08/the-saga-of-the-switch.html] (mrb -- includes comparison of Sunspot and Ultrasphinx)
 
 == Contributors
 
@@ -233,6 +241,11 @@ Sunspot repository at `upstream`:
 * Kieran Topping
 * Nicolas Braem (nicolas.braem@gmail.com)
 * Jeremy Ashkenas (jashkenas@gmail.com)
+* Dylan Vaughn (dylanvaughn@yahoo.com)
+* Brian Durand (brian@embellishedvisions.com)
+* Sam Granieri (sam@samgranieri.com)
+* Nick Zadrozny (nick@onemorecloud.com)
+* Jason Ronallo (jronallo@gmail.com)
 
 == License
 

data/lib/sunspot.rb

@@ -206,6 +206,18 @@ module Sunspot
       session.commit
     end
 
+    # Optimizes the index on the singletion session.
+    #
+    # Frequently adding and deleting documents to Solr, leaves the index in a
+    # fragmented state. The optimize command merges all index segments into 
+    # a single segment and removes any deleted documents, making it faster to 
+    # search. Since optimize rebuilds the index from scratch, it takes some 
+    # time and requires double the space on the hard disk while it's rebuilding.
+    # Note that optimize also commits.
+    def optimize
+      session.optimize
+    end
+
     # 
     # Create a new Search instance, but do not execute it immediately. Generally
     # you will want to use the #search method to build and execute searches in
@@ -327,6 +339,34 @@ module Sunspot
       session.new_more_like_this(object, *types, &block)
     end
 
+    # 
+    # Initiate a MoreLikeThis search. MoreLikeThis is a special type of search
+    # that finds similar documents using fulltext comparison. The fields to be
+    # compared are `text` fields set up with the `:more_like_this` option set to
+    # `true`. By default, more like this returns objects of the same type as the
+    # object used for comparison, but a list of types can optionally be passed
+    # to this method to return similar documents of other types. This will only
+    # work for types that have common fields.
+    #
+    # The DSL for MoreLikeThis search exposes several methods for setting
+    # options specific to this type of search. See the
+    # Sunspot::DSL::MoreLikeThis class and the MoreLikeThis documentation on
+    # the Solr wiki: http://wiki.apache.org/solr/MoreLikeThis
+    #
+    # MoreLikeThis searches have all of the same scoping, ordering, and faceting
+    # functionality as standard searches; the only thing you can't do in a MLT
+    # search is fulltext matching (since the MLT itself is a fulltext query).
+    #
+    # ==== Example
+    #
+    #   post = Post.first
+    #   Sunspot.more_like_this(post, Post, Page) do
+    #     fields :title, :body
+    #     with(:updated_at).greater_than(1.month.ago)
+    #     facet(:category_ids)
+    #   end
+    #
+    #
     def more_like_this(object, *types, &block)
       session.more_like_this(object, *types, &block)
     end

data/lib/sunspot/dsl.rb

@@ -1,5 +1,5 @@
 %w(fields scope paginatable adjustable field_query standard_query query_facet
-   functional fulltext restriction search more_like_this_query
-   function).each do |file|
+   functional fulltext restriction restriction_with_near search
+   more_like_this_query function).each do |file|
   require File.join(File.dirname(__FILE__), 'dsl', file)
 end

data/lib/sunspot/dsl/field_query.rb

@@ -196,7 +196,7 @@ module Sunspot
             search_facet = @search.add_field_facet(field, options)
             Util.Array(options[:only]).each do |value|
               facet = Sunspot::Query::QueryFacet.new
-              facet.add_restriction(field, Sunspot::Query::Restriction::EqualTo, value)
+              facet.add_positive_restriction(field, Sunspot::Query::Restriction::EqualTo, value)
               @query.add_query_facet(facet)
               search_facet.add_row(value, facet.to_boolean_phrase)
             end
@@ -236,7 +236,7 @@ module Sunspot
                   nil
                 )
               when :none
-                extra_facet.add_restriction(
+                extra_facet.add_positive_restriction(
                   field,
                   Sunspot::Query::Restriction::EqualTo,
                   nil

data/lib/sunspot/dsl/fields.rb

@@ -43,16 +43,6 @@ module Sunspot
         end
       end
 
-      # 
-      # Specify a method or block that returns the geographical coordinates
-      # associated with the document. The object returned must respond to #first
-      # and #last (e.g., a two-element Array); or to #lat and one of #lng, #lon,
-      # or #long
-      #
-      def coordinates(name = nil, &block)
-        @setup.set_coordinates_field(name, &block)
-      end
-
       # 
       # Specify a document-level boost. As with fields, you have the option of
       # passing an attribute name which will be called on each model, or a block

data/lib/sunspot/dsl/restriction.rb

@@ -8,15 +8,15 @@ module Sunspot
     # restriction.
     #
     class Restriction
-      def initialize(field_name, query, negative) #:nodoc:
-        @field_name, @scope, @negative = field_name, query, negative
+      def initialize(field, scope, negative) #:nodoc:
+        @field, @scope, @negative = field, scope, negative
       end
 
       Sunspot::Query::Restriction.names.each do |class_name|
         method_name = Util.snake_case(class_name.to_s)
         module_eval(<<-RUBY, __FILE__, __LINE__ + 1)
-          def #{method_name}(value)
-            @scope.add_restriction(@field_name, Sunspot::Query::Restriction::#{class_name}, value, @negative)
+          def #{method_name}(*value)
+            @scope.add_restriction(@negative, @field, Sunspot::Query::Restriction::#{class_name}, *value)
           end
         RUBY
       end

data/lib/sunspot/dsl/restriction_with_near.rb

@@ -0,0 +1,121 @@
+module Sunspot
+  module DSL
+    class RestrictionWithNear < Restriction
+      def initialize(field, scope, query, negated)
+        super(field, scope, negated)
+        @query = query
+      end
+
+      # 
+      # Perform a Geohash-based location restriction for the given `location`
+      # field. Though this uses the same API as other attribute-field
+      # restrictions, there are several differences between this and other
+      # scoping methods:
+      #
+      # * It can only be called from the top-level query; it cannot be nested
+      #   in a `dynamic`, `any_of`, or `all_of` block. This is because geohash
+      #   queries are not sent to Solr as filter queries like other scopes, but
+      #   rather are part of the fulltext query sent to Solr.
+      # * Because it is included with the fulltext query (if any), location
+      #   restrictions can be given boost. By default, an "exact"
+      #   (maximum-precision) match will give the result a boost of 1.0; each
+      #   lower level of precision gives a boost of 1/2 the next highest
+      #   precision. See below for options to modify this behavior.
+      #
+      # ==== What is a Geohash?
+      #
+      # Geohash is a clever algorithm that creates a decodable digest of a
+      # geographical point. It does this by dividing the globe into
+      # quadrants, encoding the quadrant in which the point sits in the hash,
+      # dividing the quadrant into smaller quadrants, and repeating an arbitrary
+      # number of times (the "precision"). Because of the way Geohash are
+      # built, the shared Geohash prefix length of two locations will
+      # <em>usually</em> increase as the distance between the points decreases.
+      # Put another way, the geohashes of two nearby points will
+      # <em>usually</em> have a longer shared prefix than two points which are
+      # distant from one another.
+      #
+      # Read more about Geohashes on
+      # {Wikipedia}[http://en.wikipedia.org/wiki/Geohash] or play around with
+      # generating your own at {geohash.org}[http://geohash.org/].
+      #
+      # In Sunspot, GeoHashes can have a precision between 3 and 12; this is the
+      # number of characters in the hash. The precisions have the following
+      # maximum bounding box sizes, in miles:
+      #
+      # <dt>3</dt>
+      # <dd>389.07812</dd>
+      # <dt>4</dt>
+      # <dd>97.26953</dd>
+      # <dt>5</dt>
+      # <dd>24.31738</dd>
+      # <dt>6</dt>
+      # <dd>6.07935</dd>
+      # <dt>7</dt>
+      # <dd>1.51984
+      # <dt>8</dt>
+      # <dd>0.37996</dd>
+      # <dt>9</dt>
+      # <dd>0.09499</dd>
+      # <dt>10</dt>
+      # <dd>0.02375</dd>
+      # <dt>11</dt>
+      # <dd>0.00594</dd>
+      # <dt>12</dt>
+      # <dd>0.00148</dd>
+      #
+      # ==== Score, boost, and sorting with location search
+      #
+      # The concept of relevance scoring is a familiar one from fulltext search;
+      # Solr (or Lucene, actually) gives each result document a score based on
+      # how relevant the document's text is to the search phrase. Sunspot's
+      # location search also uses scoring to determine geographical relevance;
+      # using boosts, longer prefix matches (which are, in general,
+      # geographically closer to the search origin) are assigned higher
+      # relevance. This means that the results of a pure location search are
+      # <em>roughly</em> in order of geographical distance, as long as no other
+      # sort is specified explicitly.
+      #
+      # This geographical relevance plays on the same field as fulltext scoring;
+      # if you use both fulltext and geographical components in a single search,
+      # both types of relevance will be taken into account when scoring the
+      # matches. Thus, a very close fulltext match that's further away from the
+      # geographical origin will be scored similarly to a less precise fulltext
+      # match that is very close to the geographical origin. That's likely to be
+      # consistent with the way most users would expect a fulltext geographical
+      # search to work.
+      #
+      # ==== Options
+      #
+      # <dt><code>:precision</code></dt>
+      # <dd>The minimum precision at which locations should match. See the table
+      # of precisions and bounding-box sizes above; the proximity value will
+      # ensure that all matching documents share a bounding box of the
+      # corresponding maximum size with your origin point. The default value
+      # is 7, meaning all results will share a bounding box with edges of
+      # about one and a half miles with the origin.</dd>
+      # <dt><code>:boost</code></dt>
+      # <dd>The boost to apply to maximum-precision matches. Default is 1.0. You
+      # can use this option to adjust the weight given to geographic
+      # proximity versus fulltext matching, if you are doing both in a
+      # search.</dd>
+      # <dt><code>:precision_factor</code></dt>
+      # <dd>This option determines how much boost is applied to matches at lower
+      # precisions. The default value, 16.0, means that a match at precision
+      # N is 1/16 as relevant as a match at precision N+1 (this is consistent
+      # with the fact that each precision's bounding box is about sixteen
+      # times the size of the next highest precision.)</dd>
+      #
+      # ==== Example
+      #
+      #   Sunspot.search(Post) do
+      #     fulltext('pizza')
+      #     with(:location).near(-40.0, -70.0, :boost => 2, :precision => 6)
+      #   end
+      #
+      def near(lat, lng, options = {})
+        @query.fulltext.add_location(@field, lat, lng, options)
+      end
+    end
+  end
+end

data/lib/sunspot/dsl/scope.rb

@@ -15,24 +15,35 @@ module Sunspot
       end
 
       # 
-      # Build a positive restriction. With one argument, this method returns
-      # another DSL object which presents methods for attaching various
-      # restriction types. With two arguments, this creates a shorthand
-      # restriction: if the second argument is a scalar, an equality restriction
-      # is created; if it is a Range, a between restriction will be created; and
-      # if it is an Array, an any_of restriction will be created.
-      #
-      # ==== Parameters
+      # Build a positive restriction. This method can take three forms: equality
+      # restriction, restriction by another restriction, or identity
+      # restriction.
+      # In the first two forms, the first argument is a field name. If only a
+      # field name is specified, this method returns another DSL object which
+      # presents methods for attaching various restriction types.
+      # With two arguments, this creates a shorthand restriction: if the second
+      # argument is a scalar, an equality restriction is created; if it is a
+      # Range, a between restriction will be created; and if it is an Array, an
+      # any_of restriction will be created.
+      # The third from restricts the search results to a specific instance.
+      #
+      # ==== Parameters (restriction by field value)
       #
       # field_name<Symbol>:: Name of the field on which to place the restriction
       # value<Object,Range,Array>::
       #   If passed, creates an equality, range, or any-of restriction based on
       #   the type of value passed.
       #
+      # ==== Parameters (restriction by identity)
+      #
+      # args<Object>...::
+      #   One or more instances that should be included in the results
+      #
       # ==== Returns
       #
       # Sunspot::DSL::Query::Restriction::
-      #   Restriction DSL object (if only one argument is passed)
+      #   Restriction DSL object (if only one argument is passed which is a
+      #   field name)
       #
       # ==== Examples
       #
@@ -60,71 +71,22 @@ module Sunspot
       #     with(:average_rating).greater_than(3.0)
       #   end
       #
-      def with(field_name, value = NONE)
-        if value == NONE
-          DSL::Restriction.new(@setup.field(field_name.to_sym), @scope, false)
-        else
-          @scope.add_shorthand_restriction(@setup.field(field_name), value)
-        end
-      end
-
-      # 
-      # Build a negative restriction (exclusion). This method can take three
-      # forms: equality exclusion, exclusion by another restriction, or identity
-      # exclusion. The first two forms work the same way as the #with method;
-      # the third excludes a specific instance from the search results.
-      #
-      # ==== Parameters (exclusion by field value)
-      #
-      # field_name<Symbol>:: Name of the field on which to place the exclusion
-      # value<Symbol>::
-      #   If passed, creates an equality exclusion with this value
-      #
-      # ==== Parameters (exclusion by identity)
-      #
-      # args<Object>...::
-      #   One or more instances that should be excluded from the results
-      #
-      # ==== Examples
-      #
-      # An equality exclusion:
-      #
-      #   Sunspot.search(Post) do
-      #     without(:blog_id, 1)
-      #   end
-      # 
-      # Other restriction types:
+      # Restriction by identity:
       #
       #   Sunspot.search(Post) do
-      #     without(:average_rating).greater_than(3.0)
+      #     with(some_post_instance)
       #   end
       #
-      # Exclusion by identity:
+      def with(*args)
+        add_restriction(false, *args)
+      end
+
       #
-      #   Sunspot.search(Post) do
-      #     without(some_post_instance)
-      #   end
+      # Build a negative restriction (exclusion). This method works the same way
+      # asthe #with method.
       #
       def without(*args)
-        case args.first
-        when String, Symbol
-          field_name = args[0]
-          value = args.length > 1 ? args[1] : NONE
-          if value == NONE
-            DSL::Restriction.new(@setup.field(field_name.to_sym), @scope, true)
-          else
-            @scope.add_negated_shorthand_restriction(@setup.field(field_name.to_sym), value)
-          end
-        else
-          instances = args
-          instances.flatten.each do |instance|
-            @scope.add_negated_restriction(
-              IdField.instance,
-              Sunspot::Query::Restriction::EqualTo,
-              Sunspot::Adapters::InstanceAdapter.adapt(instance).index_id
-            )
-          end
-        end
+        add_restriction(true, *args)
       end
 
       # 
@@ -224,6 +186,32 @@ module Sunspot
           &block
         )
       end
+
+      private
+
+      def add_restriction(negated, *args)
+        case args.first
+        when String, Symbol
+          raise ArgumentError if args.length > 2
+          field_name = args[0]
+          value = args.length > 1 ? args[1] : NONE
+          if value == NONE
+            DSL::Restriction.new(@setup.field(field_name.to_sym), @scope, negated)
+          else
+            @scope.add_shorthand_restriction(negated, @setup.field(field_name.to_sym), value)
+          end
+        else
+          instances = args.flatten
+          @scope.add_restriction(
+            negated,
+            IdField.instance,
+            Sunspot::Query::Restriction::AnyOf,
+            instances.flatten.map { |instance|
+              Sunspot::Adapters::InstanceAdapter.adapt(instance).index_id }
+          )
+        end
+      end
+
     end
   end
 end