dpickett-thinking-sphinx 1.1.4

data/lib/thinking_sphinx/field.rb

@@ -0,0 +1,172 @@
+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
+    attr_accessor :alias, :columns, :sortable, :associations, :model, :infixes,
+      :prefixes, :faceted
+    
+    # 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
+    #
+    # 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(columns, options = {})
+      @columns      = Array(columns)
+      @associations = {}
+
+      raise "Cannot define a field with no columns. Maybe you are trying to index a field with a reserved name (id, name). You can fix this error by using a symbol rather than a bare name (:id instead of id)." if @columns.empty? || @columns.any? { |column| !column.respond_to?(:__stack) }
+      
+      @alias    = options[:as]
+      @sortable = options[:sortable] || false
+      @infixes  = options[:infixes]  || false
+      @prefixes = options[:prefixes] || false
+      @faceted  = options[:facet]    || false
+    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
+      clause = @columns.collect { |column|
+        column_with_prefix(column)
+      }.join(', ')
+      
+      clause = adapter.concatenate(clause) if concat_ws?
+      clause = adapter.group_concatenate(clause) if is_many?
+      
+      "#{adapter.cast_to_string clause } AS #{quote_column(unique_name)}"
+    end
+    
+    # Get the part of the GROUP BY clause related to this field - if one is
+    # needed. If not, all you'll get back is nil. The latter will happen if
+    # there's multiple data values (read: a has_many or has_and_belongs_to_many
+    # association).
+    #
+    def to_group_sql
+      case
+      when is_many?, ThinkingSphinx.use_group_by_shortcut?
+        nil
+      else
+        @columns.collect { |column|
+          column_with_prefix(column)
+        }
+      end
+    end
+    
+    # Returns the unique name of the field - which is either the alias of
+    # the field, or the name of the only column - if there is only one. If
+    # there isn't, there should be an alias. Else things probably won't work.
+    # Consider yourself warned.
+    #
+    def unique_name
+      if @columns.length == 1
+        @alias || @columns.first.__name
+      else
+        @alias
+      end
+    end
+    
+    def to_facet
+      return nil unless @faceted
+      
+      ThinkingSphinx::Facet.new(self)
+    end
+    
+    private
+    
+    def adapter
+      @adapter ||= @model.sphinx_database_adapter
+    end
+    
+    def quote_column(column)
+      @model.connection.quote_column_name(column)
+    end
+    
+    # Indication of whether the columns should be concatenated with a space
+    # between each value. True if there's either multiple sources or multiple
+    # associations.
+    # 
+    def concat_ws?
+      @columns.length > 1 || multiple_associations?
+    end
+        
+    # Checks whether any column requires multiple associations (which only
+    # happens for polymorphic situations).
+    # 
+    def multiple_associations?
+      associations.any? { |col,assocs| assocs.length > 1 }
+    end
+    
+    # Builds a column reference tied to the appropriate associations. This
+    # dives into the associations hash and their corresponding joins to
+    # figure out how to correctly reference a column in SQL.
+    #
+    def column_with_prefix(column)
+      if column.is_string?
+        column.__name
+      elsif associations[column].empty?
+        "#{@model.quoted_table_name}.#{quote_column(column.__name)}"
+      else
+        associations[column].collect { |assoc|
+          assoc.has_column?(column.__name) ?
+          "#{@model.connection.quote_table_name(assoc.join.aliased_table_name)}" + 
+          ".#{quote_column(column.__name)}" :
+          nil
+        }.compact.join(', ')
+      end
+    end
+    
+    # Could there be more than one value related to the parent record? If so,
+    # then this will return true. If not, false. It's that simple.
+    #
+    def is_many?
+      associations.values.flatten.any? { |assoc| assoc.is_many? }
+    end
+  end
+end

data/lib/thinking_sphinx/index/builder.rb

