ultrasphinx 1.6.7 → 1.7

data/CHANGELOG

@@ -1,4 +1,6 @@
 
+v1.7. Deployment docs. Postgres fixes. Support association_name instead of class_name (Daniel Higginbotham). 
+
 v1.6.7. Fix GROUP_CONCAT aggregate problem. Discourage enable_star in default.base. Allow faceting on includes.
 
 v1.6.6. Only use DISTINCT when necessary to improve indexing speed.

data/DEPLOYMENT_NOTES

@@ -0,0 +1,29 @@
+
+== The configuration files
+
+Please note that the generated <tt>.conf</tt> file in <tt>config/ultrasphinx</tt> should not be modified by hand. This is the configuration for Sphinx itself, and includes all the generated SQL. It is <b>never the same</b> as the <tt>.base</tt> file.
+
+You will want to keep your generated <tt>production.conf</tt> in your repository. You can get a <tt>production.conf</tt> by running:
+
+  RAILS_ENV=production rake ultrasphinx:configure
+    
+If you don't have local read access to the production database, you'll need to write a post-deploy task to generate the configuration server-side. It is important that every checkout of the app has a copy of <tt>production.conf</tt>. It is not enough to only have it on the server where the search daemon is running--Rails uses it too.
+
+You will <b>not</b> want to keep the generated <tt>development.conf</tt> in the repository. This helps to catch bugs by discouraging out-of-date configurations.
+
+== Indexing and monitoring
+
+It's easy to keep the search daemon and the indexer running in a production environment. Cronjobs are the best way:
+
+  0,30 * * * * bash -c 'cd /path/to/production/current/; RAILS_ENV=production \
+    rake ultrasphinx:index >> /log/ultrasphinx-index.log 2>&1'
+  */3 * * * * bash -c 'cd /path/to/production/current/; RAILS_ENV=production \
+    rake ultrasphinx:daemon:start >> /log/ultrasphinx-daemon.log 2>&1'
+
+The first line runs the indexer every thirty minutes. The second line will try to restart the search daemon every three minutes. If it's already running, nothing happens. 
+
+If you are under severe memory limitations you might want to manage the daemon with Monit instead, so you can keep a closer eye on it. The search daemon is extremely reliable, so don't bother with fancy monitoring infrastructure unless you're sure you need it.
+
+== Gotchas
+
+If you change the field configuration or model set, you will need to rerun <tt>rake ultrasphinx:configure</tt> to update the <tt>.conf</tt> file. Make sure to completely stop and restart the search daemon when you deploy a changed <tt>.conf</tt>. It will not reload it automatically.

data/Manifest

@@ -1,7 +1,9 @@
 CHANGELOG
+DEPLOYMENT_NOTES
 examples/ap.multi
 examples/default.base
 init.rb
+lib/ultrasphinx/associations.rb
 lib/ultrasphinx/autoload.rb
 lib/ultrasphinx/configure.rb
 lib/ultrasphinx/core_extensions.rb
@@ -21,6 +23,7 @@ lib/ultrasphinx/ultrasphinx.rb
 lib/ultrasphinx.rb
 LICENSE
 Manifest
+RAKE_TASKS
 README
 tasks/ultrasphinx.rake
 test/config/ultrasphinx/test.base
@@ -35,6 +38,7 @@ test/integration/app/app/helpers/sellers_helper.rb
 test/integration/app/app/helpers/states_helper.rb
 test/integration/app/app/helpers/users_helper.rb
 test/integration/app/app/models/geo/address.rb
+test/integration/app/app/models/geo/country.rb
 test/integration/app/app/models/geo/state.rb
 test/integration/app/app/models/person/user.rb
 test/integration/app/app/models/seller.rb
@@ -67,7 +71,6 @@ test/integration/app/config/environments/test.rb
 test/integration/app/config/locomotive.yml
 test/integration/app/config/routes.rb
 test/integration/app/config/ultrasphinx/default.base
-test/integration/app/config/ultrasphinx/development.conf
 test/integration/app/config/ultrasphinx/development.conf.canonical
 test/integration/app/db/migrate/001_create_users.rb
 test/integration/app/db/migrate/002_create_sellers.rb
