repertoire-faceting 0.5.2 → 0.5.3

data/lib/repertoire-faceting/adapters/postgresql_adapter.rb

@@ -21,13 +21,13 @@ module Repertoire
     module PostgreSQLAdapter #:nodoc:
       
       # Creates (or recreates) the packed id column on a given table
-      def renumber_table(table_name, faceting_id='_packed_id')
-        sql = "SELECT renumber_table('#{table_name}', '#{faceting_id}')"
+      def renumber_table(table_name, faceting_id, wastage)
+        sql = "SELECT renumber_table('#{table_name}', '#{faceting_id}', #{wastage})"
         execute(sql)
       end
 
       # Returns the scatter quotient of the given id column
-      def signature_wastage(table_name, faceting_id='_packed_id')
+      def signature_wastage(table_name, faceting_id)
         sql    = "SELECT signature_wastage('#{table_name}', '#{faceting_id}')"
         result = select_value(sql)
         Float(result)
@@ -88,15 +88,6 @@ module Repertoire
         "INNER JOIN members(#{exprs.join(' & ')}) AS _refinements_id ON (#{table_name}.#{faceting_id} = _refinements_id)"
       end
       
-      private
-      
-      def ignoring_db_errors(&block)
-        begin
-          yield
-        rescue
-        end
-      end
-      
     end
   end
 end

data/lib/repertoire-faceting/controller.rb

@@ -2,10 +2,43 @@ module Repertoire
   module Faceting #:nodoc:
     
     # Include this mixin in your controller to add faceting webservices for use with the javascript
-    # widgets.  In general you will only need to over-ride base() to specify the model over which your
-    # faceted browser searches.  
+    # widgets.  Implementors should over-ride base() to specify the model for the faceted browser.
+    #
+    #   class PaintingsController
+    #     include Repertoire::Faceting::Controller
+    #     def base
+    #       Painting
+    #     end
+    #   end
+    #
+    # By default two web services are defined, one for the facet value count widgets and another for
+    # the result widget.  Each builds on the model returned by base():
+    #
+    #   counts  ==> base.refine(params[:filter]).count(params[:facet])
+    #   results ==> base.refine(params[:filter]).to_a
+    #
+    # If desired, you can use the Model API to specify a query that limits the faceting context to
+    # a subset of the available items from the start:
+    #
+    #     def base
+    #       q = "#{params[:search]}%"
+    #       Painting.where(["title like ?", q])
+    #     end
+    #
+    # Finally, you are free to over-ride the counts() and results() webservices.  Here we 
+    # reorder the facet value counts depending on another webservice param:
+    #
+    #     def counts
+    #       facet   = params[:facet]
+    #       filter  = params[:filter] || {}
+    #       sorting = case params[:order]
+    #                   when 'alphanumeric' then ["#{facet} ASC"]
+    #                   when 'count'        then ["count DESC", "#{facet} ASC"]
+    #                 end
+    #       @counts = base.refine(filter).order(sorting).count(facet)
+    #       render :json => @counts.to_a
+    #     end
     #
-    # However, for more complex behavior you can over-ride counts() and results() as well.
     module Controller
       
       # Web-service to return value, count pairs for a given facet, given existing filter refinements

data/lib/repertoire-faceting/model.rb

@@ -3,6 +3,10 @@ module Repertoire
     module Model #:nodoc:
       extend ActiveSupport::Concern
       
+      SIGNATURE_WASTAGE_THRESHOLD = 0.15
+      DEFAULT_SIGNATURE_COLUMN    = 'id'
+      PACKED_SIGNATURE_COLUMN     = '_packed_id'
+      
       included do |base|
         base.singleton_class.delegate :refine, :minimum, :nils, :reorder, :to_sql, :to => :scoped
       end
@@ -29,8 +33,8 @@ module Repertoire
       #
       #   facet :discipline, group(:discipline)
       #
-      # and the grouping on degree could be left out.  You can use this to construct a facet from differently-
-      # named columns:
+      # and the grouping on degree could be left out.  You can use this behavior to construct a facet 
+      # from differently-named columns:
       #
       #   facet :balloon_color, group(:color)
       #
@@ -42,13 +46,13 @@ module Repertoire
       #
       # == Nested facets
       #
-      # Facets can be constructed into a nested hierarchy of values by providing multiple group columns.  In this
+      # Facets can be built from a nested hierarchy of values by providing multiple group columns.  In this
       # case, value counts are aggregated at each level in turn.
       #
       #   facet :birth_place, group(:birth_country, :birth_state, :birth_city)
       #
-      # As for basic facets, nested facets can be constructed from SQL expressions.  This is particularly useful in
-      # faceting over data in more complex types such as dates or geographical regions.
+      # As for basic facets, nested facets may consist of SQL expressions.  This is particularly useful in
+      # faceting over data in more complex types such as dates or geographical regions:
       #
       #   facet :birth_date, group('EXTRACT(year FROM birthdate)', 'EXTRACT(month FROM birthdate)', 'EXTRACT(day FROM birthdate)')
       #
