outoftime-sunspot 0.7.3 → 0.8.0

data/lib/sunspot/query.rb

@@ -1,92 +1,124 @@
+%w(dynamic_query field_facet pagination restriction sort).each do |file|
+  require File.join(File.dirname(__FILE__), 'query', file)
+end
+
 module Sunspot
   # 
   # This class encapsulates a query that is to be sent to Solr. The query is
   # constructed in the block passed to the Sunspot.search method, using the
-  # Sunspot::DSL::Query interface. Instances of Query, as well as all of the
-  # components it contains, respond to the #to_params method, which returns
-  # a hash of parameters in the format recognized by the solr-ruby API.
+  # Sunspot::DSL::Query interface. It can also be accessed directly by calling
+  # #query on a Search object (presumably a not-yet-run one created using
+  # Sunspot#new_search), which might be more suitable than the DSL when an
+  # intermediate object has responsibility for building the query dynamically.
+  #--
+  # Instances of Query, as well as all of the components it contains, respond to
+  # the #to_params method, which returns a hash of parameters in the format
+  # recognized by the solr-ruby API.
   #
-  class Query #:nodoc:
+  class Query
     attr_writer :keywords # <String> full-text keyword boolean phrase
 
-    def initialize(types, params, configuration)
+    def initialize(types, configuration) #:nodoc:
       @types, @configuration = types, configuration
-      @rows = @configuration.pagination.default_per_page
-      apply_params(params)
+      @components = []
+      @components << @pagination = Pagination.new(@configuration)
     end
 
     # 
-    # Representation of this query as solr-ruby parameters. Constructs the hash
-    # by deep-merging scope and facet parameters, adding in various other
-    # parameters from instance data.
-    #
-    # Note that solr-ruby takes the :q parameter as a separate argument; for
-    # the sake of consistency, the Query object ignores this fact (the Search
-    # object extracts it back out).
-    #
-    # ==== Returns
-    #
-    # Hash:: Representation of query in solr-ruby form
-    #
-    def to_params
-      params = {}
-      query_components = []
-      query_components << @keywords if @keywords
-      query_components << types_phrase if types_phrase
-      params[:q] = query_components.map { |component| "(#{component})"} * ' AND '
-      params[:sort] = @sort if @sort
-      params[:start] = @start if @start
-      params[:rows] = @rows if @rows
-      for component in components
-        Util.deep_merge!(params, component.to_params)
-      end
-      params
-    end
-
+    # Add a restriction to the query.
     # 
-    # Add a query component
-    #
     # ==== Parameters
     #
-    # component<~to_params>::  A restriction query component
+    # field_name<Symbol>:: Name of the field to which the restriction applies
+    # restriction_type<Class,Symbol>::
+    #   Subclass of Sunspot::Query::Restriction::Base, or snake_cased name as symbol
+    #   (e.g., +:equal_to+)
+    # value<Object>::
+    #   Value against which the restriction applies (e.g. less_than(2) has a
+    #   value of 2)
+    # negated::
+    #   Whether this restriction should be negated (use add_negated_restriction)
     #
-    def add_component(component)
-      components << component
+    def add_restriction(field_name, restriction_type, value, negated = false)
+      if restriction_type.is_a?(Symbol)
+        restriction_type = Restriction[restriction_type]
+      end
+      @components << restriction = restriction_type.new(field(field_name), value, negated)
+      restriction
     end
 
     # 
-    # Add instance of Sunspot::Restriction::Base to query components. This
-    # method is exposed to the DSL because the Query instance holds field
-    # definitions and is able to translate field names into full field
-    # definitions, and memoize # the result.
-    # 
+    # Add a negated restriction to the query. The restriction will be taken as
+    # the opposite of its usual meaning (e.g., an :equal_to restriction will
+    # be "not equal to".
+    #
     # ==== Parameters
     #
     # field_name<Symbol>:: Name of the field to which the restriction applies
-    # restriction_clazz<Class>::
-    #   Subclass of Sunspot::Restriction::Base to instantiate
+    # restriction_type<Class>::
+    #   Subclass of Sunspot::Query::Restriction::Base to instantiate
     # value<Object>::
     #   Value against which the restriction applies (e.g. less_than(2) has a
     #   value of 2)
