active_reporting 0.6.1 → 1.0.0

data/lib/active_reporting/report.rb

@@ -4,14 +4,32 @@ require 'forwardable'
 module ActiveReporting
   class Report
     AGGREGATE_FUNCTION_OPERATORS = {
-      eq:   '=',
-      gt:   '>',
-      gte:  '>=',
-      lt:   '<',
-      lte:  '<='
+      eq: '=',
+      gt: '>',
+      gte: '>=',
+      lt: '<',
+      lte: '<='
     }.freeze
 
+    DIMENSION_FILTER_ON_VALUES = [true, 'true'].freeze
+    DIMENSION_FILTER_OFF_VALUES = [false, 'false'].freeze
+
     extend Forwardable
+
+    # Converts a metric filter's operators to symbols, raising if any operator is not supported
+    #
+    # @param metric_filter [Hash] operator (e.g. `:gt` or `'gt'`) to value
+    # @return [Hash]
+    def self.normalize_metric_filter(metric_filter)
+      metric_filter.to_h.transform_keys do |operator|
+        next operator.to_sym if AGGREGATE_FUNCTION_OPERATORS.key?(operator.to_s.to_sym)
+
+        raise UnknownMetricFilterOperator,
+              "Unknown metric filter operator '#{operator}'. Valid operators are: " \
+              "#{AGGREGATE_FUNCTION_OPERATORS.keys.join(', ')}"
+      end
+    end
+
     def_delegators :@metric, :fact_model, :model
 
     def initialize(metric, dimension_identifiers: true, dimension_filter: {}, dimensions: [], metric_filter: {})
@@ -21,9 +39,10 @@ module ActiveReporting
       @dimension_identifiers  = dimension_identifiers
       local_dimensions        = ReportingDimension.build_from_dimensions(fact_model, Array(dimensions))
       @dimensions             = (@metric.dimensions + local_dimensions).uniq
-      @metric_filter          = @metric.metric_filter.merge(metric_filter)
-      @ordering               = @metric.order_by_dimension
+      # The report's metric filter replaces the metric's, while the metric's dimension filters can't be overridden
+      @metric_filter          = @metric.metric_filter.merge(Report.normalize_metric_filter(metric_filter))
       partition_dimension_filters dimension_filter
+      @order_by = build_order_by
     end
 
     # Builds and executes a query, returning the raw result
@@ -36,13 +55,14 @@ module ActiveReporting
     private ######################################################################
 
     def build_data
-      @data = model.connection.exec_query(statement.to_sql).to_a
+      @data = model.connection.select_all(statement, 'ActiveReporting').to_a
       apply_dimension_callbacks
       @data
     end
 
     def partition_dimension_filters(user_dimension_filter)
       @dimension_filters = { ransack: {}, scope: {}, lambda: {} }
+      # The metric's dimension filters are part of its definition, so they take precedence over the report's
       user_dimension_filter.merge(@metric.dimension_filter).each do |key, value|
         dm = fact_model.find_dimension_filter(key.to_sym)
         @dimension_filters[dm.type][dm] = value
@@ -56,7 +76,7 @@ module ActiveReporting
         left_outer_joins: dimension_joins(ReportingDimension::JOIN_METHODS[:left_outer_joins]),
         group: group_by_statement,
         having: having_statement,
-        order: order_by_statement
+        order: @order_by
       }
 
       statement = ([model] + parts.keys).inject do |chain, method|
@@ -65,13 +85,11 @@ module ActiveReporting
 
       statement = process_scope_dimension_filter(statement)
       statement = process_lambda_dimension_filter(statement)
-      statement = process_ransack_dimension_filter(statement)
-
-      statement
+      process_ransack_dimension_filter(statement)
     end
 
     def select_statement
-      ss = ["#{select_aggregate} AS #{@metric.name}"]
+      ss = ["#{select_aggregate} AS #{model.connection.quote_column_name(@metric.name)}"]
       ss += @dimensions.map { |d| d.select_statement(with_identifier: @dimension_identifiers) }
       ss.flatten
     end
@@ -81,36 +99,52 @@ module ActiveReporting
       when :count
         'COUNT(*)'
       else
-        "#{@metric.aggregate.to_s.upcase}(#{fact_model.measure})"
+        "#{@metric.aggregate.to_s.upcase}(#{measure_fragment})"
       end
     end
 
+    # The measure as a column qualified by the fact model's table, so it is never ambiguous with a column on
+    # a joined dimension. A measure given as `Arel.sql(...)` is used as is, allowing SQL expressions.
+    def measure_fragment
+      measure = @metric.measure || fact_model.measure
+      return measure if measure.is_a?(Arel::Nodes::SqlLiteral)
+
+      "#{model.quoted_table_name}.#{model.connection.quote_column_name(measure)}"
+    end
+
     def dimension_joins(join_method)
