active_reporting 0.5.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 07ad5ad6e21234d6441a8e97908cf854406d30e2a77b741096d0c874c85d5c42
-  data.tar.gz: 982a82ba6ab68d81dee8a1db785f25d993ac14b2572e698923437a4c1a37bd1e
+  metadata.gz: 63bda6ce4591fc9695b29db8e53aee19966e3630e9c8b059c686678043f20938
+  data.tar.gz: e780a77254b8c8b1cc23ecc732146d581def733fef8669fc3a0419e32fabf5df
 SHA512:
-  metadata.gz: 0f7a37f152776e1d9fbc2440b71cb045464063f759c88cfff5d6dc0302ab8e9f6ea7aeed4c35375b5ad25861132dfb1ba4ebad57da6051ba75680beb309c3665
-  data.tar.gz: 0c07b8989e32d26ca39105630ffe74b83207425449d412f344461c194926e0efed64da367449898295de62a3618910f7a249e94ee91efe0290b3332d1b820319
+  metadata.gz: 89718eab7d4398d77f9d19de7e7160e52feebfc295e03a7c05a113a87159e5e3640b599d681559c53e749bf68bdcee477effff6b4b605c4dcf317da6c09d2cdd
+  data.tar.gz: 4d999fe0374b28e826edbb6f6eca9fc9f8ab9ae7aff1056aa88757079e00847f8361862108ba65227f530b72fa918e849dd3bbfe1b337156a685dd4f26b706d8

data/CHANGELOG.md