-    # negative:: Whether this restriction should be negated
     #
-    # ==== Returns
+    def add_negated_restriction(field_name, restriction_type, value)
+      add_restriction(field_name, restriction_type, value, true)
+    end
+
     #
-    # Sunspot::Restriction::Base:: Restriction instance
+    # Exclude a particular instance from the search results
     #
-    def add_restriction(field_name, restriction_clazz, value, negative = false)
-      add_component(restriction_clazz.new(field(field_name), value, negative))
+    # ==== Parameters
+    #
+    # instance<Object>:: instance to exclude from results
+    #
+    def exclude_instance(instance)
+      @components << Restriction::SameAs.new(instance, true)
     end
 
     # 
-    # Add a field facet
+    # Add a field facet. See Sunspot::Facet for more information.
     #
     # ==== Parameters
     #
     # field_name<Symbol>:: Name of the field on which to get a facet
     #
     def add_field_facet(field_name)
-      add_component(Facets::FieldFacet.new(field(field_name)))
+      @components << FieldFacet.new(field(field_name))
+    end
+
+    # 
+    # Generate a DynamicQuery instance for the given base name.
+    # This gives you access to a subset of the Query API but the operations
+    # apply to dynamic fields inside the dynamic field definition specified
+    # by +base_name+.
+    # 
+    # ==== Parameters
+    # 
+    # base_name<Symbol>::
+    #   Base name of the dynamic field definition to use in the dynamic query
+    #   operations
+    #
+    # ==== Returns
+    #
+    # DynamicQuery::
+    #   Instance providing dynamic query functionality for the given field
+    #   definitions.
+    #
+    def dynamic_query(base_name)
+      DynamicQuery.new(dynamic_field(base_name), self)
+    end
+
+    # 
+    # Add a component to the query. Used by objects that proxy to the query
+    # object.
+    # 
+    # ==== Parameters
+    # 
+    # component<~to_params>:: Query component to add.
+    # 
+    def add_component(component) #:nodoc:
+      @components << component
     end
 
     #
@@ -100,9 +132,7 @@ module Sunspot
     #   Sunspot.config.pagination.default_per_page
     #
     def paginate(page, per_page = nil)
-      per_page ||= @configuration.pagination.default_per_page
-      @start = (page - 1) * per_page
-      @rows = per_page
+      @pagination.page, @pagination.per_page = page, per_page
     end
 
     # 
@@ -114,8 +144,44 @@ module Sunspot
     # direction<Symbol>:: :asc or :desc (default :asc)
     #
     def order_by(field_name, direction = nil)
-      direction ||= :asc
-      (@sort ||= []) << { field(field_name).indexed_name.to_sym => (direction.to_s == 'asc' ? :ascending : :descending) }
+      @components << Sort.new(field(field_name), direction)
+    end
+
+    # 
+    # Build the query using the DSL block passed into Sunspot.search
+    #
+    # ==== Returns
+    #
+    # Sunspot::Query:: self
+    #
+    def build(&block)
+      Util.instance_eval_or_call(dsl, &block)
+      self
+    end
+
+    # 
+    # Representation of this query as solr-ruby parameters. Constructs the hash
+    # by deep-merging scope and facet parameters, adding in various other
+    # parameters from instance data.
+    #
+    # Note that solr-ruby takes the :q parameter as a separate argument; for
+    # the sake of consistency, the Query object ignores this fact (the Search
+    # object extracts it back out).
+    #
+    # ==== Returns
+    #
+    # Hash:: Representation of query in solr-ruby form
+    #
+    def to_params #:nodoc:
+      params = {}
+      query_components = []
+      query_components << @keywords if @keywords
+      query_components << types_phrase if types_phrase
+      params[:q] = query_components.map { |component| "(#{component})"} * ' AND '
+      for component in @components
+        Util.deep_merge!(params, component.to_params)
+      end
+      params
     end
 
     # 
@@ -126,12 +192,8 @@ module Sunspot
     #
     # Integer:: Page number
     #
-    def page
-      if @start && @rows
-        @start / @rows + 1
-      else
-        1
-      end
+    def page #:nodoc:
+      @pagination.page
     end
 
     #
