mainej-activewarehouse 0.3.0

data/activewarehouse/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/activewarehouse/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/activewarehouse/lib/active_warehouse/dimension/dimension_view.rb

@@ -0,0 +1,27 @@
+module ActiveWarehouse #:nodoc
+  # DimensionViews represent role-playing dimensions in a data warehouse. 
+  # These types of dimensions provide 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 < 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/activewarehouse/lib/active_warehouse/dimension/hierarchical_dimension.rb

@@ -0,0 +1,99 @@
+module ActiveWarehouse #:nodoc
+  # Implements a hierarchical dimension. Including the 
+  # <tt>acts_as_hierarchical_dimension</tt> directive in a dimension will add
+  # methods for accessing the parent and children of any node in the hierarchy.
+  module HierarchicalDimension
+    def self.included(base) #:nodoc
+      base.extend(ClassMethods)
+    end
+    
+    module ClassMethods #:nodoc
+      # Indicates that a dimension is a variable-depth hierarchy.
+      def acts_as_hierarchy_dimension
+        unless hierarchical_dimension?
+           class << self
+             # Get the bridge class for this dimension
+             def bridge_class
+               unless @bridge_class
+                 unless Object.const_defined?(bridge_class_name.to_sym)
+                   Object.const_set(bridge_class_name.to_sym, Class.new(ActiveWarehouse::Bridge))
+                 end
+                 @bridge_class = Object.const_get(bridge_class_name.to_sym)
+               end
+               @bridge_class
+             end
+
+             # Get the bridge class name for this hierarchical dimension
+             def bridge_class_name
+               @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
+      end
+      alias :acts_as_hierarchical_dimension :acts_as_hierarchy_dimension
+      
+      # Return true if this is a hierarchical dimension
+      def hierarchical_dimension?
+        self.included_modules.include?(InstanceMethods)
+      end
+      
+    end
+    
+    module InstanceMethods #:nodoc
+      # Get the parent for this node
+      def parent
+        self.class.find(:first, 
+          :select => "a.*",
+          :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.#{self.class.parent_foreign_key}", 
+          :conditions => ["b.#{self.class.child_foreign_key} = ? and b.#{self.class.levels_from_parent} = 1", self.id])
+      end
+    end
+    
+  end
+end

data/activewarehouse/lib/active_warehouse/dimension/slowly_changing_dimension.rb

@@ -0,0 +1,147 @@
+module ActiveWarehouse #:nodoc:
+  # Implements Type 2 Slowly Changing Dimensions.
+  #
+  # In a type 2 SCD, a new row is added each time a dimension entry requires an update. Three columns are required in
+  # the dimension table to support this:
+  #
+  # * latest_version - A boolean flag which indicates whether or not the row is the latest and current value
+  # * effective_date - A start date for when this row takes effect
+  # * expiration_date - An end date for when this row expires
+  #
+  # This module will override finder behavior in several ways. If used in a normal fashion, the find method will return
+  # the match row or rows with the latest_version flag set to true. You can also call the finder with the :valid_on 
+  # option set indicating that you want the row that is valid on the given date.
+  #
+  # You can completely override the modified finder behavior using the :with_older option (set to true). You *must* include
+  # this option if you want to search for records which are not current (for example, using the find(id) version of the finder
+  # methods).
+  module SlowlyChangingDimension
+    def self.included(base) # :nodoc:
+      base.extend ClassMethods
+    end
+
+    module ClassMethods
+      # Indicate that the dimension is a Type 2 Slowly Changing Dimension (SDC).
+      #
+      # A word of warning:
+      #
+      # The expiration_date field must never be null. For the current effective record use the maximum date allowed. 
+      # 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
+      #
+      def acts_as_slowly_changing_dimension(options = {})
+        unless slowly_changing_dimension? # don't let AR call this twice
+          cattr_accessor :identifier
+          cattr_accessor :latest_version_attribute
+          cattr_accessor :effective_date_attribute
+          cattr_accessor :expiration_date_attribute
+          self.identifier = options[:identifier] || :identifier
+          self.latest_version_attribute = options[:with] || :latest_version
+          self.effective_date_attribute = options[:effective_date_attribute] || :effective_date
+          self.expiration_date_attribute = options[:expiration_date_attribute] || :expiration_date
+          class << self
+            alias_method :find_every_with_older,    :find_every
+            alias_method :calculate_with_older,     :calculate
+            alias_method :core_validate_find_options, :validate_find_options
+            VALID_FIND_OPTIONS << :with_older
+            VALID_FIND_OPTIONS << :valid_on
+            VALID_FIND_OPTIONS << :valid_during
+          end
+        end
+        include InstanceMethods
+      end
+      
+      # Return true if this dimension is a slowly changing dimension
+      def slowly_changing_dimension?
+        self.included_modules.include?(InstanceMethods)
+      end
+    end
+
+    module InstanceMethods #:nodoc:
+      def self.included(base) # :nodoc:
+        base.extend ClassMethods
+      end
+      
+      def versions
+        self.class.find(:all,
+            :conditions => ["#{self.class.identifier} = ?", self.send(identifier)],
+            :with_older => true,
+            :order => "#{self.class.effective_date_attribute} asc")
+      end
+
+      module ClassMethods
+        def find_with_older(*args)
+          options = extract_options_from_args!(args)
+          validate_find_options(options)
+          set_readonly_option!(options)
+          options[:with_older] = true # yuck!
+
+          case args.first
+            when :first then find_initial(options)
+            when :all   then find_every(options)
+            else             find_from_ids(args, options)
+          end
+        end
+
+        def count_with_older(*args)
+          calculate_with_older(:count, *construct_count_options_from_legacy_args(*args))
+        end
+
+        def count(*args)
+          with_older_scope { count_with_older(*args) }
+        end
+
+        def calculate(*args)
+          with_older_scope { calculate_with_older(*args) }
+        end
+
+        protected
+          def with_older_scope(&block)
+            with_scope({:find => { :conditions =>
+                  ["#{table_name}.#{latest_version_attribute} = ?", true] } }, :merge, &block)
+          end
+          
+          def with_valid_on_scope(valid_on, &block)
+            with_scope({:find => { :conditions =>
+                  ["? between #{effective_date_attribute} " +
+                  "and #{expiration_date_attribute}", valid_on]} }, :merge, &block)
+          end
+          
+          def with_valid_during_scope(valid_during, &block)
+            with_scope({:find => {:conditions =>
+                  ["(? 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_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
+              with_older_scope { find_every_with_older(options) }
+            end
+          end
+      end
+    end
+  end
+end

data/activewarehouse/lib/active_warehouse/fact.rb

@@ -0,0 +1,239 @@
+module ActiveWarehouse #:nodoc
+
+  # Facts represent business measures. A row in a fact table corresponds to set
+  # of measurements in a particular
+  # granularity along with the foreign keys connecting the fact to various
+  # dimensions. All measurements in a fact
+  # table must be at the same grain.
+  class Fact < ActiveRecord::Base
+    class << self
+      # Array of AggregateField instances
+      attr_accessor :aggregate_fields
+      
+      # Array of calculated field names
+      attr_accessor :calculated_fields
+      
+      # Hash of calculated field options, where the key is the field name
+      # and the value is the Hash of options for that calculated field.
+      attr_accessor :calculated_field_options
+      
+      # Array of belongs_to +Reflection+ instances that represent the
+      # dimensions for this fact.
+      attr_accessor :dimension_relationships
+      
+      # Acts as an alias for +belongs_to+, yet marks this relationship
+      # as a dimension.  You must call +dimension+ instead of +belongs_to+.
+      # Accepts same options as +belongs_to+.
+      def dimension(association_id, options = {})
+        options[:class_name] ||= "#{association_id}Dimension".classify
+        options[:foreign_key] ||= "#{association_id}_id"
+        slowly_changing_over = options.delete(:slowly_changing)
+        belongs_to association_id, options
+        relationship = reflections[association_id]
+        
+        if slowly_changing_over
+          if !dimensions.include?(slowly_changing_over)
+            raise "No dimension specified with name '#{slowly_changing_over}' in fact '#{self.name}', specify it first with dimension macro"
+          end
+          relationship.slowly_changing_over = dimension_relationships[slowly_changing_over]
+        end
+        
+        dimension_relationships[association_id] = relationship
+      end
+
+      # Acts as an alias for +has_and_belongs_to_many+, yet marks this relationship
+      # as a dimension.  You must call +has_and_belongs_to_many_dimension+ 
+      # instead of +has_and_belongs_to_many+.
+      # Accepts same options as +has_and_belongs_to_many+.
+      def has_and_belongs_to_many_dimension(association_id, options = {})
+        options[:class_name] ||= "#{association_id}Dimension".classify
+        options[:association_foreign_key] ||= "#{association_id}_id"
+        name = self.name.demodulize.chomp('Fact').underscore
+        options[:join_table] ||= "#{name}_#{association_id}_bridge"
+        has_and_belongs_to_many association_id, options
+        relationship = reflections[association_id]
+        dimension_relationships[association_id] = relationship
+      end
+      
+      # returns true for the dimension relationship of +belongs_to+
+      def belongs_to_relationship?(dimension_name)
+        dimension_relationships[dimension_name] and dimension_relationships[dimension_name].macro == :belongs_to  
+      end
+      
+      # returns true for the dimension relationship of +has_and_belongs_to_many+
+      def has_and_belongs_to_many_relationship?(dimension_name)
+        dimension_relationships[dimension_name] and dimension_relationships[dimension_name].macro == :has_and_belongs_to_many
+      end
+      
+      # returns the AssociationReflection for the specified dimension name
+      def dimension_relationship(dimension_name)
+        dimension_relationships[dimension_name]
+      end
+
+      # returns the dimension name (as specified in the dimension macro)
+      # which the specified +dimension_name+ is slowly changing over
+      def slowly_changes_over_name(dimension_name)
+        dimension_relationships[dimension_name].slowly_changing_over.name
+      end
+      
+      # returns the Class for the dimension which the specified
+      # +dimension_name+ is slowly changing over
+      def slowly_changes_over_class(dimension_name)
+        dimension_class(slowly_changes_over_name(dimension_name))
+      end
+      
+      # Return a list of dimensions for this fact. 
+      #
+      # Example:
+      #
+      # sales_fact
+      #  date_id
+      #  region_id
+      #  sales_amount
+      #  number_items_sold
+      # 
+      # Calling SalesFact.dimensions would return the list: [:date, :region]
+      def dimensions
+        dimension_relationships.collect { |k,v| k }
+      end
+      
+      # Returns the dimension class, given a dimension name from this fact.
+      # Must appear as a registered dimension relationship.
+      def dimension_class(dimension_name)
+        dimension_relationships[dimension_name.to_sym].class_name.constantize
+      end
+      
+      # Get the time when the fact source file was last modified
+      def last_modified
+        File.new(__FILE__).mtime
+      end
+      
+      # Get the table name. The fact table name is pluralized
+      def table_name
+        name = self.name.demodulize.underscore.pluralize
+        set_table_name(name)
+        name
+      end
+      
+      # Get the class name for the specified fact name
+      def class_name(name)
+        fact_name = name.to_s
+        fact_name = "#{fact_name}_facts" unless fact_name =~ /_fact[s?]$/
+        fact_name.classify
+      end
+      
+      # Get the class for the specified fact name
+      def class_for_name(name)
+        class_name(name).constantize
+      end
+      
+      # Get the fact class for the specified value. The fact parameter may be a class,
+      # String or Symbol.
+      def to_fact(fact_name)
+        return fact_name if fact_name.is_a?(Class) and fact_name.superclass == Fact
+        return class_for_name(fact_name)
+      end
+      
+      # Return the foreign key that the fact uses to relate back to the specified 
+      # dimension. This is found using the dimension_relationships hash.
+      def foreign_key_for(dimension_name)
+        dimension_relationships[dimension_name].primary_key_name
+      end
+      
+      # Define an aggregate. Also aliased from aggregate()
+      # * <tt>field</tt>: The field name
+      # * <tt>options</tt>: A hash of options for the aggregate
+      def define_aggregate(field, options={})
+        if columns_hash[field.to_s].nil?
+          raise ArgumentError, "Field #{field} does not exist in table #{table_name}"
+        end
+        options[:type] ||= :sum
+        
+        aggregate_field = AggregateField.new(self, columns_hash[field.to_s],
+                                             options[:type], options)
+        aggregate_fields << aggregate_field
+      end
+      alias :aggregate :define_aggregate
+      
+      # Define prejoined fields from a dimension of the fact. Also aliased
+      # from prejoin()
+      # * <tt>field</tt>: A hash with the key of dimension and an array
+      # of attributes from the dimension as value
+      def define_prejoin(field)
+        prejoined_fields.merge!(field)
+      end
+      alias :prejoin :define_prejoin
+      
+      # Define a calculated field
+      # * <tt>field</tt>: The field name
+      # * <tt>options</tt>: An options hash
+      # 
+      # This method takes a block which will be passed the current aggregate record.
+      #
+      # Example: calculated_field (:gross_margin) { |r| r.gross_profit_dollar_amount / r.sales_dollar_amount}
+      def calculated_field(field, options={}, &block)
+        calculated_fields << CalculatedField.new(self, field, options[:type], options, &block)
+      end
+      
+      # Returns true if this fact has at least one fact that is semiadditive,
+      # or false
+      def has_semiadditive_fact?
+        aggregate_fields.each do |field|
+          return true if field.is_semiadditive?
+        end
+        return false
+      end
+      
+      # Get a list of all calculated fields
+      def calculated_fields
+        @calculated_field ||= []
+      end
+      
+      # Get the CalculatedField instance for the specified name
+      def calculated_field_for_name(name)
+        calculated_fields.find {|f| f.name.to_s == name.to_s}
+      end
+      
+      # Get a list of all aggregate fields
+      def aggregate_fields
+        @aggregate_fields ||= []
+      end
+      
+      # Get the AggregateField instance for the specified name.
+      def aggregate_field_for_name(name)
+        aggregate_fields.find {|f| f.name.to_s == name.to_s}
+      end
+      
+      # Get the field instance for the specified name. Looks in aggregate fields first, then
+      # calculated fields
+      def field_for_name(name)
+        field = aggregate_fields.find {|f| f.name.to_s == name.to_s}
+        field = calculated_fields.find {|f| f.name.to_s == name.to_s} unless field
+        field
+      end
+      
+      # The table name to use for the prejoined fact table
+      def prejoined_table_name
+        "prejoined_#{table_name}"
+      end
+            
+      # Get the hash of all prejoined fields
+      def prejoined_fields
+        @prejoined_fields ||= {}
+      end
+      
+      def dimension_relationships
+        @dimension_relationships ||= OrderedHash.new
+      end
+      
+      def prejoin_fact
+        @prejoin_fact ||= ActiveWarehouse::PrejoinFact.new(self)
+      end
+      
+      def populate
+        prejoin_fact.populate
+      end
+
+    end
+  end
+end