-      @dimensions.select { |d| d.type == Dimension::TYPES[:standard] && d.join_method == join_method }.
-                  map { |d| d.name.to_sym }
+      @dimensions.select { |d| d.type == Dimension::TYPES[:standard] && d.join_method == join_method }
+                 .map { |d| d.name.to_sym }
     end
 
     def group_by_statement
       @dimensions.map { |d| d.group_by_statement(with_identifier: @dimension_identifiers) }
     end
 
+    # Rails defines scopes methods taking any arguments, so it can't be known if a scope takes an argument.
     def process_scope_dimension_filter(chain)
-      @dimension_filters[:scope].each do |dm, args|
-        chain = if [true, 'true'].include?(args)
-                  chain.public_send(dm.name)
+      @dimension_filters[:scope].each do |df, value|
+        next if DIMENSION_FILTER_OFF_VALUES.include?(value)
+
+        chain = if DIMENSION_FILTER_ON_VALUES.include?(value)
+                  chain.public_send(df.name)
                 else
-                  chain.public_send(dm.name, args)
+                  chain.public_send(df.name, value)
                 end
       end
       chain
     end
 
+    # A lambda without parameters is a toggle: it is applied unless its value is `false`. A lambda with
+    # parameters is always passed the value, so it can take `true` and `false` as well.
     def process_lambda_dimension_filter(chain)
-      @dimension_filters[:lambda].each do |df, args|
-        chain = if [true, 'true'].include?(args)
-                  chain.scoping { model.instance_exec(&df.body) }
+      @dimension_filters[:lambda].each do |df, value|
+        chain = if df.body.arity.nonzero?
+                  chain.scoping { model.instance_exec(value, &df.body) }
+                elsif DIMENSION_FILTER_OFF_VALUES.include?(value)
+                  chain
                 else
-                  chain.scoping { model.instance_exec(args, &df.body) }
+                  chain.scoping { model.instance_exec(&df.body) }
                 end
       end
       chain
@@ -121,8 +155,12 @@ module ActiveReporting
       @dimension_filters[:ransack].each do |dm, value|
         ransack_hash[dm.name] = value
       end
-      chain = chain.ransack(ransack_hash).result if ransack_hash.present?
-      chain
+      return chain if ransack_hash.empty?
+      unless Configuration.ransack_available
+        raise RansackNotAvailable, 'Ransack not available. Please include it in your Gemfile.'
+      end
+
+      chain.ransack(ransack_hash).result
     end
 
     def having_statement
@@ -131,12 +169,16 @@ module ActiveReporting
       end.join(' AND ')
     end
 
-    def order_by_statement
-      [].tap do |o|
-        @ordering.each do |dimension_key, direction|
-          dim = @dimensions.detect { |d| d.name.to_sym == dimension_key.to_sym }
-          o << dim.order_by_statement(direction: direction) if dim
+    def build_order_by
+      @metric.order_by_dimension.map do |dimension_key, direction|
+        dim = @dimensions.detect { |d| d.name.to_sym == dimension_key.to_sym }
+        if dim.nil?
+          raise UnknownDimension,
+                "Cannot order by '#{dimension_key}'; it is not one of the report's dimensions " \
+                "(#{@dimensions.map(&:name).join(', ')})"
         end
+
+        dim.order_by_statement(direction: direction)
       end
     end
 
@@ -144,7 +186,8 @@ module ActiveReporting
       @dimensions.each do |dimension|
         callback = dimension.label_callback
         next unless callback
-        key = "#{dimension.name}_#{dimension.label}"
+
+        key = dimension.label_name.to_s
         @data.each do |hash|
           hash[key] = callback.call(hash[key])
         end

data/lib/active_reporting/reporting_dimension.rb

@@ -4,13 +4,17 @@ require 'forwardable'
 module ActiveReporting
   class ReportingDimension
     extend Forwardable
-    SUPPORTED_DBS = %w[PostgreSQL PostGIS Mysql2].freeze
+
     # Values for the Postgres `date_trunc` method.
-    # See https://www.postgresql.org/docs/10/static/functions-datetime.html#FUNCTIONS-DATETIME-TRUNC
+    # See https://www.postgresql.org/docs/current/functions-datetime.html#FUNCTIONS-DATETIME-TRUNC
     DATETIME_HIERARCHIES = %i[microseconds milliseconds second minute hour day week month quarter year decade
                               century millennium date].freeze