@@ -142,8 +204,8 @@ module Sunspot
     #
     # Integer:: Rows per page
     #
-    def per_page
-      @rows
+    def per_page #:nodoc:
+      @pagination.per_page
     end
 
     # 
@@ -153,7 +215,7 @@ module Sunspot
     #
     # Sunspot::DSL::Query:: DSL instance
     #
-    def dsl
+    def dsl #:nodoc:
       @dsl ||= DSL::Query.new(self)
     end
 
@@ -173,20 +235,70 @@ module Sunspot
     # ArgumentError::
     #   If the given field name is not configured for the types being queried
     #
-    def field(field_name)
+    def field(field_name) #:nodoc:
       fields_hash[field_name.to_sym] || raise(UnrecognizedFieldError, "No field configured for #{@types * ', '} with name '#{field_name}'")
     end
 
-    private
+    def dynamic_field(field_name)
+      field = dynamic_fields_hash[field_name.to_sym] || raise(UnrecognizedFieldError, "No dynamic field configured for #{@types * ', '} with name #{field_name.inspect}")
+    end
 
-    # ==== Returns
-    #
-    # Array:: Collection of query components
-    #
-    def components
-      @components ||= []
+    # 
+    # Pass in search options as a hash. This is not the preferred way of
+    # building a Sunspot search, but it is made available as experience shows
+    # Ruby developers like to pass in hashes. Probably nice for quick one-offs
+    # on the console, anyway.
+    #
+    # ==== Options (+options+)
+    #
+    # :keywords:: Keyword string for fulltext search
+    # :conditions::
+    #   Hash of key-value pairs, where keys are field names, and values are one
+    #   of scalar, Array, or Range. Scalars are evaluated as EqualTo
+    #   restrictions; Arrays are AnyOf restrictions, and Ranges are Between
+    #   restrictions.
+    # :order::
+    #   Order the search results. Either a string or array of strings of the
+    #   form "field_name direction"
+    # :page::
+    #   Page to use for pagination
+    # :per_page::
+    #   Number of results to show per page
+    #
+    def options=(options) #:nodoc:
+      if options.has_key?(:keywords)
+        self.keywords = options[:keywords]
+      end
+      if options.has_key?(:conditions)
+        options[:conditions].each_pair do |field_name, value|
+          begin
+            restriction_type =
+              case value
+              when Array
+                Restriction::AnyOf
+              when Range
+                Restriction::Between
+              else
+                Restriction::EqualTo
+              end
+            add_restriction(field_name, restriction_type, value)
+          rescue UnrecognizedFieldError
+            # ignore fields we don't recognize
+          end
+        end
+      end
+      if options.has_key?(:order)
+        for order in Array(options[:order])
+          order_by(*order.split(' '))
+        end
+      end
+      if options.has_key?(:page)
+        paginate(options[:page], options[:per_page])
+      end
     end
 
+    private
+
     # 
     # Boolean phrase that restricts results to objects of the type(s) under
     # query. If this is an open query (no types specified) then it sends a
@@ -218,55 +330,43 @@ module Sunspot
     # Hash:: field names keyed to field objects
     #
     def fields_hash
-      @fields_hash ||= begin
-        fields_hash = @types.inject({}) do |hash, type|
-          Setup.for(type).fields.each do |field|
-            (hash[field.name.to_sym] ||= {})[type.name] = field
+      @fields_hash ||=
+        begin
+          fields_hash = @types.inject({}) do |hash, type|
+            Setup.for(type).fields.each do |field|
+              (hash[field.name.to_sym] ||= {})[type.name] = field
+            end
+            hash
           end
-          hash
-        end
-        fields_hash.each_pair do |field_name, field_configurations_hash|
-          if @types.any? { |type| field_configurations_hash[type.name].nil? } # at least one type doesn't have this field configured
-            fields_hash.delete(field_name)
-          elsif field_configurations_hash.values.map { |configuration| configuration.indexed_name }.uniq.length != 1 # fields with this name have different configs
-            fields_hash.delete(field_name)
-          else
-            fields_hash[field_name] = field_configurations_hash.values.first
+          fields_hash.each_pair do |field_name, field_configurations_hash|
+            if @types.any? { |type| field_configurations_hash[type.name].nil? } # at least one type doesn't have this field configured
+              fields_hash.delete(field_name)
+            elsif field_configurations_hash.values.map { |configuration| configuration.indexed_name }.uniq.length != 1 # fields with this name have different configs
+              fields_hash.delete(field_name)
+            else
+              fields_hash[field_name] = field_configurations_hash.values.first
+            end
           end
         end
