rubiks 0.0.6 → 0.1.0

data/CHANGELOG.md

@@ -1,26 +1,26 @@
-0.0.6
------
+## 0.1.0
+* Remove RLTK
+* Generate Mondrian 3 schema
+* Generate JSON schema
+* Include Mondrian
+
+## 0.0.6
 * [0.0.6 release](https://github.com/moneydesktop/rubiks/pull/3)
 * [Nodes deep_dup the input hash in .new_from_hash](https://github.com/moneydesktop/rubiks/commit/81b2d68eddf5551abd0f360aee4c91d237e10c3c)
 
-0.0.5
------
+## 0.0.5
 * [0.0.5 release](https://github.com/moneydesktop/rubiks/pull/2)
 
-0.0.4
------
+## 0.0.4
 * [Bump to v0.0.4](https://github.com/moneydesktop/rubiks/commit/38dfd1f82e947f39457670adfdc6ca67da2728c6)
 * [Add GemVersion badge to README](https://github.com/moneydesktop/rubiks/commit/2d92097c4ba73d92690fab78455fc7db6ed0b3d9)
 
-0.0.3
------
+## 0.0.3
 * [Bump to v0.0.3](https://github.com/moneydesktop/rubiks/commit/23ceb29936f663605527a12ca2d2a5c623abe99e)
 * Need to fill in other commits here
 
-0.0.2
------
+## 0.0.2
 * [Bump to v0.0.2](https://github.com/moneydesktop/rubiks/commit/14a55449be9552268c66cbf8b902af02cf7b73c6)
 
-0.0.1
------
+## 0.0.1
 * [Initial RubyGem project](https://github.com/moneydesktop/rubiks/commit/fa8be4badf70e86fda7e14bf23f9230a926893d2)

data/Gemfile

@@ -12,6 +12,8 @@ group :test do
   gem 'simplecov', :require => false
   gem 'rspec'
   gem 'rspec-pride'
+  gem 'equivalent-xml'
+  gem 'json_expressions'
 end
 
 group :development do

data/README.md

@@ -12,102 +12,120 @@
 [codeclimate]: https://codeclimate.com/github/moneydesktop/rubiks
 [coveralls]: https://coveralls.io/r/moneydesktop/rubiks
 
-A gem to allow defining an OLAP schema from a hash and generating an XML schema for Mondrian.
+[jruby]: http://jruby.org
+[wiki_cube]: http://en.wikipedia.org/wiki/OLAP_cube
+[wiki_olap]: http://en.wikipedia.org/wiki/Online_analytical_processing
+[wiki_mdx]: http://en.wikipedia.org/wiki/MultiDimensional_eXpressions
+[wiki_open_source]: http://en.wikipedia.org/wiki/Open-source_software
+[wiki_java]: http://en.wikipedia.org/wiki/Java_(programming_language)
+[wiki_data_warehouse]: http://en.wikipedia.org/wiki/Data_warehouse
+[wiki_star_schema]: http://en.wikipedia.org/wiki/Star_schema
+[wiki_dimensional_modeling]: http://en.wikipedia.org/wiki/Dimensional_modeling
+[postgresql]: http://www.postgresql.org
+[mondrian]: http://mondrian.pentaho.com
+[mondrian_schema]: http://mondrian.pentaho.com/documentation/schema.php
+[rails]: http://rubyonrails.org
 
-## Installation
+Rubiks is a [Online Analytical Processing](wiki_olap) ( **OLAP** ) library written in [JRuby](jruby).
+It runs on top of [Mondrian](mondrian) (an [Open-source](wiki_open_source) [OLAP](wiki_olap) server
+written in [Java](wiki_java)) and provides the ability to:
 
-Run `gem install rubiks` to install the gem on its own.
-
-Or you can add the following to your Gemfile and run the `bundle` command to install it.
+* define a [OLAP](wiki_olap) schema in Ruby
+* generate a [Mondrian XML schema](mondrian_schema) from this definition
+* execute [MultiDimensional eXpressions](wiki_mdx) ( **MDX** ) queries against the OLAP server
 
-    gem 'rubiks'
 
-## Examples
+### Assumptions
 
-This is an example taken from the [Mondrian documentation](http://mondrian.pentaho.com/documentation/schema.php#Cubes_and_dimensions) (then simplified a little and modified to use some Rails/Rubiks conventions)
+* You are using [JRuby](jruby)
+* You are using [PostgreSQL](postgresql)
+* You have designed and populated your [Data Warehouse](wiki_data_warehouse) (see [Dimensional Modeling](wiki_dimensional_modeling) and [Star Schema](wiki_star_schema))
+* You are using [Ruby on Rails](rails) database naming conventions
 
-After installing the gem, fire up an IRB session with `irb` or `bundle exec irb` if you are using Bundler, and follow this (or even paste it into your session):
 
-```ruby
-require 'rubiks/examples'
+### Installation
 
-md = Rubiks::Examples::MondrianDocs
+Run `gem install rubiks` to install the gem on its own.
 
-md.filename           # => "/path/to/rubiks/examples/mondrian_docs.yml"
+Or you can add the following to your Gemfile and run the `bundle` command to install it.
 
-puts md.file_contents # see the YAML section below
+    gem 'rubiks'
 
-puts md.to_xml        # see the XML section below
-```
 
-The [example YAML file](examples/mondrian_docs.yml) contents are:
-
-```yaml
-cubes:
-  - name: sales
-    dimensions:
-      - name: date
-        hierarchies:
-          - name: year_quarter_month
-            levels:
-              - name: year
-                column: the_year
-                data_type: numeric
-
-              - name: quarter
-                data_type: string
-
-              - name: month
-                column: month_of_year
-                data_type: Numeric
-
-    measures:
-      - name: unit_sales
-        aggregator: sum
-        format_string: '#,###'
-
-      - name: store_sales
-        aggregator: sum
-        format_string: '#,###'
-
-      - name: store_cost
-        aggregator: sum
-        format_string: '#,###'
-
-    calculated_members:
-      - name: profit
-        dimension: measures
-        formula: '[Measures].[Store Sales] / [Measures].[Store Cost]'
-        format_string: '$#,##0.00'
-```
+### Schema Example
 
-and the generated XML is:
+After installing the gem, fire up an IRB session with `irb` or `bundle exec irb` if you are using Bundler, and follow this (or even paste it into your session):
 
+```ruby
+require 'rubiks'
+
+schema = ::Rubiks::Schema.define :banking do
+  cube :transactions do
+    dimension :date, :type => 'TimeDimension' do
+      hierarchy :yqmwd, :caption => 'YQMWD' do
+        level :year,    :level_type => 'TimeYears', :type => :numeric, :contiguous => true
+        level :quarter, :level_type => 'TimeQuarters', :type => :numeric, :contiguous => true, :cardinality => :low
+        level :month,   :level_type => 'TimeMonths', :type => :numeric, :contiguous => true
+        level :week,    :level_type => 'TimeWeeks', :type => :numeric, :column => :week_of_month, :contiguous => true, :cardinality => :low
+        level :day,     :level_type => 'TimeDays', :type => :numeric, :contiguous => true
+      end
+    end
+
+    dimension :account do
+      hierarchy :account_type do
+        level :asset_liability, :cardinality => :low
+        level :account_type
+      end
+    end
+
+    measure :count, :column => :quantity
+    measure :amount, :aggregator => :sum, :format_string => '$#,###'
+  end
+end
+
+puts schema.to_xml
+```
+You should see this XML:
 
 ```xml
 <?xml version="1.0" encoding="UTF-8"?>
-<schema name="default">
-  <cube name="Sales">
-    <table name="view_sales"/>
-    <dimension name="Date" foreignKey="date_id">
-      <hierarchy name="Year Quarter Month" primaryKey="id" hasAll="true">
+<schema name="Banking">
+  <cube name="Transactions">
+    <table name="view_transactions"/>
+    <dimension name="Date" foreignKey="date_id" type="TimeDimension">
+      <hierarchy name="YQMWD" hasAll="true" primaryKey="id">
         <table name="view_dates"/>
-        <level name="Year" column="the_year" type="Numeric"/>
-        <level name="Quarter" column="quarter" type="String"/>
-        <level name="Month" column="month_of_year" type="Numeric"/>
+        <level name="Year" column="year" levelType="TimeYears" type="Numeric"/>
+        <level name="Quarter" column="quarter" levelType="TimeQuarters" type="Numeric"/>
+        <level name="Month" column="month" levelType="TimeMonths" type="Numeric"/>
+        <level name="Week" column="week_of_month" levelType="TimeWeeks" type="Numeric"/>
+        <level name="Day" column="day" levelType="TimeDays" type="Numeric"/>
+      </hierarchy>
+    </dimension>
+    <dimension name="Account" foreignKey="account_id">
+      <hierarchy name="Account Type" hasAll="true" primaryKey="id">
+        <table name="view_accounts"/>
+        <level name="Asset Liability" column="asset_liability"/>
+        <level name="Account Type" column="account_type"/>
       </hierarchy>
     </dimension>
-    <measure name="Unit Sales" aggregator="sum" formatString="#,###" column="unit_sales"/>
-    <measure name="Store Sales" aggregator="sum" formatString="#,###" column="store_sales"/>
-    <measure name="Store Cost" aggregator="sum" formatString="#,###" column="store_cost"/>
-    <calculatedMember name="Profit" dimension="Measures" formula="[Measures].[Store Sales] / [Measures].[Store Cost]">
-      <calculatedMemberProperty name="FORMAT_STRING" value="$#,##0.00"/>
-    </calculatedMember>
+    <measure name="Count" column="quantity" aggregator="count"/>
+    <measure name="Amount" column="amount" aggregator="sum" formatString="$#,###"/>
   </cube>
 </schema>
 ```
 
-## Contributing
+
+### Similar projects
+
+Check out these projects (which have been super helpful in working on Rubiks):
+
+* [Mondrian (git)](https://github.com/pentaho/mondrian) - source code for Mondrian on GitHub
+* [mondrian-olap](https://github.com/rsim/mondrian-olap) - a RubyGem wrapping Mondrian
+* [Saiku](http://analytical-labs.com) ([Saiku on GitHub](https://github.com/OSBI/saiku)) - a modular open-source analysis suite offering lightweight OLAP which remains easily embeddable, extendable and configurable.
+
+
+### Contributing
 
 1. Fork it
 2. Create your feature branch (`git checkout -b my-new-feature`)

data/lib/rubiks/calculated_measure.rb

@@ -0,0 +1,26 @@
+module ::Rubiks
+
+  class CalculatedMeasure < NamedObject
+    def formula(new_value=nil, options={})
+      @formula = new_value.to_s if new_value.present?
+      @formula ||= @options[:formula]
+    end
+
+    def format_string(new_value=nil, options={})
+      @format_string = new_value.to_s if new_value.present?
+      @format_string ||= @options[:format_string]
+    end
+
+    def to_xml(builder = nil)
+      builder = builder || new_builder
+
+      xml_attrs = default_xml_attributes
+      xml_attrs[:dimension] = 'Measures'
+      xml_attrs[:formula] = formula if formula.present?
+      xml_attrs[:formatString] = format_string if format_string.present?
+
+      builder.calculatedMember(xml_attrs)
+    end
+  end
+
+end

data/lib/rubiks/cube.rb

@@ -0,0 +1,80 @@
+module ::Rubiks
+
+  class Cube < NamedObject
+    def time_dimension(new_value=nil)
+      @time_dimension = new_value.to_s if new_value.present?
+      @time_dimension ||= @options[:time_dimension]
+    end
+
+    def person_dimension(new_value=nil)
+      @person_dimension = new_value.to_s if new_value.present?
+      @person_dimension ||= @options[:person_dimension]
+    end
+
+    def count_measure(new_value=nil)
+      @count_measure = new_value.to_s if new_value.present?
+      @count_measure ||= @options[:count_measure]
+    end
+
+    def person_count_measure(new_value=nil)
+      @person_count_measure = new_value.to_s if new_value.present?
+      @person_count_measure ||= @options[:person_count_measure]
+    end
+
+    def dimensions
+      @dimensions ||= []
+    end
+
+    def dimension(dimension_name, options={}, &block)
+      dimensions.push ::Rubiks::Dimension.find_or_create(dimension_name, options, &block)
+    end
+
+    def measures
+      @measures ||= []
+    end
+
+    def measure(measure_name, options={}, &block)
+      measures.push ::Rubiks::Measure.find_or_create(measure_name, options, &block)
+    end
+
+    def calculated_measures
+      @calculated_measures ||= []
+    end
+
+    def calculated_measure(calculated_measure_name, options={}, &block)
+      calculated_measures.push ::Rubiks::CalculatedMeasure.find_or_create(calculated_measure_name, options, &block)
+    end
+
+    def json_hash
+      hash = default_json_attributes.merge(
+        :time_dimension => time_dimension.to_s,
+        :person_dimension => person_dimension.to_s,
+        :count_measure => count_measure.to_s,
+        :person_count_measure => person_count_measure.to_s,
+        :dimensions => dimensions.map{ |dim| dim.json_hash },
+        :measures => json_measures
+      )
+      hash.delete_if { |key,value| value.nil? || value.blank? }
+      hash.stringify_keys!
+    end
+
+    def to_xml(builder = nil)
+      builder = builder || new_builder
+
+      builder.cube(default_xml_attributes) do
+        builder.table(:name => table)
+        dimensions.each{ |dimension| dimension.to_xml(builder) }
+        measures.each{ |measure| measure.to_xml(builder) }
+        calculated_measures.each{ |measure| measure.to_xml(builder) }
+      end
+    end
+
+    def json_measures
+      json_measures = []
+      json_measures.push(*measures.map{ |m| m.json_hash })
+      json_measures.push(*calculated_measures.map{ |cm| cm.json_hash })
+      json_measures
+    end
+  end
+
+end

data/lib/rubiks/dimension.rb

@@ -0,0 +1,48 @@
+module ::Rubiks
+
+  class Dimension < NamedObject
+    def degenerate(new_value=nil)
+      @degenerate = new_value.to_s if new_value.present?
+      @degenerate ||= @options[:degenerate]
+    end
+
+    def type(new_value=nil)
+      @type = new_value.to_s if new_value.present?
+      @type ||= @options[:type]
+    end
+
+    def hierarchies
+      @hierarchies ||= []
+    end
+
+    def hierarchy(hierarchy_name, options={}, &block)
+      options.merge!(:table => degenerate ? 'degenerate' : self.table)
+      hierarchies.push ::Rubiks::Hierarchy.find_or_create(hierarchy_name, options, &block)
+    end
+
+    def json_hash
+      hash = default_json_attributes.merge(
+        :hierarchies => hierarchies.map{ |hier| hier.json_hash }
+      )
+      hash[:type] = type.to_s if type.present?
+      hash.delete_if { |key,value| value.nil? }
+      hash.stringify_keys!
+    end
+
+    def to_xml(builder = nil)
+      builder = builder || new_builder
+
+      xml_attrs = default_xml_attributes
+      if self.degenerate
+        xml_attrs.delete(:table)
+      else
+        xml_attrs[:foreignKey] = "#{name}_id"
+      end
+      xml_attrs[:type] = type if type.present?
+      builder.dimension(xml_attrs) do
+        hierarchies.each{ |hierarchy| hierarchy.to_xml(builder) }
+      end
+    end
+  end
+
+end

data/lib/rubiks/hierarchy.rb

@@ -0,0 +1,46 @@
+module ::Rubiks
+
+  class Hierarchy < ::Rubiks::NamedObject
+    def levels
+      @levels ||= []
+    end
+
+    def level(level_name, options={}, &block)
+      levels.push ::Rubiks::Level.find_or_create(level_name, options, &block)
+    end
+
+    def all_member_name(new_value=nil)
+      @all_member_name = new_value.to_s if new_value.present?
+      @all_member_name ||= true
+    end
+
+    def has_all(new_value=nil)
+      @has_all = new_value.to_s if new_value.present?
+      @has_all ||= true
+    end
+
+    def json_hash
+      hash = default_json_attributes.merge(
+        :levels => levels.map{ |lvl| lvl.json_hash }
+      )
+      hash.delete_if { |key,value| value.nil? }
+      hash.stringify_keys!
+    end
+
+    def to_xml(builder = nil)
+      builder = builder || new_builder
+
+      xml_attrs = default_xml_attributes.merge(:hasAll => has_all.to_s)
+      xml_attrs[:primaryKey] = 'id' unless degenerate?
+      builder.hierarchy(xml_attrs) do
+        builder.table(:name => table) unless degenerate?
+        levels.each{ |level| level.to_xml(builder) }
+      end
+    end
+
+    def degenerate?
+      table == 'degenerate'
+    end
+  end
+
+end

data/lib/rubiks/level.rb

@@ -0,0 +1,57 @@
+module ::Rubiks
+
+  class Level < ::Rubiks::NamedObject
+    def cardinality(new_value=nil)
+      @cardinality = new_value.to_s if new_value.present?
+      @cardinality ||= @options[:cardinality]
+    end
+
+    def contiguous(new_value=nil)
+      @contiguous = new_value.to_s if new_value.present?
+      @contiguous ||= @options.key?(:contiguous) ? @options[:contiguous].to_s : nil
+    end
+
+    def column(new_value=nil)
+      @column = new_value.to_s if new_value.present?
+      @column ||= @options[:column] || name
+    end
+
+    def name_column(new_value=nil)
+      @name_column = new_value.to_s if new_value.present?
+      @name_column ||= @options[:name_column]
+    end
+
+    def ordinal_column(new_value=nil)
+      @ordinal_column = new_value.to_s if new_value.present?
+      @ordinal_column ||= @options[:ordinal_column]
+    end
+
+    def level_type(new_value=nil)
+      @level_type = new_value.to_s if new_value.present?
+      @level_type ||= @options[:level_type]
+    end
+
+    def type(new_value=nil)
+      @type = new_value if new_value.present?
+      @type ||= @options[:type]
+    end
+
+    def json_hash
+      hash = default_json_attributes
+      hash[:cardinality] = cardinality.to_s if cardinality.present?
+      hash[:visible] = visible if visible.present? && visible == 'false'
+      hash[:contiguous] = contiguous if contiguous.present? && contiguous == 'true'
+      hash.stringify_keys!
+    end
+
+    def to_xml(builder = nil)
+      builder = builder || new_builder
+
+      xml_attrs = default_xml_attributes.merge(:column => column)
+      xml_attrs[:levelType] = level_type if level_type.present?
+      xml_attrs[:type] = type.to_s.capitalize if type.present?
+      builder.level(xml_attrs)
+    end
+  end
+
+end

data/lib/rubiks/measure.rb

@@ -0,0 +1,28 @@
+module ::Rubiks
+
+  class Measure < ::Rubiks::NamedObject
+    def column(new_name=nil, options={})
+      @column = new_name.to_s if new_name.present?
+      @column ||= @options[:column] || name
+    end
+
+    def aggregator(new_name=nil, options={})
+      @aggregator = new_name.to_s if new_name.present?
+      @aggregator ||= @options[:aggregator] || 'count'
+    end
+
+    def format_string(new_value=nil, options={})
+      @format_string = new_value.to_s if new_value.present?
+      @format_string ||= @options[:format_string]
+    end
+
+    def to_xml(builder = nil)
+      builder = builder || new_builder
+
+      xml_attrs = {:name => caption, :column => column, :aggregator => aggregator}
+      xml_attrs[:formatString] = format_string if format_string.present?
+      builder.measure(xml_attrs)
+    end
+  end
+
+end