thinking-sphinx 2.0.6 → 2.0.7

data/lib/thinking_sphinx/facet.rb

@@ -0,0 +1,128 @@
+module ThinkingSphinx
+  class Facet
+    attr_reader :property, :value_source
+    
+    def initialize(property, value_source = nil)
+      @property     = property
+      @value_source = value_source
+      
+      if property.columns.length != 1
+        raise "Can't translate Facets on multiple-column field or attribute"
+      end
+    end
+
+    def self.name_for(facet)
+      case facet
+      when Facet
+        facet.name
+      when String, Symbol
+        return :class if facet.to_s == 'sphinx_internal_class'
+        facet.to_s.gsub(/(_facet|_crc)$/,'').to_sym
+      end
+    end
+    
+    def self.attribute_name_for(name)
+      name.to_s == 'class' ? 'class_crc' : "#{name}_facet"
+    end
+    
+    def self.attribute_name_from_value(name, value)
+      case value
+      when String
+        attribute_name_for(name)
+      when Array
+        if value.all? { |val| val.is_a?(Integer) }
+          name
+        else
+          attribute_name_for(name)
+        end
+      else
+        name
+      end
+    end
+    
+    def self.translate?(property)
+      return true if property.is_a?(Field)
+      
+      case property.type
+      when :string
+        true
+      when :integer, :boolean, :datetime, :float
+        false
+      when :multi
+        !property.all_ints?
+      end
+    end
+    
+    def name
+      property.unique_name
+    end
+    
+    def attribute_name
+      if translate?
+        Facet.attribute_name_for(@property.unique_name)
+      else
+        @property.unique_name.to_s
+      end
+    end
+    
+    def translate?
+      Facet.translate?(@property)
+    end
+    
+    def type
+      @property.is_a?(Field) ? :string : @property.type
+    end
+    
+    def float?
+      @property.type == :float
+    end
+    
+    def value(object, attribute_hash)
+      attribute_value = attribute_hash['@groupby']
+      return translate(object, attribute_value) if translate? || float?
+      
+      case @property.type
+      when :datetime
+        Time.at(attribute_value)
+      when :boolean
+        attribute_value > 0
+      else
+        attribute_value
+      end
+    end
+    
+    def to_s
+      name
+    end
+    
+    private
+    
+    def translate(object, attribute_value)
+      objects = source_objects(object)
+      return if objects.blank?
+
+      method = value_source || column.__name
+      object = objects.one? ? objects.first : objects.detect { |item|
+        result = item.send(method)
+        result && result.to_crc32 == attribute_value
+      }
+
+      object.try(method)
+    end
+    
+    def source_objects(object)
+      column.__stack.each { |method|
+        object = Array(object).collect { |item|
+          item.send(method)
+        }.flatten.compact
+        
+        return nil if object.empty?
+      }
+      Array(object)
+    end
+    
+    def column
+      @property.columns.first
+    end
+  end
+end

data/lib/thinking_sphinx/facet_search.rb