+    # Column types a datetime drill can be used on. PostgreSQL reports `timestamp with time zone` columns as
+    # `timestamptz`, and `timestamp without time zone` columns as `timestamp` when its `datetime_type` is
+    # `:timestamptz`.
+    DATETIME_DRILL_COLUMN_TYPES = %i[datetime timestamp timestamptz date].freeze
     JOIN_METHODS = { joins: :joins, left_outer_joins: :left_outer_joins }.freeze
-    attr_reader :join_method, :label
+    attr_reader :join_method, :label, :label_name
 
     def_delegators :@dimension, :name, :type, :klass, :association, :model, :hierarchical?
 
@@ -19,15 +23,17 @@ module ActiveReporting
         dimension_name, options = dim.is_a?(Hash) ? Array(dim).flatten : [dim, nil]
         found_dimension = fact_model.dimensions[dimension_name.to_sym]
 
-        raise(UnknownDimension, "Dimension '#{dimension_name}' not found on fact model '#{fact_model}'") if found_dimension.nil?
+        if found_dimension.nil?
+          raise(UnknownDimension,
+                "Dimension '#{dimension_name}' not found on fact model '#{fact_model}'")
+        end
 
-        # Ambiguous behavior with string option for degenerate and standard dimension
-        if !options.is_a?(Hash) && found_dimension.type == Dimension::TYPES[:degenerate]
-          ActiveSupport::Deprecation.warn <<~EOS
-            direct use of implict hierarchies is deprecated and will be removed in future versions. \
-            Please use `:datetime_drill` option instead.
-          EOS
-          options = { datetime_drill: options }
+        # The `{ created_at: :month }` shorthand for datetime drills was removed in 0.7.0
+        if options && !options.is_a?(Hash) && found_dimension.type == Dimension::TYPES[:degenerate]
+          raise InvalidDimensionLabel,
+                "'#{dimension_name}' is not hierarchical. For a datetime drill, use " \
+                "`{ #{dimension_name}: { datetime_drill: :#{options} } }` " \
+                "instead of `{ #{dimension_name}: :#{options} }`"
         end
         new(found_dimension, **label_config(options))
       end
@@ -39,9 +45,7 @@ module ActiveReporting
     #
     # @param [Symbol|Hash] options
     def self.label_config(options)
