active_reporting 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b787d85e5e44d1efda8c727cc6b289674bbebb35
-  data.tar.gz: 567f54e1ea4471e679f827c8819c220a1d7dca28
+  metadata.gz: 7a5444ba19be4d20842e16f8e800e45837e133bd
+  data.tar.gz: 24b59685e4cd70770a13a8a2925c85d860e782a3
 SHA512:
-  metadata.gz: a89a8bb2e06495ff3fb14f9f5b6356840c09298dcda898433d057b658481e73aedf362ec2b4ccba3b07f7a3878f69e4fdfdfa55521fa67c10c43232caaa0cc98
-  data.tar.gz: adfb3ea1b3de2e96ea2fb10dd178cea6a7f68d5a9761e938b9dd9f0eef8c43b54af3cb583f7bca0f6717b7fab6f769d714087dea281830bef95b1a98cd800130
+  metadata.gz: 1df566a6122ec806f231a116ffe33cf729374fe529ddf18a2763cb2462946414c60bada55a06e7fc036ef3c4fc0002f021d06b1147cb011c7810ce1b517cd82e
+  data.tar.gz: 0ec9387af8a5918f3685732b4331377302e373ae56843305991d2c8abc24928c4a19ea79ed7d3bd6b5e979204c2a15cde3806df62a282a8714ac0d6a439fb4e6

data/.rubocop.yml

@@ -1,7 +1,8 @@
 AllCops:
   Exclude:
     - test/**/*
-  TargetRubyVersion: 2.2
+    - Gemfile
+  TargetRubyVersion: 2.3
 
 Metrics/LineLength:
   Max: 120
@@ -18,7 +19,7 @@ Style/ClassAndModuleChildren:
 Style/Documentation:
   Enabled: false
 
-Style/PredicateName:
+Style/Name:
   Enabled: false
 
 Style/RaiseArgs:

data/.travis.yml

@@ -7,6 +7,7 @@ rvm:
 env:
   - RAILS=5-2 DB=sqlite
   - RAILS=5-2 DB=pg
+  - RAILS=5-2 DB=mysql
   - RAILS=5-1 DB=sqlite
   - RAILS=5-1 DB=pg
   - RAILS=5-1 DB=mysql

data/CHANGELOG.md

