activewarehouse 0.1.0 → 0.2.0

data/lib/active_warehouse/dimension/bridge.rb

@@ -0,0 +1,15 @@
+module ActiveWarehouse #:nodoc
+  # Implements a bridge table.
+  class Bridge < ActiveRecord::Base
+    class << self
+      # Get the table name. By default the table name will be the name of the bridge in singular form.
+      #
+      # Example: DepartmentHierarchyBridge will have a table called department_hierarchy_bridge
+      def table_name
+        name = self.name.demodulize.underscore
+        set_table_name(name)
+        name
+      end
+    end
+  end
+end

data/lib/active_warehouse/dimension/dimension_view.rb

@@ -0,0 +1,11 @@
+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 < ActiveRecord::Base
+    class << self
+      
+    end
+  end
+end

data/lib/active_warehouse/dimension/hierarchical_dimension.rb

@@ -0,0 +1,60 @@
+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
+               name.gsub(/Dimension$/, '') + 'HierarchyBridge'
+             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.parent_id", 
+          :conditions => ['b.child_id = ? and b.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])
+      end
+    end
+    
+  end
+end

data/lib/active_warehouse/dimension/slowly_changing_dimension.rb

@@ -0,0 +1,137 @@
+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_on_or_after
+          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} = 1" } }, :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_on_or_after_scope(valid_on_or_after, &block)
+            with_scope({:find => {:conditions =>
+                  ["#{effective_date_attribute} <= ? and #{expiration_date_attribute} > ?",
+                  valid_on_or_after, valid_on_or_after]} }, :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?(:with_older)
+              find_every_with_older(options)
+            else
+              with_older_scope { find_every_with_older(options) }
+            end
+          end
+      end
+    end
+  end
+end

data/lib/active_warehouse/{model/fact.rb → fact.rb}

@@ -1,28 +1,56 @@
-module ActiveWarehouse
+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
-      attr_accessor :aggregate_fields, :aggregate_field_options, :calculated_fields, :calculated_field_options
+      # Array of aggregate field names
+      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
+      
+      # 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
       
       # Return a list of dimensions for this fact. 
       #
       # Example:
       #
       # sales_fact
-      #  time_id
+      #  date_id
       #  region_id
       #  sales_amount
       #  number_items_sold
       # 
-      # Calling SalesFact.dimensions would return the list: ['time','region']
+      # Calling SalesFact.dimensions would return the list: [:date, :region]
       def dimensions
-        dims = []
+        foreign_key_columns.collect { |c| c.name.gsub(/_id/, '').to_sym }
+      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|
-          if column.name =~ /(.*)_id/
-            dims << $1.to_sym
-          end
+          fk_columns << column if column.name =~ /(.*)_id/
         end
-        dims
+        fk_columns
       end
       
       # Get the time when the fact source file was last modified
@@ -49,6 +77,13 @@ module ActiveWarehouse
         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(dimension)
+        return dimension if dimension.is_a?(Class) and dimension.superclass == Fact
+        return class_for_name(dimension)
+      end
+      
       # Define an aggregate. Also aliased from aggregate()
       # * <tt>field</tt>: The field name
       # * <tt>options</tt>: A hash of options for the aggregate

data/lib/active_warehouse/migrations.rb

@@ -1,7 +1,6 @@
 module ActiveWarehouse #:nodoc:
-  # Responsible for migrating ActiveWarehouse
+  # Responsible for migrating ActiveWarehouse tables which are automatically created.
   class Migrator < ActiveRecord::Migrator
-    
     class << self
       def schema_info_table_name #:nodoc:
         ActiveRecord::Base.table_name_prefix + 'activewarehouse_schema_info' + ActiveRecord::Base.table_name_suffix

data/lib/active_warehouse/report.rb

@@ -0,0 +1,3 @@
+require 'active_warehouse/report/abstract_report'
+require 'active_warehouse/report/table_report'
+require 'active_warehouse/report/chart_report'

data/lib/active_warehouse/version.rb

@@ -1,7 +1,7 @@
-module ActiveWarehouse
+module ActiveWarehouse #:nodoc:
   module VERSION #:nodoc:
     MAJOR = 0
-    MINOR = 1
+    MINOR = 2
     TINY  = 0
 
     STRING = [MAJOR, MINOR, TINY].join('.')

data/lib/active_warehouse/view/report_helper.rb

@@ -138,6 +138,7 @@ module ReportHelper
     end
   end
   
+  # TODO: implement chart rendering
   def render_chart_report(report, html_options)
     "Not Yet Implemented"
   end
@@ -190,7 +191,7 @@ module ReportHelper
   # Example:
   #   sortable_column_header('SSN','ssn')
   #   sortable_column_header('Name','name',{:onclick => 'doSomething();'}, {:title => 'Some Title'})
-  def sortable_column_header(column_name, order_by, link_parameters={}, attributes={})
+  def sortable_column_header(column_name, order_by, link_parameters={}, attributes={}) # TODO get this thing back into the mix
     order = 'desc'
     if params[:order_by].to_s == order_by.to_s
   	  sorted = 'sorted'

data/tasks/active_warehouse_tasks.rake

@@ -1,4 +1,13 @@
 namespace :warehouse do 
+  desc "Drop and create the current database"
+  task :recreate => :environment do
+    abcs = ActiveRecord::Base.configurations
+    ActiveRecord::Base.establish_connection(abcs[RAILS_ENV])
+    puts "Recreating #{ActiveRecord::Base.connection.current_database}"
+    ActiveRecord::Base.connection.recreate_database(ActiveRecord::Base.connection.current_database)
+    ActiveRecord::Base.connection.reconnect!
+  end
+  
   desc "Build a 'standard' date dimension"
   task :build_date_dimension => :environment do
     abcs = ActiveRecord::Base.configurations
@@ -6,6 +15,8 @@ namespace :warehouse do
 
     start_date = (ENV['START_DATE'] ? Time.parse(ENV['START_DATE']) : Time.now.years_ago(5))
     end_date = (ENV['END_DATE'] ? Time.parse(ENV['END_DATE']) : Time.now )
+    
+    puts "Building date dimension"
 
     ddb = ActiveWarehouse::Builder::DateDimensionBuilder.new(start_date, end_date)
     ddb.build.each do |record|
@@ -17,6 +28,34 @@ namespace :warehouse do
     end
   end
   
+  desc "Build random data for all facts and dimensions in the models directory, excluding date"
+  task :build_random_data => :environment do
+    abcs = ActiveRecord::Base.configurations
+    ActiveRecord::Base.establish_connection(abcs[RAILS_ENV])
+    require 'pp'
+    
+    truncate = true if ENV['TRUNCATE']
+    name = ENV['NAME']
+    
+    if name
+      build_and_load(name, truncate)
+    else
+      models_dir = File.join(File.dirname(__FILE__), '../../../../app/models')
+      Dir.glob(File.join(models_dir, "**", "*.rb")).each do |f|
+        name = File.basename(f, '.rb')
+        next unless name =~ /_dimension$|_fact$/
+        next if name == 'date_dimension'
+        build_and_load(name)
+      end
+    end
+  end
+  
+  desc "Populate with test data"
+  task :populate => [:build_date_dimension, :build_random_data]
+  
+  desc "Recreate, migrate and populate"
+  task :setup => [:recreate, :migrate, 'db:migrate', :populate]
+  
   desc "Rebuild the warehouse" # TODO: consider moving this logic somewhere into a class and calling it from here
   task :rebuild => :environment do
     puts "Rebuilding data warehouse"
@@ -47,4 +86,19 @@ namespace :warehouse do
     migration_directory = File.join(File.dirname(__FILE__), '../db/migrations')
     ActiveWarehouse::Migrator.migrate(migration_directory, ENV["VERSION"] ? ENV["VERSION"].to_i : nil)
   end
+end
+
+def build_and_load(name, truncate=false)
+  builder = ActiveWarehouse::Builder::RandomDataBuilder.new
+  puts "Building #{name}"
+  clazz = name.classify.constantize
+  if truncate # TODO: Handle through adapter by adding a truncate method to the adapter
+    clazz.connection.execute("TRUNCATE #{clazz.table_name}")
+  end
+  options = {:fk_limit => {'date_id' => DateDimension.count}}
+  builder.build(name, options).each do |record|
+    clazz.create(record)
+  end
+rescue => e
+  puts "Unable to build #{name}: #{e}"
 end

metadata

@@ -1,10 +1,10 @@
 --- !ruby/object:Gem::Specification 
-rubygems_version: 0.9.0
+rubygems_version: 0.9.0.10
 specification_version: 1
 name: activewarehouse
 version: !ruby/object:Gem::Version 
-  version: 0.1.0
-date: 2006-12-19 00:00:00 -05:00
+  version: 0.2.0
+date: 2007-02-18 00:00:00 -05:00
 summary: Build data warehouses with Rails.
 require_paths: 
 - lib
@@ -29,18 +29,24 @@ post_install_message:
 authors: 
 - Anthony Eden
 files: 
+- init.rb
 - install.rb
 - README
 - TODO
 - Rakefile
 - db/migrations
 - db/migrations/001_create_table_reports.rb
-- doc/agg_queries.txt
-- doc/agg_queries_results.txt
-- doc/queries.txt
+- generators/bridge
 - generators/cube
 - generators/dimension
+- generators/dimension_view
 - generators/fact
+- generators/bridge/bridge_generator.rb
+- generators/bridge/templates
+- generators/bridge/USAGE
+- generators/bridge/templates/fixture.yml
+- generators/bridge/templates/migration.rb
+- generators/bridge/templates/model.rb
 - generators/cube/cube_generator.rb
 - generators/cube/templates
 - generators/cube/USAGE
@@ -53,6 +59,12 @@ files:
 - generators/dimension/templates/migration.rb
 - generators/dimension/templates/model.rb
 - generators/dimension/templates/unit_test.rb
+- generators/dimension_view/dimension_view_generator.rb
+- generators/dimension_view/templates
+- generators/dimension_view/USAGE
+- generators/dimension_view/templates/migration.rb
+- generators/dimension_view/templates/model.rb
+- generators/dimension_view/templates/unit_test.rb
 - generators/fact/fact_generator.rb
 - generators/fact/templates
 - generators/fact/USAGE
@@ -62,34 +74,35 @@ files:
 - generators/fact/templates/unit_test.rb
 - lib/active_warehouse
 - lib/active_warehouse.rb
+- lib/active_warehouse/aggregate.rb
 - lib/active_warehouse/builder
 - lib/active_warehouse/builder.rb
+- lib/active_warehouse/compat
 - lib/active_warehouse/core_ext
 - lib/active_warehouse/core_ext.rb
+- lib/active_warehouse/cube.rb
+- lib/active_warehouse/dimension
+- lib/active_warehouse/dimension.rb
+- lib/active_warehouse/fact.rb
 - lib/active_warehouse/migrations.rb
-- lib/active_warehouse/model
-- lib/active_warehouse/model.rb
+- lib/active_warehouse/report
+- lib/active_warehouse/report.rb
 - lib/active_warehouse/version.rb
 - lib/active_warehouse/view
 - lib/active_warehouse/view.rb
 - lib/active_warehouse/builder/date_dimension_builder.rb
 - lib/active_warehouse/builder/random_data_builder.rb
+- lib/active_warehouse/compat/compat.rb
 - lib/active_warehouse/core_ext/time
 - lib/active_warehouse/core_ext/time.rb
 - lib/active_warehouse/core_ext/time/calculations.rb
-- lib/active_warehouse/model/aggregate.rb
-- lib/active_warehouse/model/cube.rb
-- lib/active_warehouse/model/dimension
-- lib/active_warehouse/model/dimension.rb
-- lib/active_warehouse/model/fact.rb
-- lib/active_warehouse/model/report
-- lib/active_warehouse/model/report.rb
-- lib/active_warehouse/model/dimension/bridge.rb
-- lib/active_warehouse/model/dimension/dimension.rb
-- lib/active_warehouse/model/dimension/hierarchical_dimension.rb
-- lib/active_warehouse/model/report/abstract_report.rb
-- lib/active_warehouse/model/report/chart_report.rb
-- lib/active_warehouse/model/report/table_report.rb
+- lib/active_warehouse/dimension/bridge.rb
+- lib/active_warehouse/dimension/dimension_view.rb
+- lib/active_warehouse/dimension/hierarchical_dimension.rb
+- lib/active_warehouse/dimension/slowly_changing_dimension.rb
+- lib/active_warehouse/report/abstract_report.rb
+- lib/active_warehouse/report/chart_report.rb
+- lib/active_warehouse/report/table_report.rb
 - lib/active_warehouse/view/report_helper.rb
 - tasks/active_warehouse_tasks.rake
 test_files: []
@@ -142,3 +155,12 @@ dependencies:
       - !ruby/object:Gem::Version 
         version: 1.12.5.5618
     version: 
+- !ruby/object:Gem::Dependency 
+  name: rails_sql_views
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Version::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 0.1.0
+    version: