martyr 0.1.74.pre

data/lib/martyr/runtime/data_set/coordinates.rb

@@ -0,0 +1,108 @@
+module Martyr
+  module Runtime
+    class Coordinates
+      include ActiveModel::Model
+      include Martyr::Translations
+
+      # @attribute coordinates_hash [Hash] with keys of the form:
+      #     'dimension_name.level_name'
+      #     'cube_name.metric_name'
+      #   and values representing the slice
+
+      attr_reader :grain_hash, :memory_slice_hash
+
+      # @param grain_hash [Hash] of the structure level_id => value. For query levels, value is the primary key.
+      #   Note that it does not include metrics, and other background restrictions on the slice
+      # @param memory_slice_hash [Hash]
+      def initialize(grain_hash, memory_slice_hash)
+        @grain_hash = grain_hash
+        @memory_slice_hash = memory_slice_hash
+      end
+
+      # @return [Hash] of coordinates that can get the same element when sent to a QueryContextBuilder#slice
+      def to_hash
+        memory_slice_hash.merge(grain_coordinates)
+      end
+
+      # @return [Array<String>]
+      def grain_level_ids
+        grain_hash.keys
+      end
+
+      # @return [Hash] of the grain in a format that is understood by QueryContextBuilder#slice
+      def grain_coordinates
+        grain_hash.inject({}) { |h, (level_id, level_value)| h[level_id] = {with: level_value}; h }
+      end
+
+      def dup
+        super.dup_internals
+      end
+
+      def reset(*args)
+        dup.reset!(*args)
+      end
+
+      def set(*args)
+        dup.set!(*args)
+      end
+
+      def locate(*args)
+        dup.locate!(*args)
+      end
+
+      def locate!(slice_hash={}, reset: [])
+        reset.each { |reset_on| reset!(reset_on) }
+        set!(slice_hash)
+        self
+      end
+
+      # @param reset_on [String, Array<String>]
+      #   The caller must guarantee that only levels and dimensions are sent to #reset!.
+      #   Since this object is not hierarchy-aware, the caller must send all levels below the level asked to be reset.
+      #
+      #   There are two acceptable formats:
+      #   'dimension_name.level_name' - to remove a particular level
+      #   'dimension_name.*' - to remove a dimension with all its levels
+      #
+      def reset!(reset_on)
+        if second_element_from_id(reset_on) == '*'
+          reset_dimension first_element_from_id(reset_on)
+        else
+          grain_hash.except!(reset_on)
+        end
+        self
+      end
+
+      # @param slice_hash [Hash] of one of the formats:
+      #   'dimension_name.level_name' => {with: 'value'}
+      #   'dimension_name.level_name' => {'with' => 'value'}
+      #
+      #   The caller must guarantee that only levels and dimensions are sent.
+      #
+      def set!(slice_hash)
+        slice_hash.group_by { |k, _| first_element_from_id(k) }.each do |dimension_name, slice_hashes_arr|
+          reset_dimension dimension_name
+          slice_hashes_arr.each do |slice_on, slice_definition|
+            raise Query::Error.new('incorrect usage of locate') unless slice_definition.stringify_keys.keys == ['with']
+            grain_hash.merge! slice_on => slice_definition.stringify_keys['with']
+          end
+        end
+        self
+      end
+
+      protected
+
+      def dup_internals
+        @grain_hash = @grain_hash.dup
+        self
+      end
+
+      private
+
+      def reset_dimension(dimension_name)
+        grain_hash.reject! { |k, _| first_element_from_id(k) == dimension_name }
+      end
+
+    end
+  end
+end

data/lib/martyr/runtime/data_set/element.rb