@@ -77,7 +80,7 @@ test/integration/app/db/migrate/005_add_capitalization_to_seller.rb
 test/integration/app/db/migrate/006_add_deleted_to_user.rb
 test/integration/app/db/migrate/007_add_lat_and_long_to_address.rb
 test/integration/app/db/migrate/008_add_mission_statement_to_seller.rb
-test/integration/app/db/schema.rb
+test/integration/app/db/migrate/009_create_countries.rb
 test/integration/app/doc/README_FOR_APP
 test/integration/app/public/404.html
 test/integration/app/public/500.html
@@ -110,6 +113,7 @@ test/integration/app/script/process/spawner
 test/integration/app/script/runner
 test/integration/app/script/server
 test/integration/app/test/fixtures/addresses.yml
+test/integration/app/test/fixtures/countries.yml
 test/integration/app/test/fixtures/sellers.yml
 test/integration/app/test/fixtures/states.yml
 test/integration/app/test/fixtures/users.yml
@@ -127,6 +131,7 @@ test/integration/search_test.rb
 test/integration/server_test.rb
 test/integration/spell_test.rb
 test/setup.rb
+test/teardown.rb
 test/test_all.rb
 test/test_helper.rb
 test/ts.multi

data/RAKE_TASKS

@@ -0,0 +1,15 @@
+
+== Available Rake tasks
+
+These Rake tasks are made available to your Rails app:
+
+<tt>ultrasphinx:configure</tt>:: Rebuild the configuration file for this particular environment.
+<tt>ultrasphinx:index</tt>:: Reindex the database and send an update signal to the search daemon.
+<tt>ultrasphinx:daemon:restart</tt>:: Restart the search daemon.
+<tt>ultrasphinx:daemon:start</tt>:: Start the search daemon.
+<tt>ultrasphinx:daemon:stop</tt>:: Stop the search daemon.
+<tt>ultrasphinx:daemon:status</tt>:: Check if the search daemon is running.
+<tt>ultrasphinx:spelling:build</tt>:: Rebuild the custom spelling dictionary. You may need to use <tt>sudo</tt> if your Aspell folder is not writable by the app user.
+<tt>ultrasphinx:bootstrap</tt>:: Bootstrap a full Sphinx environment by running configure, index, then daemon:start.
+
+All tasks have shortcuts. Use <tt>us:conf</tt>, <tt>us:in</tt>, <tt>us:restart</tt>, <tt>us:start</tt>, <tt>us:stop</tt>, <tt>us:stat</tt>, <tt>us:spell</tt>, and <tt>us:boot</tt>.

data/README

@@ -11,9 +11,11 @@ The public certificate for the gem is at http://rubyforge.org/frs/download.php/2
 
 == Requirements
 
-* MySQL (or Postgres, experimental)
-* Sphinx 0.9.8-dev r871 or greater
-* Rails 1.2.3 or greater
+* MySQL 5.0, or PostgreSQL 8.2
+* Sphinx 0.9.8-dev r871
+* Rails 1.2.3
+
+More recent versions than listed are ok.
 
 == Features
 
@@ -65,15 +67,13 @@ For more index options, see ActiveRecord::Base .is_indexed.
 
 == Building the index
 
-Run:
+Now run:
 
   rake ultrasphinx:configure
   rake ultrasphinx:index
   rake ultrasphinx:daemon:start
 
-To rotate the index, just rerun <tt>rake ultrasphinx:index</tt>. If the search daemon is running, it will have its index rotated. Otherwise the new index will be installed but the daemon will remain stopped.
-
-Make sure to manually stop and restart the daemon if you change the field configuration or model set. It will not reload the configuration file automatically.
+To rotate the index, just rerun <tt>rake ultrasphinx:index</tt>. If the search daemon is running, it will have its index rotated live. Otherwise the new index will be installed but the daemon will remain stopped.
 
 == Running queries
     
@@ -97,18 +97,15 @@ See Ultrasphinx::Spell.
   
 == Available Rake tasks
 
-These Rake tasks are made available to your Rails app:
+See RAKE_TASKS[link:files/RAKE_TASKS.html].
+
+== Deployment notes
+
+See DEPLOYMENT_NOTES[link:files/DEPLOYMENT_NOTES.html].
 
-<tt>ultrasphinx:configure</tt>:: Rebuild the configuration file for this particular environment.
-<tt>ultrasphinx:index</tt>:: Reindex the database and send an update signal to the search daemon.
-<tt>ultrasphinx:daemon:restart</tt>:: Restart the search daemon.
-<tt>ultrasphinx:daemon:start</tt>:: Start the search daemon.
-<tt>ultrasphinx:daemon:stop</tt>:: Stop the search daemon.
-<tt>ultrasphinx:daemon:status</tt>:: Check if the search daemon is running.
-<tt>ultrasphinx:spelling:build</tt>:: Rebuild the custom spelling dictionary. You may need to use <tt>sudo</tt> if your Aspell folder is not writable by the app user.
-<tt>ultrasphinx:bootstrap</tt>:: Bootstrap a full Sphinx environment by running configure, index, then daemon:start.
+== A note about PostgreSQL
 
-All tasks have shortcuts. Use <tt>us:conf</tt>, <tt>us:in</tt>, <tt>us:restart</tt>, <tt>us:start</tt>, <tt>us:stop</tt>, <tt>us:stat</tt>, <tt>us:spell</tt>, and <tt>us:boot</tt>.
+PostgreSQL 8.2 and higher are well supported. However, make sure you have executed <tt>CREATE LANGUAGE plpgsql;</tt> at least once. This step does not need to be repeated, so depending on your DB permissions, you might be able to put it in a migration.
 
 == Reporting problems
 

data/TODO

@@ -1,7 +1,13 @@
 
-* Use Pat Allan's association configurator, possibly with an API change to avoid the message-passing DSL
+Planned:
+
 * Finish unifying filters and textfields
 * Support exclude filters
 * Make sure filters can be set to nil
 * Geolocation search
+
+Not sure:
+
+* Delta indexing
+* Use Pat Allan's association configurator, possibly with an API change to avoid the message-passing DSL
 * Use Treetop for the query parser instead of regexes

data/examples/default.base

@@ -2,8 +2,21 @@
 #
 # Sphinx/Ultrasphinx user-configurable options.
 #
-# Copy this file to RAILS_ROOT/config/ultrasphinx.
-# You can use individual namespaces if you want (e.g. "development.base").
+# Copy this file to RAILS_ROOT/config/ultrasphinx. You can use individual 
+# namespaces if you want (e.g. development.base, production.base,
+# test.base).
+#
+# This file should not be handed directly to Sphinx. Use the rake task 
+#
+#   rake ultrasphinx::configure
+#
+# to generate a parallel default.conf file. This is the file that Sphinx itself will
+# use. The Ultrasphinx rake tasks automatically pass the correct file to 
+# to Sphinx.
+# 
+# It is safe to edit .base files by hand. It is not safe to edit the generated 
+# .conf files. Do not symlink the .conf file to the .base file! I don't know why 
+# people think they need to do that. It's wrong.
 #
 
 indexer
@@ -18,6 +31,7 @@ searchd
   # What interface the search daemon should listen on and where to store its logs
   address = 0.0.0.0
   port = 3312
+  seamless_rotate = 1
   log = /opt/local/var/db/sphinx/log/searchd.log
   query_log = /opt/local/var/db/sphinx/log/query.log
   read_timeout = 5

data/lib/ultrasphinx.rb

@@ -12,12 +12,12 @@ end
 
 $LOAD_PATH << "#{File.dirname(__FILE__)}/../vendor/riddle/lib"
 require 'riddle'
-
 require 'ultrasphinx/ultrasphinx'
+require 'ultrasphinx/associations'
 require 'ultrasphinx/core_extensions'
 require 'ultrasphinx/is_indexed'
 
-if (ActiveRecord::Base.connection rescue nil)
+if (ActiveRecord::Base.connection rescue nil) # XXX Forget why this needed to be wrapped
   require 'ultrasphinx/configure'
   require 'ultrasphinx/autoload'
   require 'ultrasphinx/fields'

data/lib/ultrasphinx/associations.rb

