activewarehouse 0.2.0 → 0.3.0

data/lib/active_warehouse/fact.rb

@@ -1,16 +1,15 @@
 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
+
+  # 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 aggregate field names
+      # Array of AggregateField instances
       attr_accessor :aggregate_fields
       
-      # Hash of aggregate field options, where the key is the field name
-      # and the value is the Hash of options for that aggregate.
-      attr_accessor :aggregate_field_options
-      
       # Array of calculated field names
       attr_accessor :calculated_fields
       
@@ -18,6 +17,42 @@ module ActiveWarehouse #:nodoc
       # 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
+        dimension_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
+          dimension_relationship.slowly_changing_over = dimension_relationships[slowly_changing_over]
+        end
+        
+        dimension_relationships[association_id] = dimension_relationship
+      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:
@@ -30,27 +65,13 @@ module ActiveWarehouse #:nodoc
       # 
       # Calling SalesFact.dimensions would return the list: [:date, :region]
       def dimensions
-        foreign_key_columns.collect { |c| c.name.gsub(/_id/, '').to_sym }
+        dimension_relationships.collect { |k,v| k }
       end
       
-      # Get all of the Column objects representing foreign key columns
-      # 
-      # Example:
-      #
-      # sales_fact
-      #  date_id
-      #  region_id
-      #  sales_amount
-      #  number_items_sold
-      # 
-      # Calling SalesFact.foreign_key_columns would return a list of column objects containing
-      # the date column and the region column.
-      def foreign_key_columns
-        fk_columns = []
-        columns.each do |column|
-          fk_columns << column if column.name =~ /(.*)_id/
-        end
-        fk_columns
+      # 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
@@ -79,21 +100,41 @@ module ActiveWarehouse #:nodoc
       
       # Get the fact class for the specified value. The fact parameter may be a class,
       # String or Symbol.
-      def to_fact(dimension)
-        return dimension if dimension.is_a?(Class) and dimension.superclass == Fact
-        return class_for_name(dimension)
+      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={})
-        aggregate_fields << field
+        if columns_hash[field.to_s].nil?
+          raise ArgumentError, "Field #{field} does not exist in table #{table_name}"
+        end
         options[:type] ||= :sum
-        aggregate_field_options[field] = options
+        
+        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
@@ -102,9 +143,16 @@ module ActiveWarehouse #:nodoc
       #
       # Example: calculated_field (:gross_margin) { |r| r.gross_profit_dollar_amount / r.sales_dollar_amount}
       def calculated_field(field, options={}, &block)
-        calculated_fields << field
-        options[:block] = block
-        calculated_field_options[field] = options
+        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
@@ -112,9 +160,9 @@ module ActiveWarehouse #:nodoc
         @calculated_field ||= []
       end
       
-      # Get a hash of all calculated field options
-      def calculated_field_options
-        @calculated_field_options ||= {}
+      # 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
@@ -122,10 +170,41 @@ module ActiveWarehouse #:nodoc
         @aggregate_fields ||= []
       end
       
-      # Get a hash of all aggregate field options
-      def aggregate_field_options
-        @aggregate_field_options ||= {}
+      # 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

data/lib/active_warehouse/field.rb

@@ -0,0 +1,74 @@
+module ActiveWarehouse #:nodoc:
+  # Encapsulates a field.
+  class Field
+    # The owning class which is either a Fact or Dimension
+    attr_reader :owning_class
+    
+    # The field name
+    attr_reader :name
+    
+    # The field type
+    attr_reader :type
+    
+    attr_accessor :limit
+    attr_accessor :scale
+    attr_accessor :precision
+    
+    # A Hash of options for the field
+    attr_reader :field_options
+    
+    # +owning_class+ is the class of the table, either Fact or Dimension, that
+    # this field is found in.  Must somehow subclass ActiveRecord::Base
+    # +name+ is the name of this field.
+    # +field_options+ is a hash of raw options from the original definition.
+    # Options can include :label => a column alias or label for this field,
+    # :table_alias for a table alias (useful for building queries)
+    def initialize(owning_class, name, type, field_options = {})
+      @owning_class = owning_class
+      @name = name
+      @type = type
+      @field_options = field_options
+      @label = field_options[:label]
+      @table_alias = field_options[:table_alias]
+    end
+    
+    # returns the :label set in field_options, or from_table_name+'_'+name.
+    # Unless you have table_alias specified, then label will return table_alias+'_'+name.
+    # The default label can exceed database limits, so use :label to override.
+    def label
+      @label ? @label : "#{table_alias || from_table_name}_#{name}"
+    end
+    
+    # returns name of this field, matches name of the column
+    def name
+      @name
+    end
+    
+    # returns rails specific column type, e.g. :float or :string
+    def column_type
+      @type
+    end
+    
+    # convert the label into something we can use in a table.
+    # i.e., 'Sum of Transactions' becomes 'sum_of_transactions'
+    def label_for_table
+      label.gsub(/ /, '_').downcase
+    end
+    
+    # returns the table name that has this fact column
+    def from_table_name
+      owning_class.table_name
+    end
+    
+    # returns a table alias or if none set just the table name
+    def table_alias
+      @table_alias || from_table_name
+    end
+    
+    # Get a display string for the field. Delegates to label.
+    def to_s
+      label
+    end
+    
+  end
+end

data/lib/active_warehouse/ordered_hash.rb

@@ -0,0 +1,34 @@
+module ActiveWarehouse
+  # Simple ordered hash implementation
+  class OrderedHash < Hash
+    alias_method :store, :[]=
+    alias_method :each_pair, :each
+  
+    def initialize
+      @keys = []
+    end
+  
+    def []=(key, val)
+      @keys << key
+      super
+    end
+  
+    def delete(key)
+      @keys.delete(key)
+      super
+    end
+  
+    def each
+      @keys.each { |k| yield k, self[k] }
+    end
+  
+    def each_key
+      @keys.each { |k| yield k }
+    end
+  
+    def each_value
+      @keys.each { |k| yield self[k] }
+    end
+    
+  end
+end

data/lib/active_warehouse/prejoin_fact.rb

@@ -0,0 +1,97 @@
+module ActiveWarehouse #:nodoc:
+  # Class that supports prejoining a fact table with dimensions. This is useful if you need
+  # to list facts along with some or all of their detail information.
+  class PrejoinFact
+    # The fact class that this engine instance is connected to
+    attr_accessor :fact_class
+    
+    delegate :prejoined_table_name, 
+      :connection, 
+      :prejoined_fields,
+      :dimension_relationships, 
+      :dimension_class, 
+      :table_name,
+      :columns, :to => :fact_class
+  
+    # Initialize the engine instance
+    def initialize(fact_class)
+      @fact_class = fact_class
+    end
+  
+    # Populate the prejoined fact table.
+    def populate(options={})
+      populate_prejoined_fact_table(options)
+    end
+    
+    protected
+    # Drop the storage table
+    def drop_prejoin_fact_table
+      connection.drop_table(prejoined_table_name) if connection.tables.include?(prejoined_table_name)
+    end
+    
+    # Get foreign key names that are excluded.
+    def excluded_foreign_key_names
+      excluded_dimension_relations = prejoined_fields.keys.collect {|k| dimension_relationships[k]}
+      excluded_dimension_relations.collect {|r| r.primary_key_name}
+    end
+    
+    # Construct the prejoined fact table.
+    def create_prejoined_fact_table(options={})
+      connection.transaction {
+        drop_prejoin_fact_table
+
+        connection.create_table(prejoined_table_name, :id => false) do |t|
+          # get all columns except the foreign_key columns for prejoined dimensions
+          columns.each do |c|
+            t.column(c.name, c.type) unless excluded_foreign_key_names.include?(c.name)
+          end
+          #prejoined_columns
+          prejoined_fields.each_pair do |key, value|
+            dclass = dimension_class(key)
+            dclass.columns.each do |c|
+              t.column(c.name, c.type) if value.include?(c.name.to_sym) 
+            end
+          end
+        end
+      }
+    end
+    
+    # Populate the prejoined fact table.
+    def populate_prejoined_fact_table(options={})
+      fact_columns_string = columns.collect {|c|
+        "#{table_name}." + c.name unless excluded_foreign_key_names.include?(c.name)
+      }.compact.join(",\n")  
+      
+      prejoined_columns = []
+      
+      tables_and_joins = "#{table_name}"
+      
+      prejoined_fields.each_pair do |key, value|
+        dimension = dimension_class(key)
+        tables_and_joins += "\nJOIN #{dimension.table_name} as #{key}"
+        tables_and_joins += "\n  ON #{table_name}.#{dimension_relationships[key].primary_key_name} = "
+        tables_and_joins += "#{key}.#{dimension.primary_key}"
+        prejoined_columns << value.collect {|v| "#{key}." + v.to_s}
+      end
+
+      if connection.support_select_into_table?
+        drop_prejoin_fact_table
+        sql = <<-SQL
+          SELECT #{fact_columns_string}, 
+            #{prejoined_columns.join(",\n")}
+          INTO #{prejoined_table_name}
+          FROM #{tables_and_joins}
+        SQL
+      else
+        create_prejoined_fact_table(options)
+        sql = <<-SQL
+          INSERT INTO #{prejoined_table_name}
+          SELECT #{fact_columns_string}, 
+            #{prejoined_columns.join(",\n")}
+          FROM #{tables_and_joins}
+        SQL
+      end
+      connection.transaction { connection.execute(sql) }                
+    end
+  end
+end

