olap-xmla 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 0b8dba43fb5369997ffdd603813f84560764468c
-  data.tar.gz: a05013ba124097d44460b0975e374dc371efa17e
+  metadata.gz: 353d1787b60fcbfdb612748987277c3d3b4046ea
+  data.tar.gz: b7e723cf2067e094e4ba74e51267b3b3c2cd2048
 SHA512:
-  metadata.gz: d8cb6e2cf34c2c8723b7f12f53540e3932513577273b638dfdcf64b751544602efbedd0e0f77d161782d79fa2fe65fc82091d38554558ae23cd017d5632b6d16
-  data.tar.gz: b85dd1a91398b39191068c9356b146dfd5bf2078e97750d4226a8cb2f958f9ce3cbf419f12056fc4882e26dc7f036c7c0ef28b368a764e88126c8d565b0e3f05
+  metadata.gz: 9558ccbf3c6d913a7074ea34b6bb722bc5b75983e0dff1890ce98bbd45f2f1d000ada9ce790493988d8da66993439ff8dedd8062425d07f1e295954e0312a896
+  data.tar.gz: ddafa507a59edd7a7cab7035c5389672d9b156594b0550726b5ef36894710500407eb93757b536d42590a128ede68a018668a4383ac605263af5f36bb6988c5d

data/.gitignore

@@ -6,6 +6,7 @@
 /doc/
 /pkg/
 /spec/reports/
+/spec/.config.yaml
 /tmp/
 *.bundle
 *.so

data/Gemfile

@@ -2,3 +2,4 @@ source 'https://rubygems.org'
 
 # Specify your gem's dependencies in olap-xmla.gemspec
 gemspec
+

data/README.md

@@ -1,6 +1,8 @@
 # Olap::Xmla
 
-TODO: Write a gem description
+The gem connects to OLAP database using XMLA interface and executes MDX queries.
+
+Can be used in Ruby or Rails applications to display and analyse data from OLAP databases.
 
 ## Installation
 
@@ -20,7 +22,82 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+Using the gem is very simple, only basic knowledge on OLAP is required.
+
+### Connecting to server
+
+To use the gem, you need to know the connection requisites to connect to XMLA server:
+
+1. Server URL ( typically, http: or https: URL )
+2. Datasource and catalog names. You can check them in your XMLA server configuration
+
+Connecting to the server and executing MDX are straightforward:
+
+```ruby
+require 'olap/xmla'
+
+client = Olap::Xmla.client({
+            server: 'http://your-olap-server',
+            datasource: 'your-datasource',
+            catalog: 'your-catalog'})
+response = client.request 'your-mdx-here'
+```
+
+### Configuration in Rails
+
+If you are using this gem in Rails application, which uses just single OLAP data source,
+you can simplify the code by pre-configuring the XMLA connection.
+
+Create a file olap.rb in config/initializers directory with the following content:
+
+```ruby
+Olap::Xmla.default_options= { server: 'http://your-olap-server',
+                                datasource: 'your-datasource',
+                                catalog: 'your-catalog'}
+```
+
+Then in Rails application code you can simply do:
+
+```ruby
+response = Olap::Xmla.client.request 'your-mdx-here'
+```
+
+### Querying MDX
+
+The gem does not parse MDX, just passes it to XMLA server.
+
+However, it can do substituting parameters in the query:
+
+```ruby
+MDX_QUERY = 'SET [~ROWS_Date] AS {[DateTime].[Date].[Date].[%DATE%]}'
+
+Olap::Xmla.client.request MDX_QUERY, {'%DATE%' => '20150530'}
+```
+
+This allows to store MDX queries in constants, while execute them with dynamic parameters.
+Note, that you should never use these parameters directly from Rails request, as
+this may create security breach!
+
+### Using response on Query
+
+
+You may use the response to render the results to user, or post-process it to analyse the data
+The following methods can be used to request the meta-data and data from the response:
+
+```ruby
+response = client.request(mdx)
+
+
+# Meta - data of the response
+response.measures  #  array of the columns definitions ( :name / :caption )
+response.dimensions # array of the rows definitions ( :name )
+
+# Response data
+response.rows # rows of the response
+response.to_hash # response as a hash
+response.column_values(column_num) # just one column of the response
+
+```
 
 ## Contributing
 

data/lib/olap/xmla.rb

@@ -1,10 +1,50 @@
 require "olap/xmla/version"
+require "olap/xmla/client"
 
 module Olap
+
+  #
+  # Connects to XMLA[https://en.wikipedia.org/wiki/XML_for_Analysis] server and executes MDX[https://en.wikipedia.org/wiki/MultiDimensional_eXpressions] queries
+  #
   module Xmla
 