-      end
     end
 
-    def apply_params(params)
-      if params.has_key?(:keywords)
-        self.keywords = params[:keywords]
-      end
-      if params.has_key?(:conditions)
-        params[:conditions].each_pair do |field_name, value|
-          begin
-            restriction_type =
-              case value
-              when Array
-                Restriction::AnyOf
-              when Range
-                Restriction::Between
-              else
-                Restriction::EqualTo
-              end
-            add_restriction(field_name, restriction_type, value)
-          rescue UnrecognizedFieldError
-            # ignore fields we don't recognize
+    def dynamic_fields_hash
+      @dynamic_fields_hash ||=
+        begin
+          dynamic_fields_hash = @types.inject({}) do |hash, type|
+            Setup.for(type).dynamic_fields.each do |field|
+              (hash[field.name.to_sym] ||= {})[type.name] = field
+            end
+            hash
+          end
+          dynamic_fields_hash.each_pair do |field_name, field_configurations_hash|
+            if @types.any? { |type| field_configurations_hash[type.name].nil? }
+              dynamic_fields_hash.delete(field_name)
+            else
+              dynamic_fields_hash[field_name] = field_configurations_hash.values.first
+            end
           end
         end
-      end
-      if params.has_key?(:order)
-        for order in Array(params[:order])
-          order_by(*order.split(' '))
-        end
-      end
-      if params.has_key?(:page)
-        paginate(params[:page], params[:per_page])
-      end
     end
   end
 end

data/lib/sunspot/search.rb

@@ -5,14 +5,18 @@ module Sunspot
   # Instances of Search are returned by the Sunspot.search method.
   #
   class Search
+    # Objects of this class are returned by the #raw_results method.
     RawResult = Struct.new(:class_name, :primary_key)
 
-    def initialize(connection, configuration, *types, &block) #:nodoc:
+    # Query information for this search. If you wish to build the query without
+    # using the search DSL, this method allows you to access the query API
+    # directly. See Sunspot#new_search for how to construct the search object
+    # in this case.
+    attr_reader :query 
+
+    def initialize(connection, query) #:nodoc:
       @connection = connection
-      params = types.last.is_a?(Hash) ? types.pop : {}
-      @query = Query.new(types, params, configuration)
-      @query.dsl.instance_eval(&block) if block
-      @types = types
+      @query = query
     end
 
     #
@@ -88,6 +92,40 @@ module Sunspot
         end
     end
 
+    # 
+    # Get the facet object for a given dynamic field. This dynamic field will
+    # need to have been requested as a field facet inside the search block.
+    #
+    # ==== Parameters
+    #
+    # base_name<Symbol>::
+    #   Base name of the dynamic field definiton (as specified in the setup
+    #   block)
+    # dynamic_name<Symbol>::
+    #   Dynamic field name to facet on
+    # 
+    # ==== Returns
+    #
+    # Sunspot::Facet:: Facet object for given dynamic field
+    # 
+    # ==== Example
+    #
+    #   search = Sunspot.search(Post) do
+    #     dynamic :custom do
+    #       facet :cuisine
+    #     end
+    #   end
+    #   search.dynamic_facet(:custom, :cuisine)
+    #     #=> Facet for the dynamic field :cuisine in the :custom field definition
+    # 
+    def dynamic_facet(base_name, dynamic_name)
+      (@dynamic_facets_cache ||= {})[[base_name.to_sym, dynamic_name.to_sym]] ||=
+        begin
+          field = @query.dynamic_field(base_name).build(dynamic_name)
+          Facet.new(@solr_result.field_facets(field.indexed_name), field)
+        end
+    end
+
     private
 
     # 

data/lib/sunspot/session.rb

@@ -22,12 +22,23 @@ module Sunspot
       @updates = 0
     end
 