@@ -1,9 +1,19 @@
+## 0.4.0 (2018-05-02)
+
+### Breaking Changes
+
+* Gemspec now requires Ruby 2.3 and later to install
+
+### Features
+
+* Dimension off of `datetime` columns by date parts in PostgreSQL (See README for details) (#10) - *niborg*
+
 ## 0.3.0 (2018-04-12)
 
 ### Bug Fixes
 
-* Specify rescue from LoadError for ransack (#9) *niborg*
-* Fix ransack fallback logic *germanotm*
+* Specify rescue from LoadError for ransack (#9) - *niborg*
+* Fix ransack fallback logic (#8) - *germanotm*
 
 ## Misc
 
@@ -20,11 +30,11 @@
 
 ### Bug Fixes
 
-* `metric` lives on fact model and not metric (#3) - *Michael Wheeler (wheeyls)*
+* `metric` lives on fact model and not metric (#3) - *wheeyls*
 
 ### Misc
 
-* Readme corrections and updates (#2) - *Michael Wheeler (wheeyls)*
+* Readme corrections and updates (#2) - *wheeyls*
 
 ## 0.1.1 (2017-04-22)
 

data/README.md

@@ -219,6 +219,24 @@ class PhoneFactModel < ActiveReporting::FactModel
 end
 ```
 
+### Implicit hierarchies with datetime columns (PostgreSQL support only)
+
+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.
+
+To use, declare a datetime dimension on a fact model as normal:
+
+```ruby
+class UserFactModel < ActiveReporting::FactModel
+  dimension :created_at
+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.)
+
+*NOTE*: PRs welcomed to support this functionality in other databases.
+
 ## Configuring Dimension Filters
 
 A dimension filter provides filtering for a report. In SQL-land, this is the `WHERE` clause.
@@ -275,6 +293,20 @@ my_metric = ActiveReporting::Metric.new(
 
 `order_by_dimension` - Allows you to set the ordering of the results based on a dimension label. (Examples: `{author: :desc}`, `{sales_ref: :asc}`)
 
+For those using Postgres, you can take advantage of implicit hierarchies in `datetime` columns, as mentioned above:
+
+```ruby
+class UserFactModel < ActiveReporting::FactModel
+  dimension :created_at
+end
+
+my_metric = ActiveReporting::Metric.new(
+  :my_total,
+  fact_model: UserFactModel,
+  dimensions: [{ created_at: :quarter } ]
+)
+```
+
 ## ActiveReporting::Report
 
 A `Report` takes an `ActiveReporting::Metric` and ties everything together. It is responsible for building and executing the query to generate a result. The result is an simple array of hashing.
@@ -283,7 +315,7 @@ A `Report` takes an `ActiveReporting::Metric` and ties everything together. It i
 metric = ActiveReporting::Metric.new(
   :order_count,
   fact_model: OrderFactModel,
-  dimension: [:sales_rep],
+  dimensions: [:sales_rep],
   dimension_filter: {months_ago: 1}
 )
 
@@ -306,7 +338,7 @@ A `Report` may also take additional arguments to merge with the `Metric`'s infor
 metric = ActiveReporting::Metric.new(
   :order_count,
   fact_model: OrderFactModel,
-  dimension: [:sales_rep],
+  dimensions: [:sales_rep],
   dimension_filter: {months_ago: 1}
 )
 
@@ -335,6 +367,11 @@ After checking out the repo, run `bin/setup` to install dependencies. Then, run
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
+## Testing
+
+You can run the test suite using `rake test`. To test against a particular database, you'll need to set the
+appropriate `DB` environment variable, e.g. `DB=pg rake test`.
+
 ## Contributing
 
 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.
@@ -343,4 +380,3 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/[USERN
 ## License
 
 The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
-

data/Rakefile

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'bundler/gem_tasks'
 require 'rake/testtask'
 

data/active_reporting.gemspec

@@ -1,5 +1,6 @@
-# coding: utf-8
-lib = File.expand_path('../lib', __FILE__)
+# frozen_string_literal: true
+
+lib = File.expand_path('lib', __dir__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'active_reporting/version'
 
@@ -21,16 +22,16 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
-  spec.required_ruby_version = '>= 2.2'
+  spec.required_ruby_version = '>= 2.3'
 
   spec.add_dependency 'activerecord', '>= 4.2.0'
   spec.add_dependency 'activesupport', '>= 4.2.0'
 
   spec.add_development_dependency 'bundler'
-  spec.add_development_dependency 'rake', '~> 10.0'
   spec.add_development_dependency 'minitest', '~> 5.0'
+  spec.add_development_dependency 'mysql2'
+  spec.add_development_dependency 'pg'
+  spec.add_development_dependency 'rake', '~> 10.0'
   spec.add_development_dependency 'ransack'
   spec.add_development_dependency 'sqlite3'
-  spec.add_development_dependency 'pg'
-  spec.add_development_dependency 'mysql2'
 end

data/bin/console

@@ -1,4 +1,5 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
 require 'bundler/setup'
 require 'active_reporting'

data/lib/active_reporting.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'active_record'
 require 'active_reporting/active_record_adaptor'
 require 'active_reporting/configuration'
@@ -23,8 +25,8 @@ module ActiveReporting
     klass = Configuration.metric_lookup_class
     unless defined?(klass.constantize)
       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} 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'"

data/lib/active_reporting/active_record_adaptor.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module ActiveReporting
   # This is included into every class that inherits from ActiveRecord::Base
   module ActiveRecordAdaptor
@@ -13,7 +15,7 @@ module ActiveReporting
                         const_name.constantize
                       rescue NameError
                         const = Object.const_set(const_name, Class.new(ActiveReporting::FactModel))
-                        const.model= self
+                        const.model = self
                         const
                       end
     end

data/lib/active_reporting/configuration.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module ActiveReporting
   module Configuration
     class << self

data/lib/active_reporting/dimension.rb

@@ -1,5 +1,8 @@
+# frozen_string_literal: true
+
 module ActiveReporting
   class Dimension
+    TYPES = { degenerate: :degenerate, standard: :standard }.freeze
     attr_reader :name
 
     # @param model [ActiveRecord::Base]
@@ -19,14 +22,21 @@ module ActiveReporting
     # @return [Symbol]
     def type
       @type ||= if model.column_names.include?(@name)
-                  :degenerate
+                  TYPES[:degenerate]
                 elsif association
-                  :standard
+                  TYPES[:standard]
                 else
                   raise UnknownDimension, "Dimension '#{@name}' not found on fact model '#{@fact_model}'"
                 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]
@@ -53,7 +63,7 @@ module ActiveReporting
     #
     # @return [ActiveRecord::Reflection]
     def association
-      @association_info ||= model.reflect_on_association(@name)
+      @association ||= model.reflect_on_association(@name)
     end
   end
 end

data/lib/active_reporting/dimension_filter.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module ActiveReporting
   class DimensionFilter
     attr_reader :name, :type, :body

data/lib/active_reporting/fact_model.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module ActiveReporting
   class FactModel
     class << self
@@ -109,7 +111,7 @@ module ActiveReporting
     # @param body [Lambda]
     def self.dimension_label_callback(column, body)
       @dimension_label_callbacks ||= {}
-      raise ArgumentError, "Dimension label callback body must be a callable object" unless body.respond_to?(:call)
+      raise ArgumentError, 'Dimension label callback body must be a callable object' unless body.respond_to?(:call)
       @dimension_label_callbacks[column.to_sym] = body
     end
 
@@ -143,7 +145,9 @@ module ActiveReporting
     # Invoke this method to make all dimension filters fallback to use ransack
     # if they are not defined as scopes on the model
     def self.use_ransack_for_unknown_dimension_filters
-      raise RansackNotAvailable, 'Ransack not available. Please include it in your Gemfile.' unless Configuration.ransack_available
+      unless Configuration.ransack_available
+        raise RansackNotAvailable, 'Ransack not available. Please include it in your Gemfile.'
+      end
       @ransack_fallback = true
     end
 

data/lib/active_reporting/metric.rb

@@ -1,6 +1,8 @@
+# frozen_string_literal: true
+
 require 'forwardable'
 module ActiveReporting
-  AGGREGATES = %i(count sum max min avg).freeze
+  AGGREGATES = %i[count sum max min avg].freeze
 
   class Metric
     extend Forwardable

data/lib/active_reporting/report.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'forwardable'
 module ActiveReporting
   class Report

data/lib/active_reporting/reporting_dimension.rb

@@ -1,20 +1,27 @@
+# frozen_string_literal: true
+
 require 'forwardable'
 module ActiveReporting
   class ReportingDimension
     extend Forwardable
-    def_delegators :@dimension, :name, :type, :klass, :association, :model, :hierarchical?
+    SUPPORTED_DBS = %w[PostgreSQL PostGIS].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
+    def_delegators :@dimension, :name, :type, :klass, :association, :model, :hierarchical?, :datetime?
 
     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]
         found_dimension = fact_model.dimensions[dimension_name.to_sym]
-        if found_dimension.nil?
-          raise UnknownDimension, "Dimension '#{dim}' not found on fact model '#{fact_model}'"
-        end
+        raise UnknownDimension, "Dimension '#{dim}' not found on fact model '#{fact_model}'" if found_dimension.nil?
         new(found_dimension, label: label)
       end
     end
 
+    # @param dimension [ActiveReporting::Dimension]
+    # @option label [Symbol] Hierarchical dimension to be used as a label
     def initialize(dimension, label: nil)
       @dimension = dimension
       determine_label(label)
@@ -31,7 +38,7 @@ module ActiveReporting
     #
     # @return [Array]
     def select_statement(with_identifier: true)
-      return [degenerate_fragment] if type == :degenerate
+      return [degenerate_select_fragment] if type == Dimension::TYPES[:degenerate]
 
       ss = ["#{label_fragment} AS #{name}"]
       ss << "#{identifier_fragment} AS #{name}_identifier" if with_identifier
@@ -42,7 +49,7 @@ module ActiveReporting
     #
     # @return [Array]
     def group_by_statement(with_identifier: true)
-      return [degenerate_fragment] if type == :degenerate
+      return [degenerate_fragment] if type == Dimension::TYPES[:degenerate]
 
       group = [label_fragment]
       group << identifier_fragment if with_identifier
@@ -54,8 +61,8 @@ 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)
-      return "#{degenerate_fragment} #{direction}" if type == :degenerate
+      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
 
@@ -69,21 +76,53 @@ module ActiveReporting
     private ####################################################################
 
     def determine_label(label)
-      @label = label.to_sym if label.present? && validate_hierarchical_label(label)
-      @label ||= dimension_fact_model.dimension_label || Configuration.default_dimension_label
+      @label = if label.present? && validate_hierarchical_label(label)
+                 label.to_sym
+               else
+                 dimension_fact_model.dimension_label || Configuration.default_dimension_label
+               end
     end
 
     def validate_hierarchical_label(hierarchical_label)
-      if !hierarchical?
-        raise InvalidDimensionLabel, "#{name} must be hierarchical to use label #{hierarchical_label}"
-      end
-      unless dimension_fact_model.hierarchical_levels.include?(hierarchical_label.to_sym)
-        raise InvalidDimensionLabel, "#{hierarchical_label} is not a hierarchical label in #{name}"
+      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
       true
     end
 
+    def validate_dimension_is_hierachical(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)
+      raise InvalidDimensionLabel,
+            "Cannot utilize datetime grouping for #{name}; " \
+            "database #{model.connection.adapter_name} is not supported"
+    end
+
+    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_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}"
+    end
+
+    def degenerate_select_fragment
+      return "DATE_TRUNC('#{@label}', #{model.quoted_table_name}.#{name}) AS #{name}_#{@label}" if datetime?
       "#{model.quoted_table_name}.#{name}"
     end
 

data/lib/active_reporting/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module ActiveReporting
-  VERSION = '0.3.0'.freeze
+  VERSION = '0.4.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: active_reporting
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Tony Drake
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-04-12 00:00:00.000000000 Z
+date: 2018-05-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -53,35 +53,35 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: rake
+  name: minitest
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '5.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '5.0'
 - !ruby/object:Gem::Dependency
-  name: minitest
+  name: mysql2
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '5.0'
+        version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '5.0'
+        version: '0'
 - !ruby/object:Gem::Dependency
-  name: ransack
+  name: pg
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -95,21 +95,21 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: sqlite3
+  name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '10.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '10.0'
 - !ruby/object:Gem::Dependency
-  name: pg
+  name: ransack
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -123,7 +123,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: mysql2
+  name: sqlite3
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -178,7 +178,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.2'
+      version: '2.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="