-    def self.client server, data_source, catalog, options = {}
-      Olap::Xmla::Client.new server, data_source, catalog, options
+    @@connect_options = {}
+
+    # Configure the default options to connect to XMLA server
+    # Can be optionally used to setup connection options in one place in application,
+    #
+    # Example:
+    #   >> Olap::Xmla.default_options = {server: 'http://your-olap-server', datasource: 'your-datasource', catalog: 'your-catalog'}
+    #   >> Olap::Xmla.client.request mdx
+    #   => #<Olap::Xmla::Response:0x000001035b9510 @response={ ...
+    #
+    # Look client connect_options for the list of options to be specified
+    #
+    def self.default_options= options
+      @@connect_options = options
+    end
+
+    # Create a client, which can be used then to execute MDX queries
+    #
+    # Example:
+    #   >> client = Olap::Xmla.client(server: 'http://your-olap-server', datasource: 'your-datasource', catalog: 'your-catalog')
+    #   >> response = client.request mdx
+    #   => #<Olap::Xmla::Response:0x000001035b9510 @response={ ...
+    #
+    # ==== connect_options
+    #
+    #  * +:server+ - URL to connect to XMLA server (required)
+    #  * +:datasource+ - the name of datasource (required)
+    #  * +:catalog+ - the name of catalog (required)
+    #  * +:open_timeout+ - open timeout to connect to XMLA server, optional, default is 60 sec
+    #  * +:read_timeout+ - open timeout to read data from XMLA server, optional, default is 300 sec
+    #
+    #
+    def self.client connect_options = {}
+      options = @@connect_options.merge connect_options
+      raise "Connect options must define :server, :datasource and :catalog options" unless
+          options[:server] && options[:datasource] && options[:catalog]
+      Olap::Xmla::Client.new options[:server], options[:datasource], options[:catalog], options
     end
 
   end

data/lib/olap/xmla/client.rb

@@ -0,0 +1,74 @@
+require 'savon'
+require 'olap/xmla/response'
+
+class Olap::Xmla::Client
+
+  attr_reader :data_source, :catalog, :client
+
+  def initialize server, data_source, catalog, options
+
+    @catalog = catalog
+    @data_source = data_source
+    @client = Savon.client do
+      endpoint server
+      namespace "urn:schemas-microsoft-com:xml-analysis"
+      open_timeout (options[:open_timeout] || 60)
+      read_timeout (options[:read_timeout] || 300)
+    end
+  end
+
+  # Executes multiple MDX queries as a batch
+  #
+  # Arguments:
+  #  * +mdx_requests+ - Collection of MDX requests
+  #  * +parameters+ - Map of parameters to substitute in MDX request, optional
+  #
+  def batch mdx_requests, parameters = {}
+    mdx_requests.collect{|mdx|
+      request mdx, parameters
+    }
+  end
+
+  # Execute MDX queries, substituting parameters in the query
+  #
+  # Arguments:
+  #  * +mdx_request+ - MDX request as a string, required
+  #  * +parameters+ - Map of parameters to substitute in MDX request, optional
+  #
+  # Example:
+  #
+  #  client.request 'SET [~ROWS_Date] AS {[DateTime].[Date].[Date].[%DATE%]}', {'%DATE%' => '20150530'}
+  #    will execute actual MDX: SET [~ROWS_Date] AS {[DateTime].[Date].[Date].[20150530]}
+  #
+  #
+  def request mdx_request, parameters = {}
+
+    mdx = mdx_request.clone
+
+    parameters.each{|k,v|
+      mdx.gsub!(k,v)
+    }
+
+    ops = client.operation('Execute')
+    p = { 'wsdl:PropertyList' => {'wsdl:DataSourceInfo' => data_source,
+                                 'wsdl:Catalog' => catalog,
+                                 'wsdl:Format' => 'Multidimensional',
+                                 'wsdl:AxisFormat'=> 'TupleFormat'} }
+
+
+    r = ops.call(  message: {'wsdl:Command' =>  { 'wsdl:Statement' => mdx}, 'wsdl:Properties' => p })
+
+    unless r.success?
+      raise "Error executing #{mdx} in #{catalog} #{data_source}: #{r.http_error} #{r.soap_fault}"
+    end
+
+    Olap::Xmla::Response.new r.body[:execute_response][:return][:root]
+
+  end
+
+
+
+end
+
+
+

data/lib/olap/xmla/response.rb