@@ -0,0 +1,170 @@
+module ThinkingSphinx
+  class FacetSearch < Hash
+    attr_accessor :args, :options
+    
+    def initialize(*args)
+      ThinkingSphinx.context.define_indexes
+      
+      @options      = args.extract_options!
+      @args         = args
+      
+      set_default_options
+      
+      populate
+    end
+    
+    def for(hash = {})
+      for_options = {:with => {}}.merge(options)
+      
+      hash.each do |key, value|
+        attrib = ThinkingSphinx::Facet.attribute_name_from_value(key, value)
+        for_options[:with][attrib] = underlying_value key, value
+      end
+      
+      ThinkingSphinx.search *(args + [for_options])
+    end
+    
+    def facet_names
+      @facet_names ||= begin
+        names = options[:all_facets] ?
+          facet_names_for_all_classes : facet_names_common_to_all_classes
+        
+        names.delete class_facet unless options[:class_facet]
+        names
+      end
+    end
+    
+    private
+    
+    def set_default_options
+      options[:all_facets]  ||= false
+      if options[:class_facet].nil?
+        options[:class_facet] = ((options[:classes] || []).length != 1)
+      end
+    end
+    
+    def populate
+      return if facet_names.empty?
+      
+      ThinkingSphinx::Search.bundle_searches(facet_names) { |sphinx, name|
+        sphinx.search *(args + [facet_search_options(name)])
+      }.each_with_index { |search, index|
+        add_from_results facet_names[index], search
+      }
+    end
+    
+    def facet_search_options(facet_name)
+      options.merge(
+        :group_function => :attr,
+        :limit          => max_matches,
+        :max_matches    => max_matches,
+        :page           => 1,
+        :group_by       => facet_name,
+        :ids_only       => !translate?(facet_name)
+      )
+    end
+    
+    def facet_classes
+      (
+        options[:classes] || ThinkingSphinx.context.indexed_models.collect { |model|
+          model.constantize
+        }
+      ).select { |klass| klass.sphinx_facets.any? }
+    end
+    
+    def all_facets
+      facet_classes.collect { |klass|
+        klass.sphinx_facets
+      }.flatten.select { |facet|
+        options[:facets].blank? || Array(options[:facets]).include?(facet.name)
+      }
+    end
+    
+    def facet_names_for_all_classes
+      all_facets.group_by { |facet|
+        facet.name
+      }.collect { |name, facets|
+        if facets.collect { |facet| facet.type }.uniq.length > 1
+          raise "Facet #{name} exists in more than one model with different types"
+        end
+        facets.first.attribute_name
+      }
+    end
+    
+    def facet_names_common_to_all_classes
+      facet_names_for_all_classes.select { |name|
+        facet_classes.all? { |klass|
+          klass.sphinx_facets.detect { |facet|
+            facet.attribute_name == name
+          }
+        }
+      }
+    end
+    
+    def translate?(name)
+      facet = facet_from_name(name)
+      facet.translate? || facet.float?
+    end
+    
+    def config
+      ThinkingSphinx::Configuration.instance
+    end
+    
+    def max_matches
+      @max_matches ||= config.configuration.searchd.max_matches || 1000
+    end
+    
+    # example: facet = country_facet; name = :country
+    def add_from_results(facet, search)
+      name  = ThinkingSphinx::Facet.name_for(facet)
+      facet = facet_from_name(facet)
+      
+      self[name]  ||= {}
+      
+      return if search.empty?
+      
+      search.each_with_match do |result, match|
+        facet_value = facet.value(result, match[:attributes])
+        
+        self[name][facet_value] ||= 0
+        self[name][facet_value]  += match[:attributes]["@count"]
+      end
+    end
+    
+    def underlying_value(key, value)
+      case value
+      when Array
+        value.collect { |item| underlying_value(key, item) }
+      when String
+        value.to_crc32
+      else
+        value
+      end
+    end
+    
+    def facet_from_object(object, name)
+      facet = nil
+      klass = object.class
+      
+      while klass != ::ActiveRecord::Base && facet.nil?
+        facet = klass.sphinx_facets.detect { |facet|
+          facet.attribute_name == name
+        }
+        klass = klass.superclass
+      end
+      
+      facet
+    end
+    
+    def facet_from_name(name)
+      name = ThinkingSphinx::Facet.name_for(name)
+      all_facets.detect { |facet|
+        facet.name == name
+      }
+    end
+    
+    def class_facet
+      Riddle.loaded_version.to_i < 2 ? 'class_crc' : 'sphinx_internal_class'
+    end
+  end
+end

data/lib/thinking_sphinx/field.rb