+    # 
+    # See Sunspot.new_search
+    #
+    def new_search(*types)
+      types.flatten!
+      Search.new(connection, Query.new(types, @config))
+    end
+
     #
     # See Sunspot.search
     #
     def search(*types, &block)
-      types.flatten!
-      Search.new(connection, @config, *types, &block).execute!
+      options = types.last.is_a?(Hash) ? types.pop : {}
+      search = new_search(*types)
+      search.query.build(&block) if block
+      search.query.options = options
+      search.execute!
     end
 
     #
@@ -37,7 +48,7 @@ module Sunspot
       objects.flatten!
       @updates += objects.length
       for object in objects
-        setup_for(object).indexer(connection).add(object)
+        indexer_for(object).add(object)
       end
     end
 
@@ -50,7 +61,7 @@ module Sunspot
     end
 
     #
-    # See Sunspot.commit!
+    # See Sunspot.commit
     #
     def commit
       @updates = 0
@@ -64,7 +75,7 @@ module Sunspot
       objects.flatten!
       @updates += objects.length
       for object in objects
-        setup_for(object).indexer(connection).remove(object)
+        indexer_for(object).remove(object)
       end
     end
 
@@ -131,6 +142,10 @@ module Sunspot
       Setup.for(object.class) || raise(NoSetupError, "Sunspot is not configured for #{object.class.inspect}")
     end
 
+    def indexer_for(object)
+      setup_for(object).indexer(connection)
+    end
+
     # 
     # Retrieve the Solr connection for this session, creating one if it does not
     # already exist.

data/lib/sunspot/setup.rb

@@ -6,7 +6,7 @@ module Sunspot
   class Setup #:nodoc:
     def initialize(clazz)
       @class_name = clazz.name
-      @fields, @text_fields = [], []
+      @fields, @text_fields, @dynamic_fields = [], [], []
       @dsl = DSL::Fields.new(self)
     end
 
@@ -32,6 +32,17 @@ module Sunspot
       @text_fields.concat(Array(fields))
     end
 
+    #
+    # Add dynamic fields
+    #
+    # ==== Parameters
+    # 
+    # fields<Array>:: Array of dynamic field objects
+    # 
+    def add_dynamic_fields(fields)
+      @dynamic_fields.concat(Array(fields))
+    end
+
     # 
     # Builder method for evaluating the setup DSL
     #
@@ -47,9 +58,7 @@ module Sunspot
     # Array:: Collection of all fields associated with this setup
     #
     def fields
-      fields = @fields.dup
-      fields.concat(parent.fields) if parent
-      fields
+      get_inheritable_collection(:fields)
     end
 
     # 
@@ -61,21 +70,32 @@ module Sunspot
     # Array:: Collection of all text fields associated with this setup
     #
     def text_fields
-      text_fields = @text_fields.dup
-      text_fields.concat(parent.text_fields) if parent
-      text_fields
+      get_inheritable_collection(:text_fields)
     end
 
     # 
-    # Get all scope and text fields associated with this setup as well as all
-    # inherited fields
+    # Get all static, dynamic, and text fields associated with this setup as
+    # well as all inherited fields
     #
     # ==== Returns
     #
     # Array:: Collection of all text and scope fields associated with this setup
     #
     def all_fields
-      fields + text_fields
+      all_fields = []
+      all_fields.concat(fields).concat(text_fields).concat(dynamic_fields)
+      all_fields
+    end
+
+    # 
+    # Get all dynamic fields for this and parent setups
+    # 
+    # ==== Returns
+    #
+    # Array:: Dynamic fields
+    #
+    def dynamic_fields
+      get_inheritable_collection(:dynamic_fields)
     end
 
     # 
@@ -84,6 +104,7 @@ module Sunspot
     # ==== Returns
     #
     # Sunspot::Indexer:: Indexer configured with this setup
+    #
     def indexer(connection)
       Indexer.new(connection, self)
     end
@@ -112,6 +133,14 @@ module Sunspot
       Setup.for(clazz.superclass)
     end
 
+    private
+
+    def get_inheritable_collection(name)
+      collection = instance_variable_get(:"@#{name}").dup
+      collection.concat(parent.send(name)) if parent
+      collection
+    end
+
     class <<self
       # 
       # Retrieve or create the Setup instance for the given class, evaluating