@@ -0,0 +1,154 @@
+class Olap::Xmla::Response
+
+  attr_reader :response
+
+  def initialize response
+    @response = response
+  end
+
+  # Returns true if the response has any data
+  def has_data?
+    not response[:cell_data][:cell].empty?
+  end
+
+  # Collection of measures in response
+  #
+  # *  +:name+  the name of measure
+  # *  +:caption+ display name of measure
+  #
+  def measures
+    response[:axes][:axis][0][:tuples][:tuple].collect{|m|
+      {
+          name: m[:member][:u_name],
+          caption: m[:member][:caption]
+      }
+    }
+  end
+
+  # Collection of dimensions in response
+  #
+  # *  +:name+  the name of dimension
+  #
+  def dimensions
+    response[:olap_info][:axes_info][:axis_info][1][:hierarchy_info].collect{|m|
+      {
+          name: m[:@name]
+      }
+    }
+  end
+
+
+  # Collection of result rows
+  # * rownum  number of row ( 1... N)
+  # * labels - array of tuples per the row
+  #      value - the value of tuple
+  #      name - the name of tuple
+  # *  values - the values array
+  #      measure - metric name
+  #      value - metric value
+  #      fmt_value - formatted metric value
+  #      colnum - column number ( 1..N)
+  def rows
+
+    return [] unless response[:cell_data]
+
+    measures = [response[:axes][:axis][0][:tuples][:tuple]].flatten
+    cells = [response[:cell_data][:cell]].flatten
+
+    cell_ordinal = 0
+    cell_index = 0
+    rownum = 0
+
+    [response[:axes][:axis][1][:tuples][:tuple]].flatten.collect{ |tuple|
+      rownum += 1
+      colnum = 0
+      tuple_member = [tuple[:member]].flatten
+      {  rownum: rownum,
+         labels: tuple_member.collect{|member|
+           value = member[:caption]
+           value = nil if value=='#null'
+           {value: value, name: member[:@hierarchy]}
+         },
+         values: measures.collect{|m|
+
+           colnum += 1
+
+           if (cell=cells[cell_index]) && cell[:@cell_ordinal].to_i==cell_ordinal
+             cell_index += 1
+             cell_ordinal += 1
+             { colnum: colnum, measure: m[:member][:u_name], value: cell[:value], fmt_value: cell[:fmt_value]}
+           else
+             cell_ordinal += 1
+             { colnum: colnum, measure: m[:member][:u_name], value: nil, fmt_value: nil}
+           end
+
+         }
+
+      }
+    }
+
+  end
+
+  # query a colum of the result
+  #
+  # Example:
+  #
+  # >> response.column_values 1
+  #  => [30.0, 1025.0, 884.0, 543.0,...
+  #
+  def column_values column_num
+
+    rows.collect{|row|
+      row[:values].detect{|value|
+        value[:colnum]==column_num
+      }[:value].to_f
+    }
+
+  end
+
+  # Aggregate result by one of the columns
+  def column_values_aggregate dimension_aggr_index = 0
+
+    result = []
+    index = {}
+
+    rows.each{|row|
+      label = row[:labels][dimension_aggr_index]
+
+      if i = index[label]
+        for j in 0..result[i][:values].count-1
+          result[i][:values][j] += row[:values][j][:value].to_f
+        end
+      else
+        index[label] = result.count
+        result << {
+            rownum: result.count + 1,
+            label: label,
+            values: row[:values].collect{|v| v[:value].to_f }
+        }
+      end
+    }
+
+    result
+  end
+
+  # Convert the response to hash
+  # keys of hash are values of tuples
+  # values of hash are values of metrics
+  #
+  # Example:
+  #
+  #  response.to_hash
+  #  => {["2014", "05/11/2014"]=>[30.0, 27.0, 0.0], ["2014", "06/11/2014"]=>[1025.0, 688.0, 73.0]
+  #
+  def to_hash
+    Hash[rows.collect{|row|
+           [
+               row[:labels].collect{|l| l[:value].nil? ? nil : l[:value] },
+               row[:values].collect{|l| (l.nil? || l[:value].nil?) ? 0.0 : l[:value].to_f },
+           ]
+
+         }]
+  end
+
+end

data/lib/olap/xmla/version.rb

@@ -1,5 +1,5 @@
 module Olap
   module Xmla
-    VERSION = "0.0.1"
+    VERSION = "0.0.2"
   end
 end

data/olap-xmla.gemspec

@@ -10,7 +10,7 @@ Gem::Specification.new do |spec|
   spec.email         = ["aleksey@wondersoft.ru"]
   spec.summary       = %q{Pure Ruby gem to make MDX queries on OLAP databases using XMLA connection}
   spec.description   = %q{Can be used with any XMLA-compliant server, like Olaper or Mondrian.}
-  spec.homepage      = ""
+  spec.homepage      = "https://github.com/Wondersoft/olap-xmla"
   spec.license       = "MIT"
 
   spec.files         = `git ls-files -z`.split("\x0")