@@ -0,0 +1,66 @@
+module Martyr
+  module Runtime
+    class Element < HashWithIndifferentAccess
+      include Martyr::Translations
+      include Martyr::Runtime::ElementCommon
+
+      # @attribute element_locator [ElementLocator] this is added to an element in the process of building it
+      # @attribute helper_module [Module] this is kept for reference, although the element object should already extend it
+      attr_accessor :element_locator, :helper_module
+
+      attr_reader :facts
+      delegate :empty?, to: :facts
+      delegate :cube_name, to: :element_locator
+      delegate :grain_level_ids, :grain_hash, to: :@coordinates
+
+      # @param coordinates [Coordinates]
+      # @param values_hash [Hash] of the structure level_id => value. Unlike `coordinates.grain_hash`, for query levels the
+      #   value is the string value, not the primary key.
+      # @param facts [Array<Fact>]
+      def initialize(coordinates, values_hash, facts)
+        @coordinates = coordinates
+        @facts = facts
+        merge! values_hash
+      end
+
+      # @param key [String] either metric id or level id
+      def fetch(key)
+        value = super(key)
+        value.is_a?(FutureMetric) ? value.value : value
+      end
+      alias_method :[], :fetch
+
+      def coordinates
+        @coordinates.to_hash
+      end
+
+      def coordinates_object
+        @coordinates
+      end
+
+      def locate(*args)
+        element_locator.locate(grain_hash, *args)
+      end
+
+      # Loads all future values
+      def load
+        keys.each{|key| fetch(key)}
+        self
+      end
+
+      def key_for(level_id)
+        raise Query::Error.new("Error: `#{level_id}` must be included in the element grain") unless coordinates.keys.include?(level_id)
+        facts.first.fact_key_for(level_id)
+      end
+
+      def record_for(level_id)
+        raise Query::Error.new("Error: `#{level_id}` must be included in the element grain") unless coordinates.keys.include?(level_id)
+        facts.first.record_for(level_id)
+      end
+
+      def has_metric_id?(metric_id)
+        metric_ids.include? MetricIdStandardizer.new(cube_name).standardize(metric_id)
+      end
+    end
+  end
+end

data/lib/martyr/runtime/data_set/element_common.rb

@@ -0,0 +1,51 @@
+module Martyr
+  module Runtime
+
+    # Requirements:
+    #   The object must have the #store method
+
+    module ElementCommon
+      extend ActiveSupport::Concern
+
+      included do
+        attr_reader :metrics_hash
+      end
+
+      # Grain and coordinates are different.
+      # Coordinates can include "background" multi-value slices such as: 'media.types' => ['a', 'b', 'c']
+      # Grain always have one value for each level
+      # Coordinates always include the grain.
+
+      def grain_has_level_id?(level_id)
+        grain_level_ids.include?(level_id)
+      end
+
+      def coordinates_have_level_id?(level_id)
+        coordinates.keys.include?(level_id)
+      end
+      alias_method :has_level_id?, :coordinates_have_level_id?
+
+      def metrics
+        metrics_hash.values
+      end
+
+      def metric_ids
+        metrics_hash.keys
+      end
+
+      # @param metrics [Array<BaseMetric>]
+      # @return [self]
+      def rollup(*metrics)
+        @metrics_hash ||= {}
+        metrics.each do |metric|
+          next if @metrics_hash[metric.id]
+          value = empty? ? 0 : FutureMetric.wrap(self, metric, :rollup)
+          store metric.id, value
+          @metrics_hash[metric.id] = metric
+        end
+        self
+      end
+
+    end
+  end
+end

data/lib/martyr/runtime/data_set/element_locator.rb