@@ -1,3 +1,13 @@
+## 0.6.0 (2020-08-21)
+
+### Features
+
+* Support to implicit hierarchical on datetime columns in MySQL (#33) - *germanotm*
+* Added `{ datetime_drill: :month }` option for reporting dimentions to explicitly -  *germanotm*
+
+  This depricates the use of key-value only use for report dimension options (ie, `dimensions: [{ dim: single_option }]`).
+  Instead, use `dimensions: [{ dim: { option: value} }]` See the README for all reporting dimension options.
+
 ## 0.5.1 (2020-06-31)
 
 ### Features

data/README.md

@@ -49,6 +49,7 @@ Rails: ActiveRecord model
 A dimension is a point of data used to "slice and dice" data from a fact model. It's either a column that lives on the fact table or a foreign key to another table.
 
 Examples:
+
 * A sales rep on a fact table of sales
 * A state of an sale on a state machine
 * The manufacture on a fact table of widgets
@@ -62,6 +63,7 @@ Rails: ActiveRecord relation or attribute
 A hierarchy for a dimension is related attributes that live on a dimension table used to drill down and drill up through a dimension.
 
 Examples:
+
 * Dates: Date, Month, Year, Quarter
 * Mobile Phone: Model, Manufacture, OS, Wireless Technology
 
@@ -70,6 +72,7 @@ Examples:
 This is information related to a dimension. When the dimension lives on the fact table, the label is the column used. When the dimension is a related table, the label is a column representing the hierarchy level.
 
 Examples:
+
 * When dimensioning blog posts by category, the dimension is the category_id which leads to the categories table. The label would be the category name.
 
 ### Dimension Filter (or just "filter")
@@ -85,6 +88,7 @@ Rails: `where()`, scopes, etc.
 A measure is a column in a fact table (usually a numeric value) used in aggregations such as sum, maximum, average, etc.
 
 Examples:
+
 * Total amount in a sale
 * Number of units used in a transaction
 
@@ -219,11 +223,9 @@ class PhoneFactModel < ActiveReporting::FactModel
 end
 ```
 
-### Implicit hierarchies with datetime columns (PostgreSQL support only)
+### Drill down / Roll up (Drill up) with datetime columns
 
-The fastest approach to group by certain date metrics is to create so-called "date dimensions". For
-those Postgres users that are restricted from organizing their data in this way, Postgres provides
-a way to group by `datetime` column data on the fly using the `date_trunc` function.
+The fastest approach to group by certain date metrics is to create so-called "date dimensions" and add on columns for each desired hierarchy. For those users that are restricted from organizing their data in this way,  ActiveRporting provides a `datetime_drill` option that can be passed with the dimension on the metric definition to drill datetime columns.
 
 To use, declare a datetime dimension on a fact model as normal:
 
@@ -233,7 +235,23 @@ class UserFactModel < ActiveReporting::FactModel
 end
 ```
 
-When creating a metric, ActiveReporting will recognize implicit hierarchies for this dimension. The hierarchies correspond to the [values](https://www.postgresql.org/docs/8.1/static/functions-datetime.html#FUNCTIONS-DATETIME-TRUNC) supported by PostgreSQL. (See example under the metric section, below.)
+When creating a metric, ActiveReporting will recognize the following datetime hierarchies: (See example under the metric section, below.)
+
+- microseconds
+- milliseconds
+- second
+- minute
+- hour
+- day
+- week
+- month
+- quarter
+- year
+- decade
+- century
+- millennium
+
+Under the hood Active Reporting uses specific database functions to manipulate datetime columns. Postgres provides a way to group by `datetime` column data on the fly using the [`date_trunc` function](https://www.postgresql.org/docs/8.1/static/functions-datetime.html#FUNCTIONS-DATETIME-TRUNC). On Mysql this can be done using [Date and Time Functions](https://dev.mysql.com/doc/refman/8.0/en/date-and-time-functions.html).
 
 *NOTE*: PRs welcomed to support this functionality in other databases.
 
@@ -285,7 +303,17 @@ my_metric = ActiveReporting::Metric.new(
 
 `aggregate` - The SQL aggregate used to calculate the metric. Supported aggregates include count, max, min, avg, and sum. (Default: `:count`)
 
-`dimensions` - An array of dimensions used for the metric. When given just a symbol, the default dimension label will be used for the dimension. You may specify a hierarchy level by using a hash. (Examples: `[:sales_rep, {sale_date: :month}]`). In hierarchies you can customize the label in this way: `[{sale_date: { field: :month, name: :a_custom_name_for_month }}]`. If you use a hash instead of a Symbol to define a hierarchy the `field` item must be a valid field in your table. The `name` can be whatever label you want. You can choose the join_method with the dimension. The default value for join_method is :joins which does a standard "INNER JOIN", but you can pass a :left_outer_joins to use "LEFT OUTER JOIN" instead. Ex: `[{sales_rep: { join_method: :left_outer_joins }}]`
+`dimensions` - An array of dimensions used for the metric. When given just a symbol, the default dimension label will be used for the dimension.
+
+You may pass a hash instead of a symbol to customize the dimension options (example: { dimension_name: { option1: value, option2: value}}). The avaliable options are:
+
+- `field` - Specify the hierarchy level that should be used instead the default dimension label. Ex: `[:sales_rep, {mobile_phone: { field :manufacture }}]`. If you use a hash instead of a Symbol to define a hierarchy the `field` item must be a valid field in your table.
+
+- `name` - You may costumize the label alias, by default the dimension name will be used. The `name` can be whatever label you want. Ex :`[{sale_date: { field: :month, name: :a_custom_name_for_month }}]`.
+
+- `join_method` - You may choose the join_method with the dimension. The default value for join_method is :joins which does a standard "INNER JOIN", but you can pass a :left_outer_joins to use "LEFT OUTER JOIN" instead. Ex: `[{sales_rep: { join_method: :left_outer_joins }}]`
+
+- `datetime_drill` - To drill up and down over datetime column you may pass a `datetime_drill`. Ex: `[:sales_rep, { order: { field: :created_at, datetime_drill: :month }}]`. This option will perform an implicit drill over datetime columns and not a date dimension relationship.
 
 `dimension_filter` - A hash were the keys are dimension filter names and the values are the values passed into the filter.
 
@@ -303,7 +331,7 @@ end
 my_metric = ActiveReporting::Metric.new(
   :my_total,
   fact_model: UserFactModel,
-  dimensions: [{ created_at: :quarter } ]
+  dimensions: [{ created_at: { datetime_drill: :quarter }} ]
 )
 ```
 
@@ -376,7 +404,6 @@ appropriate `DB` environment variable, e.g. `DB=pg rake test`.
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/active_reporting. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
 
-
 ## License
 
 The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/lib/active_reporting/dimension.rb

@@ -30,13 +30,6 @@ module ActiveReporting
                 end
     end
 
-    # Whether the dimension is a datetime column
-    #
-    # @return [Boolean]
-    def datetime?
-      @datetime ||= type == TYPES[:degenerate] && model.column_for_attribute(@name).type == :datetime
-    end
-
     # Tells if the dimension is hierarchical
     #
     # @return [Boolean]

data/lib/active_reporting/report.rb

@@ -144,8 +144,9 @@ module ActiveReporting
       @dimensions.each do |dimension|
         callback = dimension.label_callback
         next unless callback
+        key = "#{dimension.name}_#{dimension.label}"
         @data.each do |hash|
-          hash[dimension.name.to_s] = callback.call(hash[dimension.name.to_s])
+          hash[key] = callback.call(hash[key])
         end
       end
     end

data/lib/active_reporting/reporting_dimension.rb

@@ -4,24 +4,32 @@ require 'forwardable'
 module ActiveReporting
   class ReportingDimension
     extend Forwardable
-    SUPPORTED_DBS = %w[PostgreSQL PostGIS].freeze
+    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
     DATETIME_HIERARCHIES = %i[microseconds milliseconds second minute hour day week month quarter year decade
                               century millennium].freeze
     JOIN_METHODS = { joins: :joins, left_outer_joins: :left_outer_joins }.freeze
-    attr_reader :join_method
+    attr_reader :join_method, :label
 
-    def_delegators :@dimension, :name, :type, :klass, :association, :model, :hierarchical?, :datetime?
+    def_delegators :@dimension, :name, :type, :klass, :association, :model, :hierarchical?
 
     def self.build_from_dimensions(fact_model, dimensions)
       Array(dimensions).map do |dim|
-        dimension_name, label = dim.is_a?(Hash) ? Array(dim).flatten : [dim, nil]
+        dimension_name, options = dim.is_a?(Hash) ? Array(dim).flatten : [dim, nil]
         found_dimension = fact_model.dimensions[dimension_name.to_sym]
 
-        raise(UnknownDimension, "Dimension '#{dim}' not found on fact model '#{fact_model}'") if found_dimension.nil?
-
-        new(found_dimension, **label_config(label))
+        raise(UnknownDimension, "Dimension '#{dimension_name}' not found on fact model '#{fact_model}'") if found_dimension.nil?
+
+        # 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 }
+        end
+        new(found_dimension, **label_config(options))
       end
     end
 
@@ -29,24 +37,28 @@ module ActiveReporting
     # the field on that dimension. With a hash you can
     # customize the name of the label
     #
-    # @param [Symbol|Hash] label
-    def self.label_config(label)
-      return { label: label } unless label.is_a?(Hash)
+    # @param [Symbol|Hash] options
+    def self.label_config(options)
+      unless options.is_a?(Hash)
+        return { label: options }
+      end
 
       {
-        label: label[:field],
-        label_name: label[:name],
-        join_method: label[:join_method]
+        label: options[:field],
+        label_name: options[:name],
+        join_method: options[:join_method],
+        datetime_drill: options[:datetime_drill]
       }
     end
 
     # @param dimension [ActiveReporting::Dimension]
     # @option label [Maybe<Symbol>] Hierarchical dimension to be used as a label
     # @option label_name [Maybe<Symbol|String>] Hierarchical dimension custom name
-    def initialize(dimension, label: nil, label_name: nil, join_method: nil)
+    def initialize(dimension, label: nil, label_name: nil, join_method: nil, datetime_drill: nil)
       @dimension = dimension
 
       determine_label_field(label)
+      determine_datetime_drill(datetime_drill)
       determine_label_name(label_name)
       determine_join_method(join_method)
     end
@@ -62,10 +74,8 @@ module ActiveReporting
     #
     # @return [Array]
     def select_statement(with_identifier: true)
-      return [degenerate_select_fragment] if type == Dimension::TYPES[:degenerate]
-
-      ss = ["#{label_fragment} AS #{model.connection.quote_column_name(@label_name)}"]
-      ss << "#{identifier_fragment} AS #{model.connection.quote_column_name("#{name}_identifier")}" if with_identifier
+      ss = ["#{label_fragment} AS #{label_fragment_alias}"]
+      ss << "#{identifier_fragment} AS #{identifier_fragment_alias}" if with_identifier && type == Dimension::TYPES[:standard]
       ss
     end
 
@@ -73,10 +83,8 @@ module ActiveReporting
     #
     # @return [Array]
     def group_by_statement(with_identifier: true)
-      return [degenerate_fragment] if type == Dimension::TYPES[:degenerate]
-
       group = [label_fragment]
-      group << identifier_fragment if with_identifier
+      group << identifier_fragment if with_identifier && type == Dimension::TYPES[:standard]
       group
     end
 
@@ -86,7 +94,6 @@ module ActiveReporting
     def order_by_statement(direction:)
       direction = direction.to_s.upcase
       raise "Ording direction should be 'asc' or 'desc'" unless %w[ASC DESC].include?(direction)
-      return "#{degenerate_fragment} #{direction}" if type == Dimension::TYPES[:degenerate]
       "#{label_fragment} #{direction}"
     end
 
@@ -101,14 +108,32 @@ module ActiveReporting
 
     def determine_label_field(label_field)
       @label = if label_field.present? && validate_hierarchical_label(label_field)
-                 label_field.to_sym
+                 type == Dimension::TYPES[:degenerate] ? name : label_field.to_sym
+               elsif type == Dimension::TYPES[:degenerate]
+                 name
                else
                  dimension_fact_model.dimension_label || Configuration.default_dimension_label
                end
     end
 
     def determine_label_name(label_name)
-      @label_name = label_name ? "#{name}_#{label_name}" : name
+
+      if label_name
+        @label_name = label_name
+      else
+        @label_name = name
+        @label_name += "_#{@label}" if (type == Dimension::TYPES[:standard] && @label != :name)
+        @label_name += "_#{@datetime_drill}" if @datetime_drill
+      end
+      @label_name
+    end
+
+    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
+      @datetime_drill = datetime_drill
     end
 
     def determine_join_method(join_method)
@@ -122,13 +147,8 @@ module ActiveReporting
     end
 
     def validate_hierarchical_label(hierarchical_label)
-      if datetime?
-        validate_supported_database_for_datetime_hierarchies
-        validate_against_datetime_hierarchies(hierarchical_label)
-      else
-        validate_dimension_is_hierachical(hierarchical_label)
-        validate_against_fact_model_properties(hierarchical_label)
-      end
+      validate_dimension_is_hierachical(hierarchical_label)
+      validate_against_fact_model_properties(hierarchical_label)
       true
     end
 
@@ -149,27 +169,75 @@ module ActiveReporting
       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"
+    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 degenerate_fragment
-      return "#{name}_#{@label}" if datetime?
-      "#{model.quoted_table_name}.#{name}"
+    def datetime_drill_label_fragment(column)
+      if model.connection.adapter_name == "Mysql2"
+        datetime_drill_mysql(column)
+      else # Postgress
+        datetime_drill_postgress(column)
+      end
     end
 
-    def degenerate_select_fragment
-      return "DATE_TRUNC('#{@label}', #{model.quoted_table_name}.#{name}) AS #{name}_#{@label}" if datetime?
-      "#{model.quoted_table_name}.#{name}"
+    def datetime_drill_postgress(column)
+      "DATE_TRUNC('#{@datetime_drill}', #{column})"
+    end
+
+    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"
+      end
     end
 
     def identifier_fragment
       "#{klass.quoted_table_name}.#{model.connection.quote_column_name(klass.primary_key)}"
     end
 
+    def identifier_fragment_alias
+      "#{model.connection.quote_column_name("#{name}_identifier")}"
+    end
+
     def label_fragment
-      "#{klass.quoted_table_name}.#{model.connection.quote_column_name(@label)}"
+      fragment = "#{klass.quoted_table_name}.#{model.connection.quote_column_name(@label)}"
+      fragment = datetime_drill_label_fragment(fragment) if @datetime_drill
+      fragment
+    end
+
+    def label_fragment_alias
+      "#{model.connection.quote_column_name(@label_name)}"
     end
 
     def dimension_fact_model

data/lib/active_reporting/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: active_reporting
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.6.0
 platform: ruby
 authors:
 - Tony Drake
-autorequire:
+autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-07-31 00:00:00.000000000 Z
+date: 2020-08-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -136,7 +136,7 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description:
+description: 
 email:
 - t27duck@gmail.com
 executables: []
@@ -170,7 +170,7 @@ homepage: https://github.com/t27duck/active_reporting
 licenses:
 - MIT
 metadata: {}
-post_install_message:
+post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -186,7 +186,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubygems_version: 3.0.3
-signing_key:
+signing_key: 
 specification_version: 4
 summary: Add relational OLAP-like functionality for ActiveRecord
 test_files: []