activewarehouse 0.2.0 → 0.3.0

data/lib/active_warehouse/cube_query_result.rb

@@ -0,0 +1,69 @@
+module ActiveWarehouse #:nodoc:
+  # Class that holds the results of a Cube query
+  class CubeQueryResult
+    attr_reader :aggregate_fields_hash
+  
+    # Initialize the aggregate map with an array of AggregateField instances.
+    # The AggregateFields are used to typecast the raw values coming from
+    # the database.  Thank you very little, DBI.
+    def initialize(aggregate_fields)
+      raise ArgumentError, "aggregate_fields must not be empty" unless aggregate_fields && aggregate_fields.size > 0
+      @aggregate_fields_hash = {}
+      aggregate_fields.each {|c| @aggregate_fields_hash[c.label] = c}
+      @values_map = {}
+    end
+
+    # Return true if the aggregate map includes the specified row value
+    def has_row_values?(row_value)
+      @values_map.has_key?(row_value)
+    end
+    
+    # iterate through every row and column combination
+    def each
+      @values_map.each do |key, value|
+        yield key, value
+      end
+    end
+  
+    def value(row_value, col_value, field_label)
+      #puts "getting value #{row_value},#{col_value},#{field_label}"
+      values(row_value, col_value)[field_label]
+    end
+  
+    # returns a hash of type casted fact values for the intersection of
+    # row_value and col_value
+    def values(row_value, col_value)
+      row = @values_map[row_value]
+      return empty_hash_for_missing_row_or_column if row.nil?
+      facts = row[col_value]
+      return empty_hash_for_missing_row_or_column if facts.nil?
+      facts
+    end
+  
+    # Add a hash of aggregated facts for the given row and column values.
+    # For instance, add_data('Southeast', 2005, {:sales_sum => 40000, :sales_count => 40})
+    # This method will typecast the values in aggregated_facts.
+    def add_data(row_value, col_value, aggregated_facts)
+      #puts "Adding data for #{row_value}, #{col_value} [data=[#{aggregated_facts.join(',')}]]"
+      @values_map[row_value] ||= {}
+      @values_map[row_value][col_value] = typecast_facts(aggregated_facts)
+    end
+    
+    private
+    def empty_hash_for_missing_row_or_column
+      empty = {}
+      aggregate_fields_hash.keys.each {|k| empty[k] = 0}
+      empty
+    end
+    
+    def typecast_facts(raw_facts)
+      raw_facts.each do |k,v|
+        field = aggregate_fields_hash[k]
+        if field.nil?
+          raise ArgumentError, "'#{k}' is an unknown aggregate field in this query result"
+        end
+        raw_facts[k] = field.type_cast(v)
+      end
+    end
+  end
+end

data/lib/active_warehouse/dimension.rb

@@ -1,12 +1,14 @@
 # require all of the "acts_as" mixins first
 require 'active_warehouse/dimension/hierarchical_dimension'
 require 'active_warehouse/dimension/slowly_changing_dimension'
+require 'active_warehouse/dimension/dimension_reflection'
+
+ActiveRecord::Reflection::AssociationReflection.send(:include, ActiveWarehouse::DimensionReflection)
 
 module ActiveWarehouse #:nodoc
-  # Dimension tables contain the textual descriptors of the business. Dimensions provide the filters which 
-  # are applied to facts. Dimensions are the primary source of query constraints, groupings and report 
-  # labels.
-  # 
+  # Dimension tables contain the textual descriptors of the business. Dimensions
+  # provide the filters which  are applied to facts. Dimensions are the primary
+  # source of query constraints, groupings and report labels.
   class Dimension < ActiveRecord::Base
     include ActiveWarehouse::HierarchicalDimension
     include ActiveWarehouse::SlowlyChangingDimension
@@ -20,8 +22,9 @@ module ActiveWarehouse #:nodoc
       # Map of level names to alternate order columns
       attr_reader :level_orders
       
-      # Define a column to order by. If this value is specified then it will be used rather than the actual
-      # level being queried in the following method calls:
+      # Define a column to order by. If this value is specified then it will be
+      # used rather than the actual level being queried in the following method
+      # calls:
       # * available_values
       # * available_child_values
       # * available_values_tree