-      unless options.is_a?(Hash)
-        return { label: options }
-      end
+      return { label: options } unless options.is_a?(Hash)
 
       {
         label: options[:field],
@@ -75,7 +79,7 @@ module ActiveReporting
     # @return [Array]
     def select_statement(with_identifier: true)
       ss = ["#{label_fragment} AS #{label_fragment_alias}"]
-      ss << "#{identifier_fragment} AS #{identifier_fragment_alias}" if with_identifier && type == Dimension::TYPES[:standard]
+      ss << "#{identifier_fragment} AS #{identifier_fragment_alias}" if with_identifier && identifiable?
       ss
     end
 
@@ -84,7 +88,7 @@ module ActiveReporting
     # @return [Array]
     def group_by_statement(with_identifier: true)
       group = [label_fragment]
-      group << identifier_fragment if with_identifier && type == Dimension::TYPES[:standard]
+      group << identifier_fragment if with_identifier && identifiable?
       group
     end
 
@@ -93,36 +97,52 @@ module ActiveReporting
     # @return [String]
     def order_by_statement(direction:)
       direction = direction.to_s.upcase
-      raise "Ording direction should be 'asc' or 'desc'" unless %w[ASC DESC].include?(direction)
+      unless %w[ASC DESC].include?(direction)
+        raise InvalidOrderDirection,
+              "Ordering direction for #{name} should be 'asc' or 'desc', got '#{direction.downcase}'"
+      end
+
       "#{label_fragment} #{direction}"
     end
 
+    # Tells if the dimension's identifier is included in queries when the report asks for identifiers.
+    #
+    # Only a standard dimension labeled by its default label has one row per record. Grouping a dimension
+    # drilled to a hierarchy level or datetime by its identifier as well would split each roll-up back into one
+    # row per record.
+    #
+    # @return [Boolean]
+    def identifiable?
+      type == Dimension::TYPES[:standard] && @datetime_drill.nil? && @label == dimension_fact_model.dimension_label
+    end
+
     # Looks up the dimension label callback for the label
     #
     # @return [Lambda, NilClass]
     def label_callback
-      klass.fact_model.dimension_label_callbacks[@label]
+      klass.fact_model.dimension_label_callbacks[@label.to_sym]
     end
 
     private ####################################################################
 
     def determine_label_field(label_field)
-      @label = if label_field.present? && validate_hierarchical_label(label_field)
-                 type == Dimension::TYPES[:degenerate] ? name : label_field.to_sym
-               elsif type == Dimension::TYPES[:degenerate]
+      validate_hierarchical_label(label_field) if label_field.present?
+
+      @label = if type == Dimension::TYPES[:degenerate]
                  name
+               elsif label_field.present?
+                 label_field.to_sym
                else
                  dimension_fact_model.dimension_label || Configuration.default_dimension_label
                end
     end
 
     def determine_label_name(label_name)
-
       if label_name
         @label_name = label_name
       else
         @label_name = name
-        @label_name += "_#{@label}" if (type == Dimension::TYPES[:standard] && @label != :name)
+        @label_name += "_#{@label}" if type == Dimension::TYPES[:standard] && @label != :name
         @label_name += "_#{@datetime_drill}" if @datetime_drill
       end
       @label_name
@@ -130,6 +150,7 @@ module ActiveReporting
 
     def determine_datetime_drill(datetime_drill)
       return unless datetime_drill
+
       validate_supported_database_for_datetime_hierarchies
       validate_against_datetime_hierarchies(datetime_drill)
       validate_label_is_datetime
@@ -147,18 +168,19 @@ module ActiveReporting
     end
 
     def validate_hierarchical_label(hierarchical_label)
-      validate_dimension_is_hierachical(hierarchical_label)
+      validate_dimension_is_hierarchical(hierarchical_label)
       validate_against_fact_model_properties(hierarchical_label)
-      true
     end
 
-    def validate_dimension_is_hierachical(hierarchical_label)
+    def validate_dimension_is_hierarchical(hierarchical_label)
       return if hierarchical?
+
       raise InvalidDimensionLabel, "#{name} must be hierarchical to use label #{hierarchical_label}"
     end
 
     def validate_supported_database_for_datetime_hierarchies
-      return if SUPPORTED_DBS.include?(model.connection.adapter_name)
+      return if datetime_drill_adapter
+
       raise InvalidDimensionLabel,
             "Cannot utilize datetime grouping for #{name}; " \
             "database #{model.connection.adapter_name} is not supported"
@@ -166,67 +188,26 @@ module ActiveReporting
 
     def validate_against_datetime_hierarchies(hierarchical_label)
       return if DATETIME_HIERARCHIES.include?(hierarchical_label.to_sym)
+
       raise InvalidDimensionLabel, "#{hierarchical_label} is not a valid datetime grouping label in #{name}"
     end
 
     def validate_label_is_datetime
-      return if dimension_fact_model.model.column_for_attribute(@label).type == :datetime
-      raise InvalidDimensionLabel, "'#{@label}' is not a datetime column"
+      return if DATETIME_DRILL_COLUMN_TYPES.include?(dimension_fact_model.model.column_for_attribute(@label).type)
+
+      raise InvalidDimensionLabel, "'#{@label}' is not a datetime or date column"
     end
 
     def validate_against_fact_model_properties(hierarchical_label)
       return if dimension_fact_model.hierarchical_levels.include?(hierarchical_label.to_sym)
-      raise InvalidDimensionLabel, "#{hierarchical_label} is not a hierarchical label in #{name}"
-    end
 
-    def datetime_drill_label_fragment(column)
-      if model.connection.adapter_name == "Mysql2"
-        datetime_drill_mysql(column)
-      else # Postgress
-        datetime_drill_postgress(column)
-      end
+      raise InvalidDimensionLabel, "#{hierarchical_label} is not a hierarchical label in #{name}"
     end
 
-    def datetime_drill_postgress(column)
-      case @datetime_drill.to_sym
-      when :date
-        "DATE('#{column}')"
-      else
-        "DATE_TRUNC('#{@datetime_drill}', #{column})"
-      end
-    end
+    def datetime_drill_adapter
+      return @datetime_drill_adapter if defined?(@datetime_drill_adapter)
 
-    def datetime_drill_mysql(column)
-      case @datetime_drill.to_sym
-      when :microseconds
-        "MICROSECOND(#{column})"
-      when :milliseconds
-        "MICROSECOND(#{column}) DIV 1000"
-      when :second
-        "SECOND(#{column})"
-      when :minute
-        "MINUTE(#{column})"
-      when :hour
-        "HOUR(#{column})"
-      when :day
-        "DAY(#{column})"
-      when :week
-        "WEEKDAY(#{column})"
-      when :month
-        "MONTH(#{column})"
-      when :quarter
-        "QUARTER(#{column})"
-      when :year
-        "YEAR(#{column})"
-      when :decade
-        "YEAR(#{column}) DIV 10"
-      when :century
-        "YEAR(#{column}) DIV 100"
-      when :millennium
-        "YEAR(#{column}) DIV 1000"
-      when :date
-        "DATE(#{column})"
-      end
+      @datetime_drill_adapter = DatetimeDrill.adapter_for(model.connection)
     end
 
     def identifier_fragment
@@ -234,17 +215,17 @@ module ActiveReporting
     end
 
     def identifier_fragment_alias
-      "#{model.connection.quote_column_name("#{name}_identifier")}"
+      model.connection.quote_column_name("#{name}_identifier").to_s
     end
 
     def label_fragment
       fragment = "#{klass.quoted_table_name}.#{model.connection.quote_column_name(@label)}"
-      fragment = datetime_drill_label_fragment(fragment) if @datetime_drill
+      fragment = DatetimeDrill.fragment(datetime_drill_adapter, @datetime_drill, fragment) if @datetime_drill
       fragment
     end
 
     def label_fragment_alias
-      "#{model.connection.quote_column_name(@label_name)}"
+      model.connection.quote_column_name(@label_name).to_s
     end
 
     def dimension_fact_model

data/lib/active_reporting/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ActiveReporting
-  VERSION = '0.6.1'
+  VERSION = '1.0.0'
 end

data/lib/active_reporting.rb

@@ -3,43 +3,63 @@
 require 'active_record'
 require 'active_reporting/active_record_adaptor'
 require 'active_reporting/configuration'
+require 'active_reporting/datetime_drill'
 require 'active_reporting/dimension'
 require 'active_reporting/dimension_filter'
 require 'active_reporting/metric'
 require 'active_reporting/fact_model'
+require 'active_reporting/fact_model_registry'
 require 'active_reporting/report'
 require 'active_reporting/reporting_dimension'
 require 'active_reporting/version'
+require 'active_reporting/railtie' if defined?(Rails::Railtie)
 
-begin
-  require 'ransack'
-  ActiveReporting::Configuration.ransack_available = true
-rescue LoadError, StandardError
-  ActiveReporting::Configuration.ransack_available = false
-end
-
-ActiveRecord::Base.extend(ActiveReporting::ActiveRecordAdaptor)
+ActiveSupport.on_load(:active_record) { extend ActiveReporting::ActiveRecordAdaptor }
 
 module ActiveReporting
   def self.fetch_metric(name)
-    klass = Configuration.metric_lookup_class
-    unless defined?(klass.constantize)
+    klass_name = Configuration.metric_lookup_class
+    klass = klass_name.safe_constantize
+    if klass.nil?
       raise BadMetricLookupClass,
-            "#{klass} not defined. Please define a class responsible for looking up a metric by name." \
-            ' You may define your own class and set it with `ActiveReporting::Configuration.metric_lookup_class=`.'
+            "#{klass_name} not defined. Please define a class responsible for looking up a metric by name. " \
+            'You may define your own class and set it with `ActiveReporting::Configuration.metric_lookup_class=`.'
     end
-    unless klass.constantize.respond_to?(:lookup)
-      raise BadMetricLookupClass, "#{klass} needs to define a class method called 'lookup'"
+    unless klass.respond_to?(:lookup)
+      raise BadMetricLookupClass, "#{klass_name} needs to define a class method called 'lookup'"
     end
-    klass.constantize.lookup(name)
+
+    klass.lookup(name)
+  end
+
+  class BadMetricLookupClass < StandardError
+  end
+
+  class InvalidDimensionLabel < StandardError
+  end
+
+  # Subclasses RuntimeError, which was raised for invalid directions before this class existed
+  class InvalidOrderDirection < RuntimeError
+  end
+
+  class RansackNotAvailable < StandardError
   end
 
-  BadMetricLookupClass    = Class.new(StandardError)
-  InvalidDimensionLabel   = Class.new(StandardError)
-  RansackNotAvailable     = Class.new(StandardError)
-  UnknownAggregate        = Class.new(StandardError)
-  UnknownDimension        = Class.new(StandardError)
-  UnknownDimensionFilter  = Class.new(StandardError)
-  UnknownMetric           = Class.new(StandardError)
-  UnknownJoinMethod       = Class.new(StandardError)
+  class UnknownAggregate < StandardError
+  end
+
+  class UnknownDimension < StandardError
+  end
+
+  class UnknownDimensionFilter < StandardError
+  end
+
+  class UnknownMetric < StandardError
+  end
+
+  class UnknownMetricFilterOperator < StandardError
+  end
+
+  class UnknownJoinMethod < StandardError
+  end
 end