@@ -0,0 +1,25 @@
+module Ultrasphinx
+  module Associations
+  
+    def get_association(klass, entry)
+      if value = entry['class_name']
+        klass.reflect_on_all_associations.detect do |assoc|
+          assoc.class_name == value
+        end    
+      elsif value = entry['association_name']
+        klass.reflect_on_all_associations.detect do |assoc|
+          assoc.name.to_s == value.to_s
+        end 
+      end
+    end
+    
+    def get_association_model(klass, entry)
+      get_association(klass, entry).class_name.constantize
+    end    
+    
+    def entry_identifies_association?(entry)
+      entry['class_name'] || entry['association_name']
+    end
+    
+  end
+end

data/lib/ultrasphinx/configure.rb

@@ -1,7 +1,9 @@
 
 module Ultrasphinx
   class Configure  
-    class << self    
+    class << self
+
+      include Associations
   
       # Force all the indexed models to load and register in the MODEL_CONFIGURATION hash.
       def load_constants
@@ -75,7 +77,7 @@ module Ultrasphinx
         # Supporting Postgres now
         connection_settings = klass.connection.instance_variable_get("@config")
 
-        adapter_defaults = ADAPTER_DEFAULTS[ADAPTER]
+        adapter_defaults = DEFAULTS[ADAPTER]
         raise ConfigurationError, "Unsupported database adapter" unless adapter_defaults
 
         conf = [adapter_defaults]                  
@@ -100,7 +102,12 @@ module Ultrasphinx
       
       
       def range_select_string(klass)
-        "sql_query_range = SELECT MIN(#{klass.primary_key}), MAX(#{klass.primary_key}) FROM #{klass.table_name}"
+        ["sql_query_range = SELECT",
+          SQL_FUNCTIONS[ADAPTER]['range_cast']._interpolate("MIN(#{klass.primary_key})"),
+          ", ",
+          SQL_FUNCTIONS[ADAPTER]['range_cast']._interpolate("MAX(#{klass.primary_key})"),
+          "FROM #{klass.table_name}"
+        ].join(" ")
       end
       
       
@@ -189,11 +196,15 @@ module Ultrasphinx
 
       def build_includes(klass, fields, entries, column_strings, join_strings, group_bys, remaining_columns)                  
         entries.to_a.each do |entry|
+          raise ConfigurationError, "You must identify your association with either class_name or association_name, but not both" if entry['class_name'] && entry ['association_name']          
         
-          join_klass = entry['class_name'].constantize
-          association = association_by_class_name(klass, entry['class_name'])
+          association = get_association(klass, entry)
+
+          # You can use 'class_name' and 'association_sql' to associate to a model that doesn't actually 
+          # have an association
+          join_klass = association ? association.class_name.constantize : entry['class_name'].constantize
                         
-          raise ConfigurationError, "Unknown association from #{klass} to #{entry['class_name']}" if not association and not entry['association_sql']
+          raise ConfigurationError, "Unknown association from #{klass} to #{entry['class_name'] || entry['association_name']}" if not association and not entry['association_sql']
           
           join_strings = install_join_unless_association_sql(entry['association_sql'], nil, join_strings) do 
             "LEFT OUTER JOIN #{join_klass.table_name} AS #{entry['table']} ON " + 
@@ -217,21 +228,26 @@ module Ultrasphinx
         
       def build_concatenations(klass, fields, entries, column_strings, join_strings, group_bys, use_distinct, remaining_columns)
         entries.to_a.each do |entry|
-          if entry['class_name'] and entry['field']
+          if entry_identifies_association?(entry) and entry['field']
             # Group concats
+  
             # Only has_many's or explicit sql right now
-            join_klass = entry['class_name'].constantize
+            association = get_association(klass, entry)
+            
+            # You can use 'class_name' and 'association_sql' to associate to a model that doesn't actually 
+            # have an association
+            join_klass = association ? association.class_name.constantize : entry['class_name'].constantize
         
             join_strings = install_join_unless_association_sql(entry['association_sql'], nil, join_strings) do 
               # XXX make sure foreign key is right for polymorphic relationships
-              association = association_by_class_name(klass, entry['class_name'])
+              association = get_association(klass, entry)
               "LEFT OUTER JOIN #{join_klass.table_name} AS #{entry['table']} ON #{klass.table_name}.#{klass.primary_key} = #{entry['table']}.#{association.primary_key_name}" + 
                 (entry['conditions'] ? " AND (#{entry['conditions']})" : "")
             end
             
             source_string = "#{entry['table']}.#{entry['field']}"
             # We are using the field in an aggregate, so we don't want to add it to group_bys
-            source_string = ADAPTER_SQL_FUNCTIONS[ADAPTER]['group_concat']._interpolate(source_string)
+            source_string = SQL_FUNCTIONS[ADAPTER]['group_concat']._interpolate(source_string)
             use_distinct = true
             
             column_strings, remaining_columns = install_field(fields, source_string, entry['as'], entry['function_sql'], entry['facet'], column_strings, remaining_columns)
@@ -284,12 +300,6 @@ module Ultrasphinx
       def install_join_unless_association_sql(association_sql, join_string, join_strings)
         join_strings << (association_sql or join_string or yield)
       end
-
-      def association_by_class_name(klass, class_name)
-        klass.reflect_on_all_associations.detect do |assoc|
-          assoc.class_name == class_name
-        end
-      end
       
       def say(s)
         Ultrasphinx.say s

data/lib/ultrasphinx/fields.rb

@@ -7,6 +7,7 @@ This is a special singleton configuration class that stores the index field conf
 
   class Fields
     include Singleton
+    include Associations
     
     TYPE_MAP = {
       'string' => 'text', 
@@ -114,14 +115,16 @@ This is a special singleton configuration class that stores the index field conf
           options['include'].to_a.each do |entry|
             extract_table_alias!(entry, klass)
             extract_field_alias!(entry, klass)
-
-            save_and_verify_type(entry['as'] || entry['field'], entry['class_name'].constantize.columns_hash[entry['field']].type, entry['sortable'], klass)            
+            
+            association_model = get_association_model(klass, entry)
+            
+            save_and_verify_type(entry['as'] || entry['field'], association_model.columns_hash[entry['field']].type, entry['sortable'], klass)
             install_facets!(entry, klass)
           end  
           
           # Regular concats are CHAR, group_concats are BLOB and need to be cast to CHAR
           options['concatenate'].to_a.each do |entry|
-            extract_table_alias!(entry, klass) # XXX Doesn't actually do anything useful
+            extract_table_alias!(entry, klass)
             save_and_verify_type(entry['as'], 'text', entry['sortable'], klass) 
             install_facets!(entry, klass)
           end          
@@ -155,7 +158,7 @@ This is a special singleton configuration class that stores the index field conf
           # This field is referenced by a table alias
           entry['table'], entry['field'] = entry['field'].split(".")
         else
-          klass = entry['class_name'].constantize if entry['class_name']         
+          klass = get_association_model(klass, entry) if entry_identifies_association?(entry)
           entry['table'] = klass.table_name
         end
       end

data/lib/ultrasphinx/is_indexed.rb

@@ -32,47 +32,59 @@ To apply an SQL function to a field before it is indexed, use the key <tt>:funct
 
 Note that <tt>float</tt> fields are supported, but require Sphinx 0.98.
 
+== Requiring conditions
+
+Use the <tt>:conditions</tt> key.
+
+SQL conditions, to scope which records are selected for indexing. Accepts a string. 
+
+  :conditions => "created_at < NOW() AND deleted IS NOT NULL"
+  
+The <tt>:conditions</tt> key is especially useful if you delete records by marking them deleted rather than removing them from the database.
+
 == Including a field from an association
 
 Use the <tt>:include</tt> key.
 
 Accepts an array of hashes. 
 
-  :include => [{:class_name => 'Category', :field => 'name', :as => 'category'}]
+  :include => [{:association_name => 'category', :field => 'name', :as => 'category_name'}]
 
-Each should contain a <tt>:class_name</tt> key (the class name of the included model), a <tt>:field</tt> key (the name of the field to include), and an optional <tt>:as</tt> key (what to name the field in the parent). You can use the optional key <tt>:association_sql</tt> if you need to pass a custom JOIN string, in which case the default JOIN for <tt>belongs_to</tt> will not be generated.
+Each should contain an <tt>:association_name</tt> key (the association name for the included model), a <tt>:field</tt> key (the name of the field to include), and an optional <tt>:as</tt> key (what to name the field in the parent). 
 
-The keys <tt>:facet</tt>, <tt>:sortable</tt>, and <tt>:function_sql</tt> are also recognized, just like for regular fields.
+<tt>:include</tt> hashes also accept their own <tt>:conditions</tt> key. You can use this  if you need custom WHERE conditions for this particular association (e.g, this JOIN).
 
-== Requiring conditions
+The keys <tt>:facet</tt>, <tt>:sortable</tt>, <tt>:class_name</tt>, <tt>:association_sql</tt>, and <tt>:function_sql</tt> are also recognized.
 
-Use the <tt>:conditions</tt> key.
-
-SQL conditions, to scope which records are selected for indexing. Accepts a string. 
-  :conditions => "created_at < NOW() AND deleted IS NOT NULL"
-The <tt>:conditions</tt> key is especially useful if you delete records by marking them deleted rather than removing them from the database.
-
-== Concatenating several fields within a record
+== Concatenating several fields within one record
 
 Use the <tt>:concatenate</tt> key (MySQL only).
 
 Accepts an array of option hashes. 
 
-To concatenate several fields within one record as a combined field, use a regular (or horizontal) concatenation. Regular concatenations contain a <tt>:fields</tt> key (again, an array of field names), and a mandatory <tt>:as</tt> key (the name of the result of the concatenation). For example, to concatenate the <tt>title</tt> and <tt>body</tt> into one field called <tt>text</tt>: 
+To concatenate several fields within one record as a combined field, use a regular (or lateral) concatenation. Regular concatenations contain a <tt>:fields</tt> key (again, an array of field names), and a mandatory <tt>:as</tt> key (the name of the result of the concatenation). For example, to concatenate the <tt>title</tt> and <tt>body</tt> into one field called <tt>text</tt>: 
   :concatenate => [{:fields => ['title', 'body'], :as => 'text'}]
   
-The keys <tt>:facet</tt>, <tt>:sortable</tt>, and <tt>:function_sql</tt> are also recognized, just like for regular fields.
+The keys <tt>:facet</tt>, <tt>:sortable</tt>, <tt>:conditions</tt>, <tt>:function_sql</tt>, <tt>:class_name</tt>, and <tt>:association_sql</tt>, are also recognized.
+
+Lateral concatenations are implemented with CONCAT_WS on MySQL and with a stored procedure on PostgreSQL.
 
-== Concatenating one field from a set of associated records 
+== Concatenating the same field from a set of associated records 
 
 Also use the <tt>:concatenate</tt> key.
 
-To concatenate one field from a set of associated records as a combined field in the parent record, use a group (or vertical) concatenation. A group concatenation should contain a <tt>:class_name</tt> key (the class name of the included model), a <tt>:field</tt> key (the field on the included model to concatenate), and an optional <tt>:as</tt> key (also the name of the result of the concatenation). For example, to concatenate all <tt>Post#body</tt> contents into the parent's <tt>responses</tt> field:
-  :concatenate => [{:class_name => 'Post', :field => 'body', :as => 'responses'}]
+To concatenate one field from a set of associated records as a combined field in the parent record, use a group (or vertical) concatenation. A group concatenation should contain an <tt>:association_name</tt> key (the association name for the included model), a <tt>:field</tt> key (the field on the included model to concatenate), and an optional <tt>:as</tt> key (also the name of the result of the concatenation). For example, to concatenate all <tt>Post#body</tt> contents into the parent's <tt>responses</tt> field:
+  :concatenate => [{:association_name => 'posts', :field => 'body', :as => 'responses'}]
+
+The keys <tt>:facet</tt>, <tt>:sortable</tt>, <tt>:conditions</tt>, <tt>:function_sql</tt>, <tt>:class_name</tt>, and <tt>:association_sql</tt>, are also recognized.
+
+Vertical concatenations are implemented with GROUP_CONCAT on MySQL and with an aggregate and a stored procedure on PostgreSQL.
+
+== Custom joins
 
-Optional group concatenation keys are <tt>:association_sql</tt>, if you need to pass a custom JOIN string (for example, a double JOIN for a <tt>has_many :through</tt>), and <tt>:conditions</tt> (if you need custom WHERE conditions for this particular association).
+<tt>:include</tt> and <tt>:concatenate</tt> accept an <tt>:association_sql</tt> key. You can use this if you need to pass a custom JOIN string, for example, a double JOIN for a <tt>has_many :through</tt>). If <tt>:association_sql</tt> is present, the default JOIN for <tt>belongs_to</tt> will not be generated. 
 
-The keys <tt>:facet</tt>, <tt>:sortable</tt>, and <tt>:function_sql</tt> are also recognized, just like for regular fields.
+Also, If you want to include a model that you don't have an actual ActiveRecord association for, you can use <tt>:association_sql</tt> combined with <tt>:class_name</tt> instead of <tt>:association_name</tt>. <tt>:class_name</tt> should be camelcase.
 
 Ultrasphinx is not an object-relational mapper, and the association generation is intended to stay minimal--don't be afraid of <tt>:association_sql</tt>.
 
@@ -89,13 +101,13 @@ Here's an example configuration using most of the options, taken from production
         {:field => 'author', :facet => true}
       ],
       :include => [
-        {:class_name => 'Category', :field => 'name', :as => 'category'}
+        {:association_name => 'category', :field => 'name', :as => 'category_name'}
       ],      
       :concatenate => [
         {:fields => ['title', 'long_description', 'short_description'], 
           :as => 'editorial'},
-        {:class_name => 'Page', :field => 'body', :as => 'body'},
-        {:class_name => 'Comment', :field => 'body', :as => 'comments', 
+        {:association_name => 'pages', :field => 'body', :as => 'body'},
+        {:association_name => 'comments', :field => 'body', :as => 'comments', 
           :conditions => "comments.item_type = '#{base_class}'"}
       ],
       :conditions => self.live_condition_string
@@ -110,7 +122,7 @@ A common use case is to only search records that belong to a particular parent m
 For example, say a Company <tt>has_many :users</tt> and each User <tt>has_many :articles</tt>. If you want to to filter Articles by Company, add <tt>company_id</tt> to the Article's <tt>is_indexed</tt> method. The best way is to grab it from the User association:
 
   class Article < ActiveRecord::Base 
-     is_indexed :include => [{:class_name => 'User', :field => 'company_id'}]
+     is_indexed :include => [{:association_name => 'users', :field => 'company_id'}]
   end
  
 Now you can run:
@@ -136,8 +148,8 @@ If the associations weren't just <tt>has_many</tt> and <tt>belongs_to</tt>, you
       
       Array(opts['concatenate']).each do |entry|
         entry.stringify_keys!
-        entry.assert_valid_keys ['class_name', 'conditions', 'field', 'as', 'fields', 'association_sql', 'facet', 'function_sql', 'sortable']
-        raise Ultrasphinx::ConfigurationError, "You can't mix regular concat and group concats" if entry['fields'] and (entry['field'] or entry['class_name'])
+        entry.assert_valid_keys ['class_name', 'association_name', 'conditions', 'field', 'as', 'fields', 'association_sql', 'facet', 'function_sql', 'sortable']
+        raise Ultrasphinx::ConfigurationError, "You can't mix regular concat and group concats" if entry['fields'] and (entry['field'] or entry['class_name'] or entry['association_name'])
         raise Ultrasphinx::ConfigurationError, "Concatenations must specify an :as key" unless entry['as']
         raise Ultrasphinx::ConfigurationError, "Group concatenations must not have multiple fields" if entry['field'].is_a? Array
         raise Ultrasphinx::ConfigurationError, "Regular concatenations should have multiple fields" if entry['fields'] and !entry['fields'].is_a?(Array)
@@ -145,7 +157,7 @@ If the associations weren't just <tt>has_many</tt> and <tt>belongs_to</tt>, you
       
       Array(opts['include']).each do |entry|
         entry.stringify_keys!
-        entry.assert_valid_keys ['class_name', 'field', 'as', 'association_sql', 'facet', 'function_sql', 'sortable']
+        entry.assert_valid_keys ['class_name', 'association_name', 'field', 'as', 'association_sql', 'facet', 'function_sql', 'sortable']
       end
       
       Ultrasphinx::MODEL_CONFIGURATION[self.name] = opts