@@ -0,0 +1,143 @@
+module Martyr
+  module Runtime
+
+    # This is a service object that allows locating an element given element coordinates and "locate instructions".
+    # It is structured to allow locating elements even in the absence of a real element to "start from".
+
+    # A locator deals with real elements - meaning belonging to one cube.
+
+    class ElementLocator
+      include ActiveModel::Model
+      include Martyr::Translations
+
+      # @attribute metrics [Array<BaseMetric>] the metrics that should be rolled up on the located element
+      # @attribute memory_slice [MemorySlice] the current memory slice. Sent to FactIndexer and used to build
+      #   Coordinate objects.
+      # @attribute fact_indexer [#dimension_bus, #get_element, #cube_name]
+      # @attribute restrict_level_ids [Array<String>] level IDs that are supported by the cube this locator belongs to.
+      # @attribute helper_module [Module] a module to be included into every element
+      # @attribute standardizer [MetricIdStandardizer] used to standardize user input given in procs calling locate
+      attr_accessor :metrics, :memory_slice, :fact_indexer, :restrict_level_ids, :helper_module, :standardizer
+
+      delegate :dimension_bus, :cube_name, to: :fact_indexer
+      delegate :definition_from_id, to: :dimension_bus
+
+      # @param level_ids [Array<String>] the granularity at which the elements need to be fetched
+      # @return [Array<Element>]
+      def all(level_ids)
+        Schema::CountDistinctMetric.enable_rollup_strategy_caching(metrics) do
+          fact_indexer.elements_by(memory_slice, level_ids).map {|element| finalize_element(element)}
+        end
+      end
+
+      # Get an element based on coordinates.
+      # If the coordinates contain an unsupported level, it returns nil.
+      # @param grain_hash [Hash] see Coordinates. We do not need Coordinates here so we prefer to allow sending in a
+      #   Hash.
+      # @param exclude_metric_id [nil, String, Array<String>] @see #finalize_elements
+      def get(grain_hash, exclude_metric_id: nil, memory_slice: nil)
+        memory_slice ||= self.memory_slice
+
+        elm = fact_indexer.get_element(memory_slice, grain_hash) unless restrict_level_ids.present? and
+          (grain_hash.keys - restrict_level_ids).present?
+
+        elm ||= unfinalized_empty_element(grain_hash, memory_slice: memory_slice)
+        finalize_element(elm, exclude_metric_id: exclude_metric_id)
+      end
+
+      # Get an element based on existing coordinates hash AND changes instructions sent to #locate
+      # @param grain_hash [Hash] base coordinates that are to be manipulated.
+      # @param *several_variants
+      # Variant 1:
+      #   level_id [String] level ID to slice
+      #   with [String] value at level
+      # Variant 2:
+      #   slice_hash [Hash] level IDs and their values to slice
+      # @option reset [String, Array<String>] level ids to remove from coordinates
+      # @option standardizer [MetricIdStandardizer]
+      # @option exclude_metric_id [String, Array<String>] @see finalize_element
+      #
+      # @examples
+      #   locate(coords, 'customers.country', with: 'USA', reset: '')
+      def locate(grain_hash, *several_variants)
+        slice_hash, reset_arr, options = sanitize_args_for_locate(*several_variants)
+        dimensions_slice_hash, metrics_slice_hash = separate_dimensions_and_metrics(slice_hash)
+        metrics_slice_hash = standardizer.standardize(metrics_slice_hash)
+        new_memory_slice = metrics_slice_hash.present? ? memory_slice.dup_internals.slice_hash(metrics_slice_hash) : memory_slice
+        new_coords = coordinates_from_grain_hash(grain_hash, memory_slice: new_memory_slice).locate(dimensions_slice_hash, reset: reset_arr)
+        get(new_coords.grain_hash, memory_slice: new_memory_slice, **options)
+      end
+
+      def empty_element(grain_hash={}, memory_slice: nil)
+        finalize_element unfinalized_empty_element(grain_hash, memory_slice: memory_slice)
+      end
+
+      private
+
+      # @param grain_hash [Hash]
+      # @return [Coordinates]
+      def coordinates_from_grain_hash(grain_hash, memory_slice: nil)
+        memory_slice ||= self.memory_slice
+        Coordinates.new(grain_hash, memory_slice.to_hash)
+      end
+
+      # @param element [Hash] element that does not have metrics rolled up and whose element_locator is missing
+      # @return [Element] fully initialized
+      def finalize_element(element, exclude_metric_id: nil)
+        exclude_metric_id = Array.wrap(exclude_metric_id)
+        element.element_locator = self
+        element.helper_module = helper_module
+        element.extend(helper_module) if helper_module.present?
+        element.rollup *metrics.reject{|m| exclude_metric_id.include? m.id.to_s }
+        element
+      end
+
+      def sanitize_args_for_locate(*several_variants)
+        if several_variants.length == 2
+          slice_definition, reset_arr, options = extract_options_for_locate(several_variants[1])
+          slice_hash = {several_variants[0] => slice_definition}
+        elsif several_variants.length == 1 and several_variants.first.is_a?(Hash)
+          slice_hash, reset_arr, options = extract_options_for_locate(several_variants.first)
+        else
+          raise ArgumentError.new("wrong number of arguments #{several_variants.length} for (1..2)")
+        end
+        standardizer = options.delete(:standardizer) || MetricIdStandardizer.new
+
+        validate_no_metrics standardizer.standardize(reset_arr)
+
+        [standardizer.standardize(slice_hash), standardizer.standardize(reset_arr), options]
+      end
+
+      def extract_options_for_locate(hash)
+        option_keys = [:standardizer, :exclude_metric_id]
+        hash_dup = hash.dup
+
+        options = hash_dup.slice(*option_keys)
+        reset = hash_dup.delete(:reset) || hash_dup.delete('reset')
+        slice = hash_dup.except!(*option_keys)
+        [slice, Array.wrap(reset), options]
+      end
+
+      # @param hash [Hash] of keys and set instructions
+      # @return [Hash, Hash] first hash is dimensions, second is metrics
+      def separate_dimensions_and_metrics(hash)
+        dimension_keys = hash.keys.select{|id| definition_from_id(first_element_from_id(id)).respond_to?(:dimension?)}
+        [hash.slice(*dimension_keys), hash.except(*dimension_keys)]
+      end
+
+      # @param ids_array [Array] array of fully qualified IDs that contain either metrics or dimensions
+      def validate_no_metrics(ids_array)
+        ids_array.each do |id|
+          raise Query::Error.new('Can only reset on dimensions') unless
+            definition_from_id(first_element_from_id(id)).respond_to?(:dimension?)
+        end
+      end
+
+      def unfinalized_empty_element(grain_hash, memory_slice: nil)
+        coordinates = coordinates_from_grain_hash(grain_hash, memory_slice: memory_slice)
+        Element.new(coordinates, {}, [])
+      end
+
+    end
+  end
+end