@@ -46,8 +49,9 @@ module ActiveWarehouse #:nodoc
       # This would indicate that one of the drill down paths for this dimension is:
       # Fiscal Year -> Fiscal Quarter -> Fiscal Month
       #
-      # Internally the hierarchies are stored in order. The first hierarchy defined will be used as the default
-      # if no hierarchy is specified when rendering a cube.
+      # Internally the hierarchies are stored in order. The first hierarchy
+      # defined will be used as the default if no hierarchy is specified when
+      # rendering a cube.
       def define_hierarchy(name, levels)
         hierarchies << name
         hierarchy_levels[name] = levels
@@ -70,7 +74,8 @@ module ActiveWarehouse #:nodoc
         @hierarchy_levels ||= {}
       end
       
-      # Return a symbol used when referring to this dimension. The symbol is calculated by demodulizing and underscoring the
+      # Return a symbol used when referring to this dimension. The symbol is
+      # calculated by demodulizing and underscoring the
       # dimension's class name and then removing the trailing _dimension.
       # 
       # Example: DateDimension will return a symbol :date
@@ -78,7 +83,8 @@ module ActiveWarehouse #:nodoc
         self.name.demodulize.underscore.gsub(/_dimension/, '').to_sym
       end
       
-      # Get the table name. By default the table name will be the name of the dimension in singular form.
+      # Get the table name. By default the table name will be the name of the
+      # dimension in singular form.
       #
       # Example: DateDimension will have a table called date_dimension
       def table_name
@@ -99,31 +105,35 @@ module ActiveWarehouse #:nodoc
         class_name(name).constantize
       end
       
-      # Return the time when the underlying dimension source file was last modified. This is used
+      # Return the time when the underlying dimension source file was last
+      # modified. This is used
       # to determine if a cube structure rebuild is required
       def last_modified
         File.new(__FILE__).mtime
       end
       
-      # Get the dimension class for the specified dimension parameter. The dimension parameter may be a class,
-      # String or Symbol.
+      # Get the dimension class for the specified dimension parameter. The
+      # dimension parameter may be a class, String or Symbol.
       def to_dimension(dimension)
-        return dimension if dimension.is_a?(Class) and dimension.superclass == Dimension
+        return dimension if dimension.is_a?(Class) and dimension.ancestors.include?(Dimension)
         return class_for_name(dimension)
       end
       
-      # Returns a hash of all of the values at the specified hierarchy level mapped to the count at that level.
-      # For example, given a date dimension with years from 2002 to 2004 and a hierarchy defined with:
+      # Returns a hash of all of the values at the specified hierarchy level 
+      # mapped to the count at that level. For example, given a date dimension
+      # with years from 2002 to 2004 and a hierarchy defined with:
       # 
       #  hierarchy :cy, [:calendar_year, :calendar_quarter, :calendar_month_name] 
       #
       # ...then...
       #
-      #  DateDimension.denominator_count(:cy, :calendar_year, :calendar_quarter) returns {'2002' => 4, '2003' => 4, '2004' => 4}
+      #  DateDimension.denominator_count(:cy, :calendar_year, :calendar_quarter)
+      #  returns {'2002' => 4, '2003' => 4, '2004' => 4}
       # 
       # If the denominator_level parameter is omitted or nil then:
       #
-      #  DateDimension.denominator_count(:cy, :calendar_year) returns {'2003' => 365, '2003' => 365, '2004' => 366}
+      #  DateDimension.denominator_count(:cy, :calendar_year) returns
+      #  {'2003' => 365, '2003' => 365, '2004' => 366}
       #
       def denominator_count(hierarchy_name, level, denominator_level=nil)
         if hierarchy_levels[hierarchy_name].nil?
@@ -131,12 +141,16 @@ module ActiveWarehouse #:nodoc
         end
         
         q = nil
-        # If the denominator_level is specified and it is not the last element in the hierarchy then do a distinct count. If
-        # the denominator level is less than the current level then raise an ArgumentError. In other words, if the current level is
-        # calendar month then passing in calendar year as the denominator level would raise an ArgumentErro.
+        # If the denominator_level is specified and it is not the last element
+        # in the hierarchy then do a distinct count. If
+        # the denominator level is less than the current level then raise an
+        # ArgumentError. In other words, if the current level is
+        # calendar month then passing in calendar year as the denominator level
+        # would raise an ArgumentErro.
         #
