pduey-sunspot 1.2.1.1

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

@@ -0,0 +1,217 @@
+module Sunspot
+  module DSL #:nodoc:
+    # 
+    # This DSL presents methods for constructing restrictions and other query
+    # elements that are specific to fields. As well as being a superclass of
+    # Sunspot::DSL::Query, which presents the main query block, this DSL class
+    # is also used directly inside the #dynamic() block, which only allows
+    # operations on specific fields.
+    #
+    class Scope
+      NONE = Object.new
+
+      def initialize(scope, setup) #:nodoc:
+        @scope, @setup = scope, setup
+      end
+
+      # 
+      # 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 which is a
+      #   field name)
+      #
+      # ==== Examples
+      #
+      # An equality restriction:
+      #
+      #   Sunspot.search do
+      #     with(:blog_id, 1)
+      #   end
+      #
+      # Restrict by range:
+      #
+      #   Sunspot.search do
+      #     with(:average_rating, 3.0..5.0)
+      #   end
+      #
+      # Restrict by a set of allowed values:
+      #
+      #   Sunspot.search do
+      #     with(:category_ids, [1, 5, 9])
+      #   end
+      # 
+      # Other restriction types:
+      #
+      #   Sunspot.search(Post) do
+      #     with(:average_rating).greater_than(3.0)
+      #   end
+      #
+      # Restriction by identity:
+      #
+      #   Sunspot.search(Post) do
+      #     with(some_post_instance)
+      #   end
+      #
+      def with(*args)
+        add_restriction(false, *args)
+      end
+
+      #
+      # Build a negative restriction (exclusion). This method works the same way
+      # asthe #with method.
+      #
+      def without(*args)
+        add_restriction(true, *args)
+      end
+
+      # 
+      # Create a disjunction, scoping the results to documents that match any
+      # of the enclosed restrictions.
+      #
+      # ==== Example
+      #
+      #   Sunspot.search(Post) do
+      #     any_of do
+      #       with(:expired_at).greater_than Time.now
+      #       with :expired_at, nil
+      #     end
+      #   end
+      #
+      # This will return all documents who either have an expiration time in the
+      # future, or who do not have any expiration time at all.
+      #
+      def any_of(&block)
+        disjunction = @scope.add_disjunction
+        Util.instance_eval_or_call(Scope.new(disjunction, @setup), &block)
+        disjunction
+      end
+
+      # 
+      # Create a conjunction, scoping the results to documents that match all of
+      # the enclosed restrictions. When called from the top level of a search
+      # block, this has no effect, but can be useful for grouping a conjunction
+      # inside a disjunction.
+      #
+      # ==== Example
+      #
+      #   Sunspot.search(Post) do
+      #     any_of do
+      #       with(:blog_id, 1)
+      #       all_of do
+      #         with(:blog_id, 2)
+      #         with(:category_ids, 3)
+      #       end
+      #     end
+      #   end
+      #
+      def all_of(&block)
+        conjunction = @scope.add_conjunction
+        Util.instance_eval_or_call(Scope.new(conjunction, @setup), &block)
+        conjunction
+      end
+
+      #
+      # Apply restrictions, facets, and ordering to dynamic field instances.
+      # The block API is implemented by Sunspot::DSL::FieldQuery, which is a
+      # superclass of the Query DSL (thus providing a subset of the API, in
+      # particular only methods that refer to particular fields).
+      # 
+      # ==== Parameters
+      # 
+      # base_name<Symbol>:: The base name for the dynamic field definition
+      #
+      # ==== Example
+      #
+      #   Sunspot.search Post do
+      #     dynamic :custom do
+      #       with :cuisine, 'Pizza'
+      #       facet :atmosphere
+      #       order_by :chef_name
+      #     end
+      #   end
+      #
+      def dynamic(base_name, &block)
+        Sunspot::Util.instance_eval_or_call(
+          Scope.new(@scope, @setup.dynamic_field_factory(base_name)),
+          &block
+        )
+      end
+
+      # 
+      # Apply scope-type restrictions on fulltext fields. In certain situations,
+      # it may be desirable to place logical restrictions on text fields.
+      # Remember that text fields are tokenized; your mileage may very.
+      #
+      # The block works exactly like a normal scope, except that the field names
+      # refer to text fields instead of attribute fields.
+      # 
+      # === Example
+      #
+      #   Sunspot.search(Post) do
+      #     text_fields do
+      #       with :body, nil
+      #     end
+      #   end
+      #
+      # This will return all documents that do not have a body.
+      #
+      def text_fields(&block)
+        Sunspot::Util.instance_eval_or_call(
+          Scope.new(@scope, TextFieldSetup.new(@setup)),
+          &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

data/lib/sunspot/dsl/search.rb

@@ -0,0 +1,30 @@
+module Sunspot
+  module DSL
+    # 
+    # This top-level DSL class is the context in which the block passed to
+    # Sunspot.query. See Sunspot::DSL::Query, Sunspot::DSL::FieldQuery, and
+    # Sunspot::DSL::Scope for the full API presented.
+    #
+    class Search < StandardQuery
+      def initialize(search, setup) #:nodoc:
+        @search = search
+        super(search, search.query, setup)
+      end
+
+      # 
+      # Retrieve the data accessor used to load instances of the given class
+      # out of persistent storage. Data accessors are free to implement any
+      # extra methods that may be useful in this context.
+      #
+      # ==== Example
+      #
+      #   Sunspot.search Post do
+      #     data_acccessor_for(Post).includes = [:blog, :comments]
+      #   end
+      #
+      def data_accessor_for(clazz)
+        @search.data_accessor_for(clazz)
+      end
+    end
+  end
+end

data/lib/sunspot/dsl/standard_query.rb

@@ -0,0 +1,121 @@
+module Sunspot
+  module DSL #:nodoc:
+    #
+    # This class presents a DSL for constructing queries using the
+    # Sunspot.search method. Methods of this class are available inside the
+    # search block. Much of the DSL's functionality is implemented by this
+    # class's superclasses, Sunspot::DSL::FieldQuery and Sunspot::DSL::Scope
+    #
+    # See Sunspot.search for usage examples
+    #
+    class StandardQuery < FieldQuery
+      include Paginatable, Adjustable
+
+      # Specify a phrase that should be searched as fulltext. Only +text+
+      # fields are searched - see DSL::Fields.text
+      #
+      # Keyword search is executed using Solr's dismax handler, which strikes
+      # a good balance between powerful and foolproof. In particular,
+      # well-matched quotation marks can be used to group phrases, and the
+      # + and - modifiers work as expected. All other special Solr boolean
+      # syntax is escaped, and mismatched quotes are ignored entirely.
+      #
+      # This method can optionally take a block, which is evaluated by the
+      # Fulltext DSL class, and exposes several powerful dismax features.
+      #
+      # ==== Parameters
+      #
+      # keywords<String>:: phrase to perform fulltext search on
+      #
+      # ==== Options
+      #
+      # :fields<Array>::
+      #   List of fields that should be searched for keywords. Defaults to all
+      #   fields configured for the types under search.
+      # :highlight<Boolean,Array>::
+      #   If true, perform keyword highlighting on all searched fields. If an
+      #   array of field names, perform highlighting on the specified fields.
+      #   This can also be called from within the fulltext block.
+      # :minimum_match<Integer>::
+      #   The minimum number of search terms that a result must match. By
+      #   default, all search terms must match; if the number of search terms
+      #   is less than this number, the default behavior applies.
+      # :tie<Float>::
+      #   A tiebreaker coefficient for scores derived from subqueries that are
+      #   lower-scoring than the maximum score subquery. Typically a near-zero
+      #   value is useful. See
+      #   http://wiki.apache.org/solr/DisMaxRequestHandler#tie_.28Tie_breaker.29
+      #   for more information.
+      # :query_phrase_slop<Integer>::
+      #   The number of words that can appear between the words in a
+      #   user-entered phrase (i.e., keywords in quotes) and still match. For
+      #   instance, in a search for "\"great pizza\"" with a phrase slop of 1,
+      #   "great pizza" and "great big pizza" will match, but "great monster of
+      #   a pizza" will not. Default behavior is a query phrase slop of zero.
+      #
+      def fulltext(keywords, options = {}, &block)
+        if keywords && !(keywords.to_s =~ /^\s*$/)
+          fulltext_query = @query.add_fulltext(keywords)
+          if field_names = options.delete(:fields)
+            Util.Array(field_names).each do |field_name|
+              @setup.text_fields(field_name).each do |field|
+                fulltext_query.add_fulltext_field(field, field.default_boost)
+              end
+            end
+          end
+          if minimum_match = options.delete(:minimum_match)
+            fulltext_query.minimum_match = minimum_match.to_i
+          end
+          if tie = options.delete(:tie)
+            fulltext_query.tie = tie.to_f
+          end
+          if query_phrase_slop = options.delete(:query_phrase_slop)
+            fulltext_query.query_phrase_slop = query_phrase_slop.to_i
+          end
+          if highlight_field_names = options.delete(:highlight)
+            if highlight_field_names == true
+              fulltext_query.add_highlight
+            else
+              highlight_fields = []
+              Util.Array(highlight_field_names).each do |field_name|
+                highlight_fields.concat(@setup.text_fields(field_name))
+              end
+              fulltext_query.add_highlight(highlight_fields)
+            end
+          end
+          if block && fulltext_query
+            fulltext_dsl = Fulltext.new(fulltext_query, @setup)
+            Util.instance_eval_or_call(
+              fulltext_dsl,
+              &block
+            )
+          end
+          if !field_names && (!fulltext_dsl || !fulltext_dsl.fields_added?)
+            @setup.all_text_fields.each do |field|
+              unless fulltext_query.has_fulltext_field?(field)
+                unless fulltext_dsl && fulltext_dsl.exclude_fields.include?(field.name)
+                  fulltext_query.add_fulltext_field(field, field.default_boost)
+                end
+              end
+            end
+          end
+        end
+      end
+      alias_method :keywords, :fulltext
+
+      def with(*args)
+        case args.first
+        when String, Symbol
+          field_name = args[0]
+          value = args.length > 1 ? args[1] : Scope::NONE
+          if value == Scope::NONE
+            return DSL::RestrictionWithNear.new(@setup.field(field_name.to_sym), @scope, @query, false)
+          end
+        end
+
+        # else
+        super
+      end
+    end
+  end
+end