@@ -20,4 +20,7 @@ Gem::Specification.new do |spec|
 
   spec.add_development_dependency "bundler", "~> 1.7"
   spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec", '~> 0'
+  spec.add_runtime_dependency 'savon', '~> 2.8'
+  spec.add_runtime_dependency 'rubyntlm', '~> 0.3.2'
 end

data/spec/gem_spec.rb

@@ -0,0 +1,72 @@
+require 'spec_helper'
+
+
+connection_config = YAML.load File.read 'spec/.config.yaml'
+
+describe 'Test MDX queries' do
+
+  it 'should request mdx' do
+
+    client = Olap::Xmla.client connection_config
+
+    mdx= "WITH SET [~ROWS_YearByDay] AS " +
+          "{[DateTime].[YearByDay].[Year].Members} " +
+        "SET [~ROWS_Date] AS " +
+        "    {[DateTime].[Date].[Date].Members} " +
+        "SELECT " +
+        "NON EMPTY {[Measures].[Slots], [Measures].[Clicks], [Measures].[Conversions]} ON COLUMNS, " +
+        "NON EMPTY NonEmptyCrossJoin([~ROWS_YearByDay], [~ROWS_Date]) ON ROWS " +
+        "FROM [Ad Serving]"
+
+    response = client.request mdx
+
+    expect(response.has_data?).to be true
+
+    expect(response.measures.count).to eq 3
+    expect(response.measures[0][:name]).to eq '[Measures].[Slots]'
+    expect(response.measures[1][:name]).to eq '[Measures].[Clicks]'
+
+    expect(response.dimensions.count).to eq 2
+
+    expect(response.dimensions[0][:name]).to eq 'YearByDay'
+    expect(response.dimensions[1][:name]).to eq 'Date'
+
+    expect(response.rows.count).to be > 100
+
+    expect(response.rows[0][:rownum]).to eq 1
+
+    expect(response.rows[0][:labels].size).to eq 2
+    expect(response.rows[0][:labels][0][:name]).to eq 'YearByDay'
+    expect(response.rows[0][:labels][1][:name]).to eq 'Date'
+
+    expect(response.rows[0][:values].size).to eq 3
+
+    expect(response.rows[0][:values][0][:colnum]).to eq 1
+    expect(response.rows[0][:values][0][:measure]).to eq '[Measures].[Slots]'
+    expect(response.rows[0][:values][0][:value]).to_not be_nil
+
+  end
+
+  it 'should use default connect' do
+
+    Olap::Xmla.default_options = connection_config
+
+    client = Olap::Xmla.client
+
+    mdx= "WITH SET [~ROWS_YearByDay] AS " +
+        "{[DateTime].[YearByDay].[Year].Members} " +
+        "SET [~ROWS_Date] AS " +
+        "    {[DateTime].[Date].[Date].Members} " +
+        "SELECT " +
+        "NON EMPTY {[Measures].[Slots], [Measures].[Clicks], [Measures].[Conversions]} ON COLUMNS, " +
+        "NON EMPTY NonEmptyCrossJoin([~ROWS_YearByDay], [~ROWS_Date]) ON ROWS " +
+        "FROM [Ad Serving]"
+
+    response = client.request mdx
+
+    expect(response.has_data?).to be true
+
+  end
+
+
+end

data/spec/spec_helper.rb

@@ -0,0 +1,11 @@
+require 'bundler/setup'
+require 'rspec'
+require 'yaml'
+
+Bundler.setup
+
+require 'olap/xmla'
+
+
+RSpec.configure do |config|
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: olap-xmla
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - studnev
@@ -38,6 +38,48 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: savon
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.8'
+- !ruby/object:Gem::Dependency
+  name: rubyntlm
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.3.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.3.2
 description: Can be used with any XMLA-compliant server, like Olaper or Mondrian.
 email:
 - aleksey@wondersoft.ru
@@ -51,9 +93,13 @@ files:
 - README.md
 - Rakefile
 - lib/olap/xmla.rb
+- lib/olap/xmla/client.rb
+- lib/olap/xmla/response.rb
 - lib/olap/xmla/version.rb
 - olap-xmla.gemspec
-homepage: ''
+- spec/gem_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/Wondersoft/olap-xmla
 licenses:
 - MIT
 metadata: {}
@@ -77,4 +123,6 @@ rubygems_version: 2.2.2
 signing_key: 
 specification_version: 4
 summary: Pure Ruby gem to make MDX queries on OLAP databases using XMLA connection
-test_files: []
+test_files:
+- spec/gem_spec.rb
+- spec/spec_helper.rb