@@ -0,0 +1,98 @@
+module ThinkingSphinx
+  # Fields - holding the string data which Sphinx indexes for your searches.
+  # This class isn't really useful to you unless you're hacking around with the
+  # internals of Thinking Sphinx - but hey, don't let that stop you.
+  #
+  # One key thing to remember - if you're using the field manually to
+  # generate SQL statements, you'll need to set the base model, and all the
+  # associations. Which can get messy. Use Index.link!, it really helps.
+  # 
+  class Field < ThinkingSphinx::Property
+    attr_accessor :sortable, :infixes, :prefixes
+    
+    # To create a new field, you'll need to pass in either a single Column
+    # or an array of them, and some (optional) options. The columns are
+    # references to the data that will make up the field.
+    #
+    # Valid options are:
+    # - :as       => :alias_name 
+    # - :sortable => true
+    # - :infixes  => true
+    # - :prefixes => true
+    # - :file     => true
+    # - :with     => :attribute # or :wordcount
+    #
+    # Alias is only required in three circumstances: when there's
+    # another attribute or field with the same name, when the column name is
+    # 'id', or when there's more than one column.
+    # 
+    # Sortable defaults to false - but is quite useful when set to true, as
+    # it creates an attribute with the same string value (which Sphinx converts
+    # to an integer value), which can be sorted by. Thinking Sphinx is smart
+    # enough to realise that when you specify fields in sort statements, you
+    # mean their respective attributes.
+    # 
+    # If you have partial matching enabled (ie: enable_star), then you can
+    # specify certain fields to have their prefixes and infixes indexed. Keep
+    # in mind, though, that Sphinx's default is _all_ fields - so once you
+    # highlight a particular field, no other fields in the index will have
+    # these partial indexes.
+    #
+    # Here's some examples:
+    #
+    #   Field.new(
+    #     Column.new(:name)
+    #   )
+    #
+    #   Field.new(
+    #     [Column.new(:first_name), Column.new(:last_name)],
+    #     :as => :name, :sortable => true
+    #   )
+    # 
+    #   Field.new(
+    #     [Column.new(:posts, :subject), Column.new(:posts, :content)],
+    #     :as => :posts, :prefixes => true
+    #   )
+    # 
+    def initialize(source, columns, options = {})
+      super
+      
+      @sortable = options[:sortable] || false
+      @infixes  = options[:infixes]  || false
+      @prefixes = options[:prefixes] || false
+      @file     = options[:file]     || false
+      @with     = options[:with]
+      
+      source.fields << self
+    end
+    
+    # Get the part of the SELECT clause related to this field. Don't forget
+    # to set your model and associations first though.
+    #
+    # This will concatenate strings if there's more than one data source or
+    # multiple data values (has_many or has_and_belongs_to_many associations).
+    # 
+    def to_select_sql
+      return nil unless available?
+      
+      clause = columns_with_prefixes.join(', ')
+      
+      clause = adapter.concatenate(clause)       if concat_ws?
+      clause = adapter.group_concatenate(clause) if is_many?
+      
+      "#{clause} AS #{quote_column(unique_name)}"
+    end
+    
+    def file?
+      @file
+    end
+    
+    def with_attribute?
+      @with == :attribute
+    end
+    
+    def with_wordcount?
+      @with == :wordcount
+    end
+  end
+end

data/lib/thinking_sphinx/index/builder.rb

@@ -0,0 +1,312 @@
+module ThinkingSphinx
+  class Index
+    # The Builder class is the core for the index definition block processing.
+    # There are four methods you really need to pay attention to:
+    # - indexes
+    # - has
+    # - where
+    # - set_property/set_properties
+    #
+    # The first two of these methods allow you to define what data makes up
+    # your indexes. #where provides a method to add manual SQL conditions, and
+    # set_property allows you to set some settings on a per-index basis. Check
+    # out each method's documentation for better ideas of usage.
+    # 
+    class Builder
+      instance_methods.grep(/^[^_]/).each { |method|
+        next if method.to_s == "instance_eval"
+        define_method(method) {
+          caller.grep(/irb.completion/).empty? ? method_missing(method) : super
+        }
+      }
+      
+      def self.generate(model, name = nil, &block)
+        index  = ThinkingSphinx::Index.new(model)
+        index.name = name unless name.nil?
+        
+        Builder.new(index, &block) if block_given?
+        
+        index.delta_object = ThinkingSphinx::Deltas.parse index
+        index
+      end
+      
+      def initialize(index, &block)
+        @index  = index
+        @explicit_source = false
+        
+        self.instance_eval &block
+        
+        if no_fields?
+          raise "At least one field is necessary for an index"
+        end
+      end
+      
+      def define_source(&block)
+        if @explicit_source
+          @source = ThinkingSphinx::Source.new(@index)
+          @index.sources << @source
+        else
+          @explicit_source = true
+        end
+        
+        self.instance_eval &block
+      end
+      
+      # This is how you add fields - the strings Sphinx looks at - to your
+      # index. Technically, to use this method, you need to pass in some
+      # columns and options - but there's some neat method_missing stuff
+      # happening, so lets stick to the expected syntax within a define_index
+      # block.
+      #
+      # Expected options are :as, which points to a column alias in symbol
+      # form, and :sortable, which indicates whether you want to sort by this
+      # field.
+      #
+      # Adding Single-Column Fields:
+      # 
+      # You can use symbols or methods - and can chain methods together to
+      # get access down the associations tree.
+      # 
+      #   indexes :id, :as => :my_id
+      #   indexes :name, :sortable => true
+      #   indexes first_name, last_name, :sortable => true
+      #   indexes users.posts.content, :as => :post_content
+      #   indexes users(:id), :as => :user_ids
+      #
+      # Keep in mind that if any keywords for Ruby methods - such as id or 
+      # name - clash with your column names, you need to use the symbol
+      # version (see the first, second and last examples above).
+      #
+      # If you specify multiple columns (example #2), a field will be created
+      # for each. Don't use the :as option in this case. If you want to merge
+      # those columns together, continue reading.
+      # 
+      # Adding Multi-Column Fields:
+      # 
+      #   indexes [first_name, last_name], :as => :name
+      #   indexes [location, parent.location], :as => :location
+      #
+      # To combine multiple columns into a single field, you need to wrap
+      # them in an Array, as shown by the above examples. There's no
+      # limitations on whether they're symbols or methods or what level of
+      # associations they come from.
+      # 
+      # Adding SQL Fragment Fields
+      #
+      # You can also define a field using an SQL fragment, useful for when
+      # you would like to index a calculated value.
+      #
+      #   indexes "age < 18", :as => :minor
+      #
+      def indexes(*args)
+        options = args.extract_options!
+        args.each do |columns|
+          field = Field.new(source, FauxColumn.coerce(columns), options)
+          
+          add_sort_attribute  field, options   if field.sortable
+          add_facet_attribute field, options   if field.faceted
+        end
+      end
+      
+      # This is the method to add attributes to your index (hence why it is
+      # aliased as 'attribute'). The syntax is the same as #indexes, so use
+      # that as starting point, but keep in mind the following points.
+      # 
+      # An attribute can have an alias (the :as option), but it is always
+      # sortable - so you don't need to explicitly request that. You _can_
+      # specify the data type of the attribute (the :type option), but the
+      # code's pretty good at figuring that out itself from peering into the
+      # database.
+      # 
+      # Attributes are limited to the following types: integers, floats,
+      # datetimes (converted to timestamps), booleans, strings and MVAs
+      # (:multi). Don't forget that Sphinx converts string attributes to
+      # integers, which are useful for sorting, but that's about it.
+      # 
+      # Collection of integers are known as multi-value attributes (MVAs).
+      # Generally these would be through a has_many relationship, like in this
+      # example:
+      # 
+      #   has posts(:id), :as => :post_ids
+      # 
+      # This allows you to filter on any of the values tied to a specific
+      # record. Might be best to read through the Sphinx documentation to get
+      # a better idea of that though.
+      # 
+      # Adding SQL Fragment Attributes
+      #
+      # You can also define an attribute using an SQL fragment, useful for
+      # when you would like to index a calculated value. Don't forget to set
+      # the type of the attribute though:
+      #
+      #   has "age < 18", :as => :minor, :type => :boolean
+      # 
+      # If you're creating attributes for latitude and longitude, don't
+      # forget that Sphinx expects these values to be in radians.
+      # 
+      def has(*args)
+        options = args.extract_options!
+        args.each do |columns|
+          attribute = Attribute.new(source, FauxColumn.coerce(columns), options)
+          
+          add_facet_attribute attribute, options if attribute.faceted
+        end
+      end
+      
+      def facet(*args)
+        options = args.extract_options!
+        options[:facet] = true
+        
+        args.each do |columns|
+          attribute = Attribute.new(source, FauxColumn.coerce(columns), options)
+          
+          add_facet_attribute attribute, options
+        end
+      end
+      
+      def join(*args)
+        args.each do |association|
+          Join.new(source, association)
+        end
+      end
+      
+      # Use this method to add some manual SQL conditions for your index
+      # request. You can pass in as many strings as you like, they'll get
+      # joined together with ANDs later on.
+      # 
+      #   where "user_id = 10"
+      #   where "parent_type = 'Article'", "created_at < NOW()"
+      # 
+      def where(*args)
+        source.conditions += args
+      end
+      
+      # Use this method to add some manual SQL strings to the GROUP BY
+      # clause. You can pass in as many strings as you'd like, they'll get
+      # joined together with commas later on.
+      # 
+      #   group_by "lat", "lng"
+      # 
+      def group_by(*args)
+        source.groupings += args
+      end
+      
+      # This is what to use to set properties on the index. Chief amongst
+      # those is the delta property - to allow automatic updates to your
+      # indexes as new models are added and edited - but also you can
+      # define search-related properties which will be the defaults for all
+      # searches on the model.
+      # 
+      #   set_property :delta => true
+      #   set_property :field_weights => {"name" => 100}
+      #   set_property :order => "name ASC"
+      #   set_property :select => 'name'
+      # 
+      # Also, the following two properties are particularly relevant for
+      # geo-location searching - latitude_attr and longitude_attr. If your
+      # attributes for these two values are named something other than
+      # lat/latitude or lon/long/longitude, you can dictate what they are
+      # when defining the index, so you don't need to specify them for every
+      # geo-related search.
+      #
+      #   set_property :latitude_attr => "lt", :longitude_attr => "lg"
+      # 
+      # Please don't forget to add a boolean field named 'delta' to your
+      # model's database table if enabling the delta index for it.
+      # Valid options for the delta property are:
+      # 
+      # true
+      # false
+      # :default
+      # :delayed
+      # :datetime
+      # 
+      # You can also extend ThinkingSphinx::Deltas::DefaultDelta to implement 
+      # your own handling for delta indexing.
+      # 
+      def set_property(*args)
+        options = args.extract_options!
+        options.each do |key, value|
+          set_single_property key, value
+        end
+        
+        set_single_property args[0], args[1] if args.length == 2
+      end
+      alias_method :set_properties, :set_property
+      
+      # Handles the generation of new columns for the field and attribute
+      # definitions.
+      # 
+      def method_missing(method, *args)
+        FauxColumn.new(method, *args)
+      end
+      
+      # A method to allow adding fields from associations which have names
+      # that clash with method names in the Builder class (ie: properties,
+      # fields, attributes).
+      # 
+      # Example: indexes assoc(:properties).column
+      # 
+      def assoc(assoc, *args)
+        FauxColumn.new(assoc, *args)
+      end
+      
+      # Use this method to generate SQL for your attributes, conditions, etc.
+      # You can pass in as whatever ActiveRecord::Base.sanitize_sql accepts.
+      # 
+      #   where sanitize_sql(["active = ?", true])
+      #   #=> WHERE active = 1
+      # 
+      def sanitize_sql(*args)
+        @index.model.send(:sanitize_sql, *args)
+      end
+      
+      private
+      
+      def source
+        @source ||= begin
+          source = ThinkingSphinx::Source.new(@index)
+          @index.sources << source
+          source
+        end
+      end
+      
+      def set_single_property(key, value)
+        source_options = ThinkingSphinx::Configuration::SourceOptions
+        if source_options.include?(key.to_s)
+          source.options.merge! key => value
+        else
+          @index.local_options.merge!  key => value
+        end
+      end
+      
+      def add_sort_attribute(field, options)
+        add_internal_attribute field, options, "_sort"
+      end
+      
+      def add_facet_attribute(property, options)
+        add_internal_attribute property, options, "_facet", true
+        @index.model.sphinx_facets << property.to_facet
+      end
+      
+      def add_internal_attribute(property, options, suffix, crc = false)
+        return unless ThinkingSphinx::Facet.translate?(property)
+        
+        Attribute.new(source,
+          property.columns.collect { |col| col.clone },
+          options.merge(
+            :type => property.is_a?(Field) ? :string : options[:type],
+            :as   => property.unique_name.to_s.concat(suffix).to_sym,
+            :crc  => crc
+          ).except(:facet)
+        )
+      end
+      
+      def no_fields?
+        @index.sources.empty? || @index.sources.any? { |source|
+          source.fields.length == 0
+        }
+      end
+    end
+  end
+end