@@ -0,0 +1,233 @@
+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 (aliased to includes and attribute)
+    # - has (aliased to attribute)
+    # - where
+    # - set_property (aliased to 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
+      class << self
+        # No idea where this is coming from - haven't found it in any ruby or
+        # rails documentation. It's not needed though, so it gets undef'd.
+        # Hopefully the list of methods that get in the way doesn't get too
+        # long.
+        HiddenMethods = [:parent, :name, :id, :type].each { |method|
+          define_method(method) {
+            caller.grep(/irb.completion/).empty? ? method_missing(method) : super
+          }
+        }
+        
+        attr_accessor :fields, :attributes, :properties, :conditions,
+          :groupings
+        
+        # Set up all the collections. Consider this the equivalent of an
+        # instance's initialize method.
+        # 
+        def setup
+          @fields     = []
+          @attributes = []
+          @properties = {}
+          @conditions = []
+          @groupings  = []
+        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|
+            fields << Field.new(FauxColumn.coerce(columns), options)
+            
+            if fields.last.sortable || fields.last.faceted
+              attributes << Attribute.new(
+                fields.last.columns.collect { |col| col.clone },
+                options.merge(
+                  :type => :string,
+                  :as => fields.last.unique_name.to_s.concat("_sort").to_sym
+                ).except(:facet)
+              )
+            end
+          end
+        end
+        alias_method :field,    :indexes
+        alias_method :includes, :indexes
+        
+        # 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 and strings. Don't
+        # forget that Sphinx converts string attributes to integers, which are
+        # useful for sorting, but that's about it.
+        # 
+        # You can also have a collection of integers for 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|
+            attributes << Attribute.new(FauxColumn.coerce(columns), options)
+          end
+        end
+        alias_method :attribute, :has
+        
+        def facet(*args)
+          options = args.extract_options!
+          options[:facet] = true
+          
+          args.each do |columns|
+            attributes << Attribute.new(FauxColumn.coerce(columns), options)
+          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)
+          @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)
+          @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 :include => :picture
+        #   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.
+        # 
+        def set_property(*args)
+          options = args.extract_options!
+          if options.empty?
+            @properties[args[0]] = args[1]
+          else
+            @properties.merge!(options)
+          end
+        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)
+          FauxColumn.new(method)
+        end
+      end
+    end
+  end
+end

data/lib/thinking_sphinx/index/faux_column.rb

@@ -0,0 +1,110 @@
+module ThinkingSphinx
+  class Index
+    # Instances of this class represent database columns and the stack of
+    # associations that lead from the base model to them.
+    # 
+    # The name and stack are accessible through methods starting with __ to
+    # avoid conflicting with the method_missing calls that build the stack.
+    # 
+    class FauxColumn
+      # Create a new column with a pre-defined stack. The top element in the
+      # stack will get shifted to be the name value.
+      # 
+      def initialize(*stack)
+        @name  = stack.pop
+        @stack = stack
+      end
+      
+      def self.coerce(columns)
+        case columns
+        when Symbol, String
+          FauxColumn.new(columns)
+        when Array
+          columns.collect { |col| FauxColumn.coerce(col) }
+        when FauxColumn
+          columns
+        else
+          nil
+        end
+      end
+      
+      # Can't use normal method name, as that could be an association or
+      # column name.
+      # 
+      def __name
+        @name
+      end
+      
+      # Can't use normal method name, as that could be an association or
+      # column name.
+      # 
+      def __stack
+        @stack
+      end
+      
+      # Returns true if the stack is empty *and* if the name is a string -
+      # which is an indication that of raw SQL, as opposed to a value from a
+      # table's column.
+      # 
+      def is_string?
+        @name.is_a?(String) && @stack.empty?
+      end
+      
+      # This handles any 'invalid' method calls and sets them as the name,
+      # and pushing the previous name into the stack. The object returns
+      # itself.
+      # 
+      # If there's a single argument, it becomes the name, and the method
+      # symbol goes into the stack as well. Multiple arguments means new
+      # columns with the original stack and new names (from each argument) gets
+      # returned.
+      # 
+      # Easier to explain with examples:
+      # 
+      #   col = FauxColumn.new :a, :b, :c
+      #   col.__name  #=> :c
+      #   col.__stack #=> [:a, :b]
+      # 
+      #   col.whatever #=> col
+      #   col.__name  #=> :whatever
+      #   col.__stack #=> [:a, :b, :c]
+      #
+      #   col.something(:id) #=> col
+      #   col.__name  #=> :id
+      #   col.__stack #=> [:a, :b, :c, :whatever, :something]
+      #
+      #   cols = col.short(:x, :y, :z)
+      #   cols[0].__name  #=> :x
+      #   cols[0].__stack #=> [:a, :b, :c, :whatever, :something, :short]
+      #   cols[1].__name  #=> :y
+      #   cols[1].__stack #=> [:a, :b, :c, :whatever, :something, :short]
+      #   cols[2].__name  #=> :z
+      #   cols[2].__stack #=> [:a, :b, :c, :whatever, :something, :short]
+      #   
+      # Also, this allows method chaining to build up a relevant stack:
+      # 
+      #   col = FauxColumn.new :a, :b
+      #   col.__name  #=> :b
+      #   col.__stack #=> [:a]
+      # 
+      #   col.one.two.three #=> col
+      #   col.__name  #=> :three
+      #   col.__stack #=> [:a, :b, :one, :two]
+      #
+      def method_missing(method, *args)
+        @stack << @name
+        @name   = method
+        
+        if (args.empty?)
+          self
+        elsif (args.length == 1)
+          method_missing(args.first)
+        else
+          args.collect { |arg|
+            FauxColumn.new(@stack + [@name, arg])
+          }
+        end
+      end
+    end
+  end
+end