@@ -137,27 +141,45 @@ module Repertoire
           facets.keys
         end
         
-        # Drops any unused facet indices, updates its packed ids, then recreates indices 
-        # for the facets with the provided names.  If no names are provided, then the existing 
-        # facet indices are refreshed.  For example:
+        # Drops any unused facet indices, updates its packed ids, then recreates 
+        # indices for the facets with the provided names.  If no names are provided, 
+        # then the existing facet indices are refreshed.
+        #
+        # If a signature id column name is provided, it will be used to build the 
+        # bitset indices. Otherwise the indexer will add or remove a new packed 
+        # id column as appropriate.
+        #
+        # Examples:
         #
         # === Refresh existing facet indices
         #
         #   Nobelist.update_indexed_facets
         #
-        # === Drop all facet indices
+        # === Adjust which facets are indexed
+        #
+        #   Nobelist.update_indexed_facets([:degree, :nobel_year])
+        #
+        # === Drop all facet indices, but add/remove packed id as necessary
         #
         #   Nobelist.update_indexed_facets([])
         #
-        # === Adjust which facets are indexed
+        # === Drop absolutely everything, force manual faceting using 'id' 
+        #     column
         #
-        #   Nobelist.update_indexed_facets([:degree, :nobel_year])
+        #   Nobelist.udpate_indexed_facets([], 'id')
         #
-        def update_indexed_facets(facet_names=nil)
+        def update_indexed_facets(facet_names=nil, signature_column=nil)
           # default: update existing facets
           indexed_facets = connection.indexed_facets(table_name)
           facet_names ||= indexed_facets
           
+          # determine best column for signature bitsets, unless set manually
+          signature_column ||= if signature_wastage('id') < SIGNATURE_WASTAGE_THRESHOLD
+            DEFAULT_SIGNATURE_COLUMN
+          else
+            PACKED_SIGNATURE_COLUMN
+          end
+          
           connection.transaction do
             # drop old facet indices
             indexed_facets.each do |name|
@@ -165,18 +187,14 @@ module Repertoire
               connection.drop_table(table)
             end
             
-            # update or drop the model packed id column
-            if (facet_names.empty? && should_unpack?)
-              connection.remove_column(table_name, '_packed_id')
-            else 
-              connection.renumber_table(table_name, '_packed_id')
-            end
+            # create or remove packed signature column as necessary
+            ensure_numbering(signature_column)
 
             # re-create the facet indices
             facet_names.each do |name|
               name = name.to_sym
               raise "Unknown facet #{name}" unless facet?(name)
-              facets[name].create_index('_packed_id')
+              facets[name].create_index(signature_column)
             end
           end
           
@@ -186,7 +204,7 @@ module Repertoire
         # Returns the name of the id column to use for constructing bitset signatures
         # over this model.
         def faceting_id
-          ['_packed_id', 'id'].detect { |c| column_names.include?(c) }
+          [PACKED_SIGNATURE_COLUMN, DEFAULT_SIGNATURE_COLUMN].detect { |c| column_names.include?(c) }
         end
         
         def signature_wastage(col=nil)
@@ -194,9 +212,14 @@ module Repertoire
           connection.signature_wastage(table_name, col)
         end
         
-        def should_unpack?
-          (faceting_id == '_packed_id') && (signature_wastage('id') < 0.15)
+        def ensure_numbering(signature_column)
+          if signature_column == DEFAULT_SIGNATURE_COLUMN
+            connection.remove_column(table_name, PACKED_SIGNATURE_COLUMN) if column_names.include?(PACKED_SIGNATURE_COLUMN)
+          else
+            connection.renumber_table(table_name, PACKED_SIGNATURE_COLUMN, SIGNATURE_WASTAGE_THRESHOLD)
+          end
         end
+        
       end
     end
   end

data/lib/repertoire-faceting/routing.rb

@@ -1,16 +1,19 @@
 module Repertoire
   module Faceting #:nodoc:
+    #
+    # Standard routing extensions for Repertoire Faceting webservices.
+    #
+    #   Example::Application.routes.draw do
+    #     faceting_for :paintings
+    #   end
+    #
+    # N.B. Include faceting routes before any resources!
+    #
     module Routing
       
       #
       # Add routes for the faceting webservices provided by the Controller mixin.
       #
-      #   Example::Application.routes.draw do
-      #     faceting_for :nobelists
-      #   end
-      #
-      # N.B. Include faceting routes before any resources!
-      #
       def faceting_for(*controllers)
         options = controllers.extract_options!
 
@@ -25,4 +28,3 @@ module Repertoire
     end
   end
 end
-    

data/lib/repertoire-faceting/version.rb

@@ -1,5 +1,5 @@
 module Repertoire
   module Faceting #:nodoc:
-    VERSION = "0.5.2"
+    VERSION = "0.5.3"
   end
 end

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 5
-  - 2
-  version: 0.5.2
+  - 3
+  version: 0.5.3
 platform: ruby
 authors: 
 - Christopher York
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-10-28 00:00:00 +01:00
+date: 2010-11-03 00:00:00 +00:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency