sunspot_rails 2.0.0.pre.120720 → 2.0.0.pre.120924

data/sunspot/lib/sunspot/dsl/paginatable.rb

@@ -0,0 +1,32 @@
+module Sunspot
+  module DSL #:nodoc
+    module Paginatable
+      # Paginate your search. This works the same way as WillPaginate's
+      # paginate().
+      #
+      # Note that Solr searches are _always_ paginated. Not calling #paginate is
+      # the equivalent of calling:
+      #
+      #   paginate(:page => 1, :per_page => Sunspot.config.pagination.default_per_page)
+      #
+      # ==== Options (options)
+      #
+      # :page<Integer,String>:: The requested page. The default is 1.
+      #
+      # :per_page<Integer,String>::
+      #   How many results to return per page. The default is the value in
+      #   +Sunspot.config.pagination.default_per_page+
+      #
+      # :offset<Integer,String>::
+      #   Applies a shift to paginated records. The default is 0.
+      #
+      def paginate(options = {})
+        page = options.delete(:page)
+        per_page = options.delete(:per_page)
+        offset = options.delete(:offset)
+        raise ArgumentError, "unknown argument #{options.keys.first.inspect} passed to paginate" unless options.empty?
+        @query.paginate(page, per_page, offset)
+      end
+    end
+  end
+end

data/sunspot/lib/sunspot/dsl/query_facet.rb

@@ -0,0 +1,36 @@
+module Sunspot
+  module DSL
+    # 
+    # This tiny DSL class implements the DSL for the FieldQuery.facet
+    # method.
+    #
+    class QueryFacet
+      def initialize(query, setup, facet, options) #:nodoc:
+        @query, @setup, @facet, @options = query, setup, facet, options
+      end
+
+      # 
+      # Add a row to this query facet. The label argument can be anything; it's
+      # simply the value that's passed into the Sunspot::QueryFacetRow object
+      # corresponding to the row that's created. Use whatever seems most
+      # intuitive.
+      #
+      # The block is evaluated in the context of a Sunspot::DSL::Scope, meaning
+      # any restrictions can be placed on the documents matching this facet row.
+      #
+      # ==== Parameters
+      #
+      # label<Object>::
+      #   An object used to identify this facet row in the results.
+      #
+      def row(label, &block)
+        query_facet = Sunspot::Query::QueryFacet.new(@options)
+        Sunspot::Util.instance_eval_or_call(
+          Scope.new(@query.add_query_facet(query_facet), @setup),
+          &block
+        )
+        @facet.add_row(label, query_facet.to_boolean_phrase)
+      end
+    end
+  end
+end

data/sunspot/lib/sunspot/dsl/restriction.rb

@@ -0,0 +1,25 @@
+module Sunspot
+  module DSL
+    # 
+    # This class presents an API for building restrictions in the query DSL. The
+    # methods exposed are the snake-cased names of the classes defined in the
+    # Sunspot::Restriction module, with the exception of Base. All
+    # methods take a single argument, which is the value to be applied to the
+    # restriction.
+    #
+    class Restriction
+      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(@negative, @field, Sunspot::Query::Restriction::#{class_name}, *value)
+          end
+        RUBY
+      end
+    end
+  end
+end

data/sunspot/lib/sunspot/dsl/restriction_with_near.rb

@@ -0,0 +1,160 @@
+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
+
+      #
+      # Performs a query that is filtered by a radius around a given
+      # latitude and longitude.
+      #
+      # ==== Parameters
+      #
+      # :lat<Numeric>::
+      #   Latitude (in degrees)
+      # :lon<Numeric>::
+      #   Longitude (in degrees)
+      # :radius<Numeric>::
+      #   Radius (in kilometers)
+      #
+      # ==== Options
+      #
+      # <dt><code>:bbox</code></dt>
+      # <dd>If `true`, performs the search using `bbox`. `bbox` is
+      # more performant, but also more inexact (guaranteed to encompass
+      # all of the points of interest, but may also include other points
+      # that are slightly outside of the required distance).</dd>
+      #
+      def in_radius(lat, lon, radius, options = {})
+        @query.add_geo(Sunspot::Query::Geofilt.new(@field, lat, lon, radius, options))
+      end
+
+      #
+      # Performs a query that is filtered by a bounding box
+      #
+      # ==== Parameters
+      # 
+      # :first_corner<Array>::
+      #   First corner (expressed as an array `[latitude, longitude]`)
+      # :second_corner<Array>::
+      #   Second corner (expressed as an array `[latitude, longitude]`)
+      #
+      def in_bounding_box(first_corner, second_corner)
+        @query.add_geo(Sunspot::Query::Bbox.new(@field, first_corner, second_corner))
+      end
+    end
+  end
+end

data/sunspot/lib/sunspot/dsl/scope.rb

@@ -0,0 +1,214 @@
+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::StandardQuery, 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
+      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::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 = @setup.field(args[0].to_sym)
+          if args.length > 1
+            value = args[1]
+            @scope.add_shorthand_restriction(negated, field, value)
+          else # NONE
+            DSL::Restriction.new(field, @scope, negated)
+          end
+        else # args are instances
+          @scope.add_restriction(
+            negated,
+            IdField.instance,
+            Sunspot::Query::Restriction::AnyOf,
+            args.flatten.map { |instance|
+              Sunspot::Adapters::InstanceAdapter.adapt(instance).index_id }
+          )
+        end
+      end
+
+    end
+  end
+end