-        # If the denominator_level is not specified then assume the finest grain possible (in the context of a date dimension
-        # this would be each day) and use the id to count.
+        # If the denominator_level is not specified then assume the finest grain
+        # possible (in the context of a date dimension this would be each day)
+        # and use the id to count.
         if denominator_level && hierarchy_levels[hierarchy_name].last != denominator_level
           level_index = hierarchy_levels[hierarchy_name].index(level)
           denominator_index = hierarchy_levels[hierarchy_name].index(denominator_level)
@@ -156,7 +170,6 @@ module ActiveWarehouse #:nodoc
           q = "select #{level} as level, count(id) as level_count from #{table_name} group by #{level}"
         end
         denominators = {}
-        # TODO: fix to use select_all instead of execute
         connection.select_all(q).each do |row|
           denominators[row['level']] = row['level_count'].to_i
         end
@@ -166,6 +179,10 @@ module ActiveWarehouse #:nodoc
       # Get the foreign key for this dimension which is used in Fact tables.
       # 
       # Example: DateDimension would have a foreign key of date_id
+      #
+      # The actual foreign key may be different and depends on the fact class.
+      # You may specify the foreign key to use for a specific fact using the
+      # Fact#set_dimension_options method.
       def foreign_key
         table_name.sub(/_dimension/,'') + '_id'
       end
@@ -178,13 +195,21 @@ module ActiveWarehouse #:nodoc
         level_method = level.to_sym
         level = connection.quote_column_name(level.to_s)
         order = level_orders[level] || self.order || level
-        find(:all, :select => level, :group => level, :order => order).collect {|dim| dim.send(level_method)}
+        
+        options = {:select => "distinct #{order.to_s == level.to_s ? '' : order.to_s+','} #{level}", :order => order}
+        values = []
+        find(:all, options).each do |dim|
+          value = dim.send(level_method)
+          values << dim.send(level_method) unless values.include?(value)
+        end
+        values.to_a
       end
       
       # Get an array of child values for a particular parent in the hierachy
       # For example, given a DateDimension with data from 2002 to 2004:
       # 
-      # available_child_values(:cy, [2002, 'Q1']) returns ['January', 'Feburary', 'March', 'April']
+      # available_child_values(:cy, [2002, 'Q1']) returns
+      # ['January', 'Feburary', 'March', 'April']
       def available_child_values(hierarchy_name, parent_values)
         if hierarchy_levels[hierarchy_name].nil?
           raise ArgumentError, "The hierarchy '#{hierarchy_name}' does not exist in your dimension #{name}"
@@ -210,9 +235,17 @@ module ActiveWarehouse #:nodoc
         child_level = connection.quote_column_name(child_level)
         order = level_orders[child_level] || self.order || child_level
         
-        options = {:select => child_level, :group => child_level, :order => order}
+        select_sql = "distinct #{child_level}"
+        select_sql += ", #{order}" unless order == child_level
+        options = {:select => select_sql, :order => order}
+
         options[:conditions] = conditions unless conditions.nil?
-        find(:all, options).collect {|dim| dim.send(child_level_method)}
+        values = []
+        find(:all, options).each do |dim|
+          value = dim.send(child_level_method)
+          values << dim.send(child_level_method) unless values.include?(value)
+        end
+        values.to_a
       end
       alias :available_children_values :available_child_values
       
@@ -286,6 +319,7 @@ module ActiveWarehouse #:nodoc
     end
     
     public
+    # Expire the value tree cache
     def expire_value_tree_cache
       self.class.expire_value_tree_cache
     end
@@ -293,4 +327,5 @@ module ActiveWarehouse #:nodoc
   end
 end
 
-require 'active_warehouse/dimension/bridge'
+require 'active_warehouse/dimension/date_dimension'
+require 'active_warehouse/dimension/dimension_view'

data/lib/active_warehouse/dimension/date_dimension.rb

@@ -0,0 +1,15 @@
+module ActiveWarehouse
+  # Explicit date dimension, because Date dimension has special columns
+  # which can be configured to have different names.
+  class DateDimension < Dimension
+    class << self
+      def set_sql_date_stamp(name)
+        @sql_date_stamp = name
+      end
+      
+      def sql_date_stamp
+        @sql_date_stamp ||= "sql_date_stamp"
+      end
+    end
+  end
+end

data/lib/active_warehouse/dimension/dimension_reflection.rb

@@ -0,0 +1,21 @@
+module ActiveWarehouse
+  module DimensionReflection
+    attr_reader :slowly_changing_over
+    
+    def slowly_changing_over=(reflection)
+      @slowly_changing_over = reflection
+      add_dependent_dimension_reflection(reflection)
+    end
+    
+    # add a dependent dimension reflection to this dimension reflection.
+    # some dimensions require others to operate, e.g. slowly changing dimensions
+    def add_dependent_dimension_reflection(dimension_reflection)
+      dependent_dimension_reflections << dimension_reflection
+    end
+    
+    # returns array of dependent dimension reflections
+    def dependent_dimension_reflections
+      @dependent_dimension_reflections ||= []
+    end
+  end
+end

data/lib/active_warehouse/dimension/dimension_view.rb

@@ -3,9 +3,24 @@ module ActiveWarehouse #:nodoc
   # a view for an existing dimension. A common use is to provide a date dimension and then provide numerous
   # role-playing dimensions implemented as views to the date dimension, such as Order Date Dimension, 
   # Shipping Date Dimension, etc.
-  class DimensionView < ActiveRecord::Base
+  class DimensionView < Dimension
     class << self
-      
+      def set_order(name)
+        super("#{self.sym}_#{name}".to_sym)
+      end
+      def define_hierarchy(name, hierarchy)
+        super(name, hierarchy.collect { |name| "#{self.sym}_#{name}".to_sym })
+      end
+    end
+    def method_missing(method_name, *args)
+      unless method_name.to_s =~ /^#{self.class.sym}_/
+        method_name = "#{self.class.sym}_#{method_name}".to_sym
+      end
+      if attribute_present?(method_name)
+        read_attribute(method_name)
+      else
+        raise NameError, "Attribute #{method_name} not found in #{self.class}"
+      end
     end
   end
 end

data/lib/active_warehouse/dimension/hierarchical_dimension.rb

@@ -24,8 +24,45 @@ module ActiveWarehouse #:nodoc
 
              # Get the bridge class name for this hierarchical dimension
              def bridge_class_name
-               name.gsub(/Dimension$/, '') + 'HierarchyBridge'
+               @child_hierarchy_relationship.class_name || @parent_hierarchy_relationship.class_name
              end
+
+            # Define the child relationship on the bridge table to the dimension
+            # table. We can specify a different class name for the bridge table
+            # and different foreign-key.
+            def child_bridge(association_id, options = {})
+              options[:class_name] ||= name.gsub(/Dimension$/, 'HierarchyBridge')
+              options[:foreign_key] ||= "parent_id"
+              has_many association_id, options
+              @child_hierarchy_relationship = reflections[association_id]
+            end
+
+            # Define the parent relationship on the bridge table to the dimension
+            # table. 
+            def parent_bridge(association_id, options = {})
+              options[:class_name] ||= name.gsub(/Dimension$/, 'HierarchyBridge')
+              options[:foreign_key] ||= "child_id"
+              has_many association_id, options
+              @parent_hierarchy_relationship = reflections[association_id]
+            end
+
+            # the foreign key column name on the bridge table for finding the
+            # children.
+            def child_foreign_key
+              @child_hierarchy_relationship.primary_key_name
+            end
+            
+            # the foreign key column name on the bridge table for finding the
+            # parent.
+            def parent_foreign_key
+              @parent_hierarchy_relationship.primary_key_name
+            end
+            
+            # the column name on the bridge table that defines the number of levels
+            # from the parent
+            def levels_from_parent
+              bridge_class.levels_from_parent
+            end
            end
         end
         include InstanceMethods
@@ -36,6 +73,7 @@ module ActiveWarehouse #:nodoc
       def hierarchical_dimension?
         self.included_modules.include?(InstanceMethods)
       end
+      
     end
     
     module InstanceMethods #:nodoc