data/lib/active_warehouse/report/abstract_report.rb

@@ -1,12 +1,25 @@
-module ActiveWarehouse
-  module Report
+module ActiveWarehouse #:nodoc:
+  module Report #:nodoc:
+    # Base module for reports.
     module AbstractReport
       
+      # Array of parameters which will be passed
       attr_accessor :pass_params
+      
+      # A Hash of level names mapped to a method that is used to filter the available
+      # column values
+      attr_accessor :column_filters
+      
+      # A Hash of level names mapped to a method that is used to filter the available
+      # row values
+      attr_accessor :row_filters
+      
+      # An optional conditions String
+      attr_accessor :conditions
 
       # Set the cube name
       def cube_name=(name)
-        self['cube_name'] = name
+        write_attribute(:cube_name, name)
         @cube = nil
       end
 
@@ -29,12 +42,19 @@ module ActiveWarehouse
         @column_dimension_class ||= ActiveWarehouse::Dimension.class_name(self.column_dimension_name).constantize
       end
 
+      # Get the column hierarchy. Uses the first hierarchy in the column dimension if not specified
       def column_hierarchy
-        self['column_hierarchy'] || column_dimension_class.hierarchies.first
+        ch = read_attribute(:column_hierarchy)
+        if ch.nil? || ch == 'NULL'
+          column_dimension_class.hierarchies.first
+        else
+          ch
+        end
       end
       
+      # Get the column prefix. Returns 'c' if not specified.
       def column_param_prefix
-        self['column_param_prefix'] || 'c'
+        read_attribute(:column_param_prefix) || 'c'
       end
 
       # Get the row dimension class
@@ -42,28 +62,34 @@ module ActiveWarehouse
         @row_dimension_class ||= ActiveWarehouse::Dimension.class_name(self.row_dimension_name).constantize
       end
       
+      # Get the row hierarchy. Uses the first hierarchy in the row dimension if not specified
       def row_hierarchy
-        self['row_hierarchy'] || row_dimension_class.hierarchies.first
+        read_attribute(:row_hierarchy) || row_dimension_class.hierarchies.first
       end
       
+      # Get the row parameter prefix. Returns 'r' if not specified.
       def row_param_prefix
-        self['row_param_prefix'] || 'r'
+        read_attribute(:row_param_prefix) || 'r'
       end
       
       # Get the list of displayed fact attributes. If this value is not specified then all aggregate and calculated
       # fields will be displayed
       def fact_attributes
-        return self['fact_attributes'] if self['fact_attributes']
+        return read_attribute(:fact_attributes) if read_attribute(:fact_attributes)
         fa = []
-        fact_class.aggregate_fields.each do |name|
-          fa << name
-        end
-        fact_class.calculated_fields.each do |name|
-          fa << name
-        end
+        fact_class.aggregate_fields.each { |field| fa << field }
+        fact_class.calculated_fields.each { |field| fa << field }
         fa
       end
       
+      def column_filters
+        @column_filters ||= {}
+      end
+      
+      def row_filters
+        @row_filters ||= {}
+      end
+      
       def pass_params
         @pass_params ||= []
       end