mainej-activewarehouse 0.3.0

data/activewarehouse/lib/active_warehouse/cube.rb

@@ -0,0 +1,235 @@
+module ActiveWarehouse
+  # A Cube represents a collection of dimensions operating on a fact. The Cube
+  # provides a front-end for getting at the
+  # underlying data. Cubes support pluggable aggregation. The default aggregation
+  # is the NoAggregate which goes directly
+  # to the fact and dimensions to answer queries.
+  class Cube
+    class << self
+      
+      # Callback which is invoked when subclasses are created
+      def inherited(subclass)
+        subclasses << subclass
+      end
+      
+      # Get a list of all known subclasses
+      def subclasses
+        @subclasses ||= []
+      end
+      
+      # Defines the dimensions that this cube pivots on. If the fact name and
+      # cube name are different (for example, if a PurchaseCube does not report
+      # on a PurchaseFact) then you *must* declare the <code>reports_on</code>
+      # first.
+      def pivots_on(*dimension_list)
+        @dimensions_hierarchies = OrderedHash.new
+        @dimensions = []
+        dimension_list.each do |dimension|
+          case dimension
+          when Symbol, String
+            dimensions << dimension.to_sym
+            dimensions_hierarchies[dimension.to_sym] = fact_class.dimension_class(dimension).hierarchies
+          when Hash
+            dimension_name = dimension.keys.first.to_sym
+            dimensions << dimension_name
+            dimensions_hierarchies[dimension_name] = [dimension[dimension_name]].flatten
+          else
+            raise ArgumentError, "Each argument to pivot_on must be a symbol, string or Hash"
+          end
+        end
+      end
+      alias :pivot_on :pivots_on
+      
+      # Defines the fact name, without the 'Fact' suffix, that this cube
+      # reports on.  For instance, if you have PurchaseFact, you could then
+      # call <code>reports_on :purchase</code>.
+      # 
+      # The default value for reports_on is to take the name of the cube,
+      # i.e. PurchaseCube, and remove the Cube suffix.  The assumption is that
+      # your Cube name matches your Fact name.
+      def reports_on(fact_name)
+        @fact_name = fact_name
+      end
+      alias :report_on :reports_on
+      
+      # Rebuild the data warehouse.
+      def rebuild(options={})
+        populate(options)
+      end
+      
+      # Populate the data warehouse.  Delegate to aggregate.populate
+      def populate(options={})
+        aggregate.populate
+      end
+      
+      # Get the dimensions that this cube pivots on
+      def dimensions
+        @dimensions ||= fact_class.dimension_relationships.collect{|k,v| k}
+      end
+      
+      # Get an OrderedHash of each dimension mapped to its hierarchies which 
+      # will be included in the cube
+      def dimensions_hierarchies
+        if @dimensions_hierarchies.nil?
+          @dimensions_hierarchies = OrderedHash.new
+          dimensions.each do |dimension|
+            @dimensions_hierarchies[dimension] = fact_class.dimension_class(dimension).hierarchies
+          end
+        end
+        @dimensions_hierarchies
+      end
+      
+      # returns true if this cube pivots on a hierarchical dimension.
+      def pivot_on_hierarchical_dimension?
+        dimension_classes.each do |dimension|
+          return true if dimension.hierarchical_dimension?
+        end
+        return false
+      end
+      
+      # returns the aggregate fields for this cube
+      # removing the aggregate fields that are defined in fact class that are
+      # related to hierarchical dimension, but the cube doesn't pivot on any
+      # hierarchical dimensions
+      # The method also further removes the not appropreate aggregate fields
+      # for the type of dimensions passed in if they exists.
+      def aggregate_fields(dims=[])
+        agg_fields = fact_class.aggregate_fields.reject {|field| !pivot_on_hierarchical_dimension? and !field.levels_from_parent.empty? } 
+        dims.each do |dim|
+          if !dim.blank? and fact_class.has_and_belongs_to_many_relationship?(dim.to_sym)
+            return agg_fields.reject {|field| !field.is_count_distinct?}
+          end
+        end
+        agg_fields
+      end
+      
+      def calculated_fields
+        fact_class.calculated_fields
+      end
+      
+      def fields(dims=[])
+        aggregate_fields(dims) + calculated_fields
+      end
+      
+      def field_names(dims=[])
+        fields(dims).map { |field| field.name.to_sym }
+      end
+      
+      def fields_for_select(dims=[])
+        fields(dims).inject({}) { |select_hash, field| select_hash.update field.label.to_s => field.name.to_sym }
+      end
+      
+      # Get the class name for the specified cube name
+      # Example: Regional Sales will become RegionalSalesCube
+      def class_name(name)
+        cube_name = name.to_s
+        cube_name = "#{cube_name}_cube" unless cube_name =~ /_cube$/
+        cube_name.classify
+      end
+      
+      # Get the aggregated fact class name
+      def fact_class_name
+        ActiveWarehouse::Fact.class_name(@fact_name || name.sub(/Cube$/,'').underscore.to_sym)
+      end
+      
+      # Get the aggregated fact class instance
+      def fact_class
+        fact_class_name.constantize
+      end
+      
+      # Get a list of dimension class instances
+      def dimension_classes
+        dimensions.collect do |dimension_name|
+          dimension_class(dimension_name)
+        end
+      end
+      
+      # Get the dimension class for the specified dimension name
+      def dimension_class(dimension_name)
+        fact_class.dimension_relationships[dimension_name.to_sym].class_name.constantize      
+      end
+      
+      # Get the cube logger
+      def logger
+        @logger ||= Logger.new('cube.log')
+      end
+      
+      # Get the time when the fact or any dimension referenced in this cube 
+      # was last modified
+      def last_modified
+        lm = fact_class.last_modified
+        dimensions.each do |dimension|
+          dim = ActiveWarehouse::Dimension.class_for_name(dimension)
+          lm = dim.last_modified if dim.last_modified > lm
+        end
+        lm
+      end
+      
+      # The temp directory for storing files during warehouse rebuilds
+      attr_accessor :temp_dir
+      def temp_dir
+        @temp_dir ||= '/tmp'
+      end
+      
+      # Specify the ActiveRecord class to connect through
+      # Note: this is a potential directive in a Cube subclass
+      attr_accessor :connect_through
+      def connect_through
+        @connect_through ||= ActiveRecord::Base
+      end
+      
+      # Get an adapter connection
+      def connection
+        connect_through.connection
+      end
+      
+      # Defaults to NoAggregate strategy.
+      def aggregate
+        @aggregate ||= ActiveWarehouse::Aggregate::NoAggregate.new(self)
+      end
+      
+      def aggregate_class(agg_class)
+        @aggregate = agg_class.new(self)
+      end
+      
+    end
+    
+    public
+    # Query the cube. The column dimension, column hierarchy, row dimension and
+    # row hierarchy are all required.
+    #
+    # The conditions value is a String that represents a SQL condition appended
+    # to the where clause. TODO: this may eventually be converted to another
+    # query language.
+    #
+    # The cstage value represents the current  column drill down stage and 
+    # defaults to 0.
+    # 
+    # The rstage value represents the current row drill down stage and defaults 
+    # to 0. Filters contains key/value pairs where the key is a string of 
+    # 'dimension.column' and the value is the value to filter by. For example:
+    #
+    # filters = {'date.calendar_year' => 2007, 'product.category' => 'Food'}
+    # query(:date, :cy, :store, :region, 1, 0, filters)
+    #
+    # Note that product.category refers to a dimension which is not actually 
+    # visible but which is both part of the cube and is used for filtering.
+    def query(*args)
+      self.class.aggregate.query(*args)
+    end
+    
+    # Similar to query, but expects slightly different arguments.  See
+    # ActiveWarehouse::Aggregate::Aggregate.query_row_and_column for
+    # details.
+    def query_row_and_column(*args)
+      self.class.aggregate.query_row_and_column(*args)
+    end
+    
+    # Get the database connection (delegates to Cube.connection class method)
+    def connection
+      self.class.connection
+    end
+    
+  end
+  
+end

data/activewarehouse/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.to_s)
+    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.to_s]
+      return empty_hash_for_missing_row_or_column if row.nil?
+      facts = row[col_value.to_s]
+      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.to_s] ||= {}
+      @values_map[row_value.to_s][col_value.to_s] = 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/activewarehouse/lib/active_warehouse/dimension.rb

@@ -0,0 +1,329 @@
+# 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.
+  class Dimension < ActiveRecord::Base
+    include ActiveWarehouse::HierarchicalDimension
+    include ActiveWarehouse::SlowlyChangingDimension
+    
+    after_save :expire_value_tree_cache
+    
+    class << self
+      # Alternate order by, to be used rather than the current level being queried
+      attr_accessor :order
+      
+      # 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:
+      # * available_values
+      # * available_child_values
+      # * available_values_tree
+      def set_order(name)
+        @order = name
+      end
+      
+      # Define a column to order by for a specific level.
+      def set_level_order(level, name)
+        level_orders[level] = name
+      end
+      
+      # Get the level orders map
+      def level_orders
+        @level_orders ||= {}
+      end
+      
+      # Define a named attribute hierarchy in the dimension.
+      # 
+      # Example: define_hierarchy(:fiscal_calendar, [:fiscal_year, :fiscal_quarter, :fiscal_month])
+      # 
+      # 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.
+      def define_hierarchy(name, levels)
+        hierarchies << name
+        hierarchy_levels[name] = levels
+      end
+      
+      # Get the named attribute hierarchy. Returns an array of column names.
+      # 
+      # Example: hierarchy(:fiscal_calendar) might return [:fiscal_year, :fiscal_quarter, :fiscal_month]
+      def hierarchy(name)
+        hierarchy_levels[name]
+      end
+      
+      # Get the ordered hierarchy names
+      def hierarchies
+        @hierarchies ||= []
+      end
+      
+      # Get the hierarchy levels hash
+      def hierarchy_levels
+        @hierarchy_levels ||= {}
+      end
+      
+      # 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
+      def sym
+        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.
+      #
+      # Example: DateDimension will have a table called date_dimension
+      def table_name
+        name = self.name.demodulize.underscore
+        set_table_name(name)
+        name
+      end
+      
+      # Convert the given name into a dimension class name
+      def class_name(name)
+        dimension_name = name.to_s
+        dimension_name = "#{dimension_name}_dimension" unless dimension_name =~ /_dimension$/
+        dimension_name.classify
+      end
+      
+      # Get a class for the specified named dimension
+      def class_for_name(name)
+        class_name(name).constantize
+      end
+      
+      # 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.
+      def to_dimension(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:
+      # 
+      #  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}
+      # 
+      # If the denominator_level parameter is omitted or nil then:
+      #
+      #  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?
+          raise ArgumentError, "The hierarchy '#{hierarchy_name}' does not exist in your dimension #{name}"
+        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 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)
+
+          if level_index.nil?
+            raise ArgumentError, "The level '#{level}' does not appear to exist"
+          end
+          if denominator_index.nil?
+            raise ArgumentError, "The denominator level '#{denominator_level}' does not appear to exist"
+          end
+          if hierarchy_levels[hierarchy_name].index(denominator_level) < hierarchy_levels[hierarchy_name].index(level)
+            raise ArgumentError, "The index of the denominator level '#{denominator_level}' in the hierarchy '#{hierarchy_name}' must be greater than or equal to the level '#{level}'"
+          end
+
+          q = "select #{level} as level, count(distinct(#{denominator_level})) as level_count from #{table_name} group by #{level}"
+        else
+          q = "select #{level} as level, count(id) as level_count from #{table_name} group by #{level}"
+        end
+        denominators = {}
+        connection.select_all(q).each do |row|
+          denominators[row['level']] = row['level_count'].to_i
+        end
+        denominators
+      end
+      
+      # 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
+      
+      # Get an array of the available values for a particular hierarchy level
+      # For example, given a DateDimension with data from 2002 to 2004:
+      #
+      #  available_values('calendar_year') returns ['2002','2003','2004']
+      def available_values(level)
+        level_method = level.to_sym
+        level = connection.quote_column_name(level.to_s)
+        order = level_orders[level] || self.order || level
+        
+        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']
+      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}"
+        end
+
+        levels = hierarchy_levels[hierarchy_name]
+        if levels.length <= parent_values.length
+          raise ArgumentError, "The parent_values '#{parent_values.to_yaml}' exceeds the hierarchy depth #{levels.to_yaml}"
+        end
+        
+        child_level = levels[parent_values.length].to_s
+        
+        # Create the conditions array. Will work with 1.1.6.
+        conditions_parts = []
+        conditions_values = []
+        parent_values.each_with_index do |value, index|
+          conditions_parts << "#{levels[index]} = ?"
+          conditions_values << value
+        end
+        conditions = [conditions_parts.join(' AND ')] + conditions_values unless conditions_parts.empty?
+        
+        child_level_method = child_level.to_sym
+        child_level = connection.quote_column_name(child_level)
+        order = level_orders[child_level] || self.order || child_level
+        
+        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).map do |dim|
+          dim.send(child_level_method)
+        end.uniq
+      end
+      alias :available_children_values :available_child_values
+      
+      # Get a tree of Node objects for all of the values in the specified hierarchy.
+      def available_values_tree(hierarchy_name)
+        root = value_tree_cache[hierarchy_name]
+        if root.nil?
+          root = Node.new('All', '__ROOT__')
+          levels = hierarchy(hierarchy_name)
+          nodes = {nil => root}
+          level_list = levels.collect{|level| connection.quote_column_name(level) }.join(',')
+          order = self.order || level_list
+          find(:all, :select => level_list, :group => level_list, :order => order).each do |dim|
+            parent_node = root
+            levels.each do |level|
+              node_value = dim.send(level)
+              child_node = parent_node.optionally_add_child(node_value, level)
+              parent_node = child_node
+            end
+          end
+          value_tree_cache[hierarchy_name] = root
+        end
+        root
+      end
+      
+      protected
+      # Get the value tree cache
+      def value_tree_cache
+        @value_tree_cache ||= {}
+      end
+      
+      class Node#:nodoc:
+        attr_reader :value, :children, :parent, :level
+
+        def initialize(value, level, parent = nil)
+          @children = []
+          @value = value
+          @parent = parent
+          @level = level
+        end
+
+        def has_child?(child_value)
+          !self.child(child_value).nil?
+        end
+
+        def child(child_value)
+          @children.each do |c|
+            return c if c.value == child_value
+          end
+          nil
+        end
+
+        def add_child(child_value, level)
+          child = Node.new(child_value, level, self)
+          @children << child
+          child
+        end
+        
+        def optionally_add_child(child_value, level)
+          c = child(child_value)
+          c = add_child(child_value, level) unless c
+          c
+        end
+      end
+      
+      public
+      # Expire the value tree cache. This should be called if the dimension
+      def expire_value_tree_cache
+        @value_tree_cache = nil
+      end
+    end
+    
+    public
+    # Expire the value tree cache
+    def expire_value_tree_cache
+      self.class.expire_value_tree_cache
+    end
+    
+  end
+end
+
+require 'active_warehouse/dimension/date_dimension'
+require 'active_warehouse/dimension/dimension_view'