@@ -43,16 +81,16 @@ module ActiveWarehouse #:nodoc
       def parent
         self.class.find(:first, 
           :select => "a.*",
-          :joins => "a join #{self.class.bridge_class.table_name} b on a.id = b.parent_id", 
-          :conditions => ['b.child_id = ? and b.levels_from_parent = 1', self.id])
+          :joins => "a join #{self.class.bridge_class.table_name} b on a.id = b.#{self.class.child_foreign_key}", 
+          :conditions => ["b.#{self.class.parent_foreign_key} = ? and b.#{self.class.levels_from_parent} = 1", self.id])
       end
   
       # Get the children for this node
       def children
         self.class.find(:all, 
           :select => "a.*",
-          :joins => "a join #{self.class.bridge_class.table_name} b on a.id = b.child_id", 
-          :conditions => ['b.parent_id = ? and b.levels_from_parent = 1', self.id])
+          :joins => "a join #{self.class.bridge_class.table_name} b on a.id = b.#{self.class.parent_foreign_key}", 
+          :conditions => ["b.#{self.class.child_foreign_key} = ? and b.#{self.class.levels_from_parent} = 1", self.id])
       end
     end
     

data/lib/active_warehouse/dimension/slowly_changing_dimension.rb

@@ -29,10 +29,10 @@ module ActiveWarehouse #:nodoc:
       # This is necessary because the find query used when :valid_on is specified is implemented using a between clause.
       #
       # Options:
-      # *<tt>:identifier</tt>: 
-      # *<tt>:lastest_version</tt>: Define the attribute name which represents the latest version flag
-      # *<tt>:effective_date</tt>: Define the attribute name which represents the effective date column
-      # *<tt>:expiration_date</tt>: Define the attribute name which represents the expiration date column
+      # * <tt>:identifier</tt>: 
+      # * <tt>:lastest_version</tt>: Define the attribute name which represents the latest version flag
+      # * <tt>:effective_date</tt>: Define the attribute name which represents the effective date column
+      # * <tt>:expiration_date</tt>: Define the attribute name which represents the expiration date column
       #
       def acts_as_slowly_changing_dimension(options = {})
         unless slowly_changing_dimension? # don't let AR call this twice
@@ -50,7 +50,7 @@ module ActiveWarehouse #:nodoc:
             alias_method :core_validate_find_options, :validate_find_options
             VALID_FIND_OPTIONS << :with_older
             VALID_FIND_OPTIONS << :valid_on
-            VALID_FIND_OPTIONS << :valid_on_or_after
+            VALID_FIND_OPTIONS << :valid_during
           end
         end
         include InstanceMethods
@@ -103,7 +103,7 @@ module ActiveWarehouse #:nodoc:
         protected
           def with_older_scope(&block)
             with_scope({:find => { :conditions =>
-                  "#{table_name}.#{latest_version_attribute} = 1" } }, :merge, &block)
+                  ["#{table_name}.#{latest_version_attribute} = ?", true] } }, :merge, &block)
           end
           
           def with_valid_on_scope(valid_on, &block)
@@ -112,19 +112,29 @@ module ActiveWarehouse #:nodoc:
                   "and #{expiration_date_attribute}", valid_on]} }, :merge, &block)
           end
           
-          def with_valid_on_or_after_scope(valid_on_or_after, &block)
+          def with_valid_during_scope(valid_during, &block)
             with_scope({:find => {:conditions =>
-                  ["#{effective_date_attribute} <= ? and #{expiration_date_attribute} > ?",
-                  valid_on_or_after, valid_on_or_after]} }, :merge, &block)
+                  ["(? between #{effective_date_attribute} and #{expiration_date_attribute})" +
+                  " or (#{effective_date_attribute} between ? and ?)",
+                  valid_during.first, valid_during.first, valid_during.last]} }, :merge, &block)
           end
-          
+
         private
           # all find calls lead here
           def find_every(options)
             if options.include?(:valid_on)
               with_valid_on_scope(options[:valid_on]) { find_every_with_older(options) }
-            elsif options.include?(:valid_on_or_after)
-              with_valid_on_or_after_scope(options[:valid_on_or_after]) { find_every_with_older(options) }
+            elsif options.include?(:valid_during)
+              if !options.include?(:order)
+                options[:order] = "#{effective_date_attribute} asc"
+              end
+              if !options.include?(:limit)
+                options[:limit] = 1
+              end
+              if !options.include?(:offset)
+                options[:offset] = 0
+              end
+              with_valid_during_scope(options[:valid_during]) { find_every_with_older(options) }
             elsif options.include?(:with_older)
               find_every_with_older(options)
             else