data/lib/martyr/runtime/data_set/fact.rb

@@ -0,0 +1,83 @@
+module Martyr
+  module Runtime
+    class Fact < Hash
+      include Martyr::LevelComparator
+      include Martyr::Translations
+
+      attr_reader :sub_cube, :raw, :grain_level_ids
+      delegate :dimension_bus, to: :sub_cube
+
+      def initialize(sub_cube, query_result_hash)
+        @sub_cube = sub_cube
+        @raw = query_result_hash
+        @grain_level_ids = []
+        merge_value_by_levels_hash
+        merge_built_in_metrics_hash
+        merge_custom_metrics_hash
+      end
+
+      alias_method :hash_fetch, :fetch
+
+      # @param id [String] either metric id or level id
+      def fetch(id)
+        value = hash_fetch(fully_qualify_id(id))
+        value.is_a?(FutureFactValue) || value.is_a?(FutureMetric) ? value.value : value
+      end
+      alias_method :[], :fetch
+
+      # Similar to fetch, but returns the original fact_key_value if such existed for the level
+      def fact_key_for(level_id)
+        value = hash_fetch(level_id)
+        value.is_a?(FutureFactValue) ? (value.fact_key_value || value.value) : value
+      end
+
+      # Similar to fetch, but returns the active record object if such existed for the level
+      def record_for(level_id)
+        value = hash_fetch(level_id)
+        value.is_a?(FutureFactValue) ? (value.active_record || value.value) : value
+      end
+
+      def load
+        keys.each{|key| fetch(key)}
+        self
+      end
+
+      private
+
+      def merge_value_by_levels_hash
+        sub_cube.fact_levels_filler_hash.each do |level_id, filler|
+          store level_id, filler.value(self)
+          @grain_level_ids << level_id
+        end
+      end
+
+      def merge_built_in_metrics_hash
+        sub_cube.built_in_metrics.each do |metric|
+          store metric.id, metric.extract(self)
+        end
+      end
+
+      # This has to occur after merging the built_in_metrics_hash so that the user custom code can fetch
+      # existing metrics. We merge them one after the other so custom metrics can depend on one another.
+      def merge_custom_metrics_hash
+        sub_cube.custom_metrics.each do |metric|
+          store metric.id, FutureMetric.wrap(self, metric, :extract)
+        end
+      end
+
+      def fully_qualify_id(id)
+        with_standard_id(id) do |dimension_or_cube_or_metric, level_or_metric|
+          level_or_metric ? id : "#{sub_cube.cube_name}.#{dimension_or_cube_or_metric}"
+        end
+      end
+
+      private
+
+      def method_missing(method, *args, &block)
+        return fetch(method) if has_key? fully_qualify_id(method)
+        super
+      end
+
+    end
+  end
+end

data/lib/martyr/runtime/data_set/fact_indexer.rb

@@ -0,0 +1,72 @@
+module Martyr
+  module Runtime
+    class FactIndexer
+
+      attr_reader :sub_cube, :facts
+      delegate :dimension_bus, :cube_name, to: :sub_cube
+
+      def initialize(sub_cube, facts)
+        @sub_cube = sub_cube
+        @facts = facts
+        @indices = {}
+      end
+
+      # @param memory_slice [MemorySlice] scoped to the current cube
+      # @param level_ids [Array<String>] level ids used to group facts by
+      # @return [Array<Element>] creates an array of elements. Each elements holds multiple facts based on
+      #   level_keys_arr.
+      #
+      # Example:
+      #   Consider facts with the following grain:
+      #        media_types.name    genres.name       customers.country     Metric 1      Metric 2
+      #     1  MPEG audio file     Rock              USA                   100           20
+      #     2  MPEG audio file     Pop               USA                   76            32
+      #     3  MPEG audio file     Jazz              USA                   98            16
+      #     4  AAC audio file      Rock              USA                   57            25
+      #     5  AAC audio file      Pop               USA                   98            72
+      #     6  AAC audio file      Jazz              USA                   34            18
+      #
+      # Running `elements_by 'genres.name'` will return 3 elements:
+      #     genres.name     Contained facts
+      #     Rock            1,4
+      #     Pop             2,5
+      #     Jazz            3,6
+      #
+      # In addition, each element will have the metrics, rolled-up based on their roll-up function
+      #
+      def elements_by(memory_slice, level_ids)
+        elements_hash(memory_slice, level_ids).values
+      end
+
+      # @param memory_slice [MemorySlice]
+      # @param grain_hash [Hash] see Coordinates
+      # @return [Element] that resides in the provided coordinates
+      def get_element(memory_slice, grain_hash)
+        grain_hash_values_sorted_by_level_id = grain_hash.keys.sort.map{|x| grain_hash[x]}
+        elements_hash(memory_slice, grain_hash.keys)[grain_hash_values_sorted_by_level_id]
+      end
+
+      private
+
+      # @return [Hash] { element_key => Element }
+      #   where element_key is array of values for levels in the same order of level_ids.
+      def elements_hash(memory_slice, level_ids)
+        sorted_level_ids = level_ids.sort
+        index_key = {slice: memory_slice.to_hash, levels: sorted_level_ids}
+        return @indices[index_key] if @indices[index_key]
+
+        arr = memory_slice.apply_on(facts).group_by do |fact|
+          sorted_level_ids.map{|id| fact.fact_key_for(id)}
+        end.map do |element_key, facts_arr|
+          grain_arr = sorted_level_ids.each_with_index.map{|level_id, i| [level_id, element_key[i]]}
+          coordinates = Coordinates.new(Hash[grain_arr], memory_slice.to_hash)
+
+          representative = facts_arr.first
+          values_arr = sorted_level_ids.map{|id| [id, representative.fetch(id)]}
+          [element_key, Element.new(coordinates, Hash[values_arr], facts_arr)]
+        end
+        @indices[index_key] = Hash[arr]
+      end
+    end
+  end
+end

data/lib/martyr/runtime/data_set/future_fact_value.rb

@@ -0,0 +1,58 @@
+module Martyr
+  module Runtime
+    class FutureFactValue
+
+      attr_reader :fact_record, :level, :fact_key_value, :key_supported
+      delegate :dimension_bus, to: :fact_record
+
+      # @param fact_record [Fact]
+      # @param level [BaseLevelDefinition] the level that needs to be fetched
+      # @param key_supported [Boolean] if true, this means the fact has direct association with the level, and the
+      #   value simply needs to be fetched from the dimension. fact_key_value must be provided when true.
+      # @param fact_key_value [String, Integer] only relevant if key_supported is true.
+      def initialize(fact_record, level, key_supported:, fact_key_value: nil)
+        @level = level
+        @fact_record = fact_record
+        @fact_key_value = fact_key_value.try(:to_i)
+        @key_supported = key_supported
+      end
+
+      def inspect
+        value_loaded? ? @value.inspect : '?'
+      end
+
+      def value
+        return @value if value_loaded?
+        if key_supported
+          @active_record = dimension_bus.fetch_supported_query_level_record(level.id, fact_key_value)
+          @value = level.record_value(@active_record)
+        else
+          value = dimension_bus.fetch_unsupported_level_value(level.id, fact_record)
+          if level.degenerate?
+            @value = value
+          else
+            @active_record = value
+            @value = level.record_value(@active_record)
+          end
+        end
+        @value_loaded = true
+        @value
+      end
+
+      def active_record
+        value unless value_loaded?
+        @active_record
+      end
+
+      def value_loaded?
+        !!@value_loaded
+      end
+
+      protected
+
+      def ==(other)
+        value == other.value and fact_key_value == other.fact_key_value
+      end
+    end
+  end
+end

data/lib/martyr/runtime/data_set/future_metric.rb

@@ -0,0 +1,40 @@
+# This class is used in two cases:
+# For facts:
+#   To prevent calculation of custom metrics as user code may rely on dimension initialization during
+#   the process of figuring out which keys should be initialized.
+#
+# For elements:
+#   To prevent infinite recursion that can be caused if a cube has two custom rollups that call `locate`.
+#   The result would be that the calculations oscillates between the two metrics on the newly located element.
+
+module Martyr
+  module Runtime
+    class FutureMetric
+
+      # @param element_or_fact [Element, Fact]
+      # @param metric [BaseMetric]
+      # @param method [:rollup, :extract]
+      def self.wrap(element_or_fact, metric, method)
+        if metric.is_a?(Martyr::Schema::BuiltInMetric)
+          metric.send(method, element_or_fact)
+        else
+          proc = -> { metric.send(method, element_or_fact) }
+          new(proc)
+        end
+      end
+
+      def initialize(proc)
+        @proc = proc
+      end
+
+      def inspect
+        @value_retrieved ? @value.inspect : '?'
+      end
+
+      def value
+        @value_retrieved = true
+        @value ||= @proc.call
+      end
+    end
+  end
+end