active_reporting 0.3.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: b787d85e5e44d1efda8c727cc6b289674bbebb35
-  data.tar.gz: 567f54e1ea4471e679f827c8819c220a1d7dca28
+SHA256:
+  metadata.gz: 07ad5ad6e21234d6441a8e97908cf854406d30e2a77b741096d0c874c85d5c42
+  data.tar.gz: 982a82ba6ab68d81dee8a1db785f25d993ac14b2572e698923437a4c1a37bd1e
 SHA512:
-  metadata.gz: a89a8bb2e06495ff3fb14f9f5b6356840c09298dcda898433d057b658481e73aedf362ec2b4ccba3b07f7a3878f69e4fdfdfa55521fa67c10c43232caaa0cc98
-  data.tar.gz: adfb3ea1b3de2e96ea2fb10dd178cea6a7f68d5a9761e938b9dd9f0eef8c43b54af3cb583f7bca0f6717b7fab6f769d714087dea281830bef95b1a98cd800130
+  metadata.gz: 0f7a37f152776e1d9fbc2440b71cb045464063f759c88cfff5d6dc0302ab8e9f6ea7aeed4c35375b5ad25861132dfb1ba4ebad57da6051ba75680beb309c3665
+  data.tar.gz: 0c07b8989e32d26ca39105630ffe74b83207425449d412f344461c194926e0efed64da367449898295de62a3618910f7a249e94ee91efe0290b3332d1b820319

data/.gitignore

@@ -6,5 +6,7 @@
 /doc/
 /pkg/
 /spec/reports/
+.byebug_history
+.ruby-version
 /tmp/
 .DS_STORE

data/.rubocop.yml

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

data/.travis.yml

@@ -1,18 +1,20 @@
 sudo: false
 language: ruby
+services:
+  - mysql
+addons:
+  postgresql: "9.6"
 rvm:
-  - 2.3.7
-  - 2.4.4
-  - 2.5.1
+  - 2.5.8
+  - 2.6.6
+  - 2.7.1
 env:
+  - RAILS=6-0 DB=sqlite
+  - RAILS=6-0 DB=pg
+  - RAILS=6-0 DB=mysql
   - RAILS=5-2 DB=sqlite
   - RAILS=5-2 DB=pg
-  - RAILS=5-1 DB=sqlite
-  - RAILS=5-1 DB=pg
-  - RAILS=5-1 DB=mysql
-  - RAILS=4-2 DB=sqlite
-  - RAILS=4-2 DB=pg
-  - RAILS=4-2 DB=mysql
+  - RAILS=5-2 DB=mysql
 before_script:
   - psql -c 'create database active_reporting_test;' -U postgres
   - mysql -e 'create database active_reporting_test collate utf8_general_ci;'

data/CHANGELOG.md

@@ -1,11 +1,62 @@
+## 0.5.1 (2020-06-31)
+
+### Features
+
+* Allow dimensions defined in a `Metric` to use LEFT OUTER JOINs via a new `:join_method` option (#32) - *germanotm*
+
+### Misc
+
+* Fixed warning about initialized variables
+* Fixed Ruby 2.7 warning
+
+## 0.5.0 (2020-06-30)
+
+### Bug Fixes
+
+* Fix Missing quotation marks in column names causing SQL errors on MYSQL (#30) - *germanotm*
+
+### Misc
+
+* Update matrix to only supported Rubies and Rails versions. Rails 5.2+ and Ruby 2.5+ are officially supported now.
+
+## 0.4.2 (2019-11-01)
+
+### Misc
+
+* Test against Rails 6.0 final
+* Fixed deprecated call to `to_hash` - *joshforbes*
+* Corrected readme entry for `dimesions` option for `ActiveReporting::Metric` - *joshforbes*
+
+## 0.4.1 (2019-05-28)
+
+### Features
+
+* Hierarchical dimensions may now have custom keys in result (#16) - *andresgutgon*
+
+### Misc
+
+* Test against Raisl 6.0RC
+* Loosen AR requirements. The gem will install for any AR version, but only ones listed in the README are supported
+* Test against active Rubies
+
+## 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
+### Misc
 
 * Test against Rails 5.2
 * Test against Ruby 2.5
@@ -20,11 +71,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/Gemfile

@@ -8,16 +8,8 @@ rails = ENV['RAILS'] || '5-2'
 db = ENV['DB'] || 'sqlite'
 
 case rails
-when '4-2'
-  gem 'activerecord', '~> 4.2.0'
-  if ENV['DB'] == 'pg'
-    gem 'pg', '~> 0.18'
-  end
-  if ENV['DB'] == 'mysql'
-    gem 'mysql2', '~> 0.3.18'
-  end
-when '5-1'
-  gem 'activerecord', '~> 5.1.0'
-else
+when '5-2'
   gem 'activerecord', '~> 5.2.0'
+when '6-0'
+  gem 'activerecord', '~> 6.0.0'
 end

data/README.md

@@ -8,9 +8,9 @@ ActiveReporting implements various terminology used in Relational Online Analyti
 
 ActiveReporting officially supports MySQL, PostgreSQL, and SQLite.
 
-ActiveReporting officially supports Ruby 2.3, 2.4, and 2.5.
+ActiveReporting officially supports Ruby 2.5 and later. Other versions may work, but are not supported.
 
-ActiveReporting officially supports Rails 4.2, 5.1, and 5.2.
+ActiveReporting officially supports Rails 5.2, and 6.0. Other versions may work, but are not supported.
 
 ## Installation
 
@@ -49,8 +49,8 @@ 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 orders
-* A state of an order on a state machine
+* 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
 
 SQL Equivalent: JOIN, GROUP BY
@@ -178,7 +178,7 @@ end
 ActiveReporting assumes the column of a fact model used for summing, averaging, etc. is called `value`. This may be changed on a fact model using `measure=`. You may pass in a string or symbol of the column you wish to use for aggregations.
 
 ```ruby
-class OrderFactModel < ActiveReporting::FactModel
+class SaleFactModel < ActiveReporting::FactModel
   self.measure = :total
 end
 ```
@@ -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.
@@ -255,8 +273,8 @@ A `Metric` is the basic building block used to describe a question you want to a
 
 ```ruby
 my_metric = ActiveReporting::Metric.new(
-  :order_total,
-  fact_model: OrderFactModel,
+  :sale_total,
+  fact_model: SaleFactModel,
   aggregate: :sum
 )
 ```
@@ -267,7 +285,7 @@ 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, {order_date: :month}]`)
+`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 }}]`
 
 `dimension_filter` - A hash were the keys are dimension filter names and the values are the values passed into the filter.
 
@@ -275,26 +293,40 @@ 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.
 
 ```ruby
 metric = ActiveReporting::Metric.new(
-  :order_count,
-  fact_model: OrderFactModel,
-  dimension: [:sales_rep],
+  :sale_count,
+  fact_model: SaleFactModel,
+  dimensions: [:sales_rep],
   dimension_filter: {months_ago: 1}
 )
 
 report = ActiveReporting::Report.new(metric)
 report.run
-=> [{order_count: 12, sales_rep: 'Fred Jones', sales_rep_identifier: 123},{order_count: 17, sales_rep: 'Mary Sue', sales_rep_identifier: 123}]
+=> [{sale_count: 12, sales_rep: 'Fred Jones', sales_rep_identifier: 123},{sale_count: 17, sales_rep: 'Mary Sue', sales_rep_identifier: 123}]
 ```
 
 A `Report` may also take additional arguments to merge with the `Metric`'s information. This can be user input for additional filters, or to expand on a base `Metric`.
 
-`dimension_identifiers` - When true, the result will include the database identifier columns of the dimensions. For example, when running a report for the total number of orders dimensioned by sales rep, the rep's IDs from the `sales_reps` table will be included. (Default `true`)
+`dimension_identifiers` - When true, the result will include the database identifier columns of the dimensions. For example, when running a report for the total number of sales dimensioned by sales rep, the rep's IDs from the `sales_reps` table will be included. (Default `true`)
 
 `dimension_filter` - A hash that will be merged with the `Metric`'s dimension filters.
 
@@ -304,15 +336,15 @@ A `Report` may also take additional arguments to merge with the `Metric`'s infor
 
 ```ruby
 metric = ActiveReporting::Metric.new(
-  :order_count,
-  fact_model: OrderFactModel,
-  dimension: [:sales_rep],
+  :sale_count,
+  fact_model: SaleFactModel,
+  dimensions: [:sales_rep],
   dimension_filter: {months_ago: 1}
 )
 
-report = ActiveReporting.new(metric, dimension_filter: {from_region: 'North'}, dimension_identifiers: false)
+report = ActiveReporting::Report.new(metric, dimension_filter: {from_region: 'North'}, dimension_identifiers: false)
 report.run
-=> [{order_count: 17, sales_rep: 'Mary Sue'}]
+=> [{sale_count: 17, sales_rep: 'Mary Sue'}]
 ```
 
 It may be more DRY to store ready-made metrics in a database table or stored in memory to use as the bases for various reports. You can pass a string or symbol into a `Report` instead of a `Metric` to look up an pre-made metric. This is done by passing the symbol or string into the `lookup` class method on the constant defined in `ActiveReporting::Configuration.metric_lookup_class`.
@@ -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_dependency 'activerecord'
+  spec.add_dependency 'activesupport'
 
   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'
   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'"
@@ -39,4 +41,5 @@ module ActiveReporting
   UnknownDimension        = Class.new(StandardError)
   UnknownDimensionFilter  = Class.new(StandardError)
   UnknownMetric           = Class.new(StandardError)
+  UnknownJoinMethod       = Class.new(StandardError)
 end

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
@@ -83,6 +85,7 @@ module ActiveReporting
     #
     # @return [Symbol]
     def self.dimension_label
+      @dimension_label ||= nil
       @dimension_label || Configuration.default_dimension_label
     end
 
@@ -109,7 +112,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 +146,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
 
@@ -151,6 +156,7 @@ module ActiveReporting
     #
     # @return [Boolean]
     def self.ransack_fallback
+      @ransack_fallback ||= false
       @ransack_fallback || Configuration.ransack_fallback
     end
     private_class_method :ransack_fallback

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
@@ -34,7 +36,7 @@ module ActiveReporting
     private ######################################################################
 
     def build_data
-      @data = model.connection.exec_query(statement.to_sql).to_hash
+      @data = model.connection.exec_query(statement.to_sql).to_a
       apply_dimension_callbacks
       @data
     end
@@ -50,7 +52,8 @@ module ActiveReporting
     def statement
       parts = {
         select: select_statement,
-        joins: dimension_joins,
+        joins: dimension_joins(ReportingDimension::JOIN_METHODS[:joins]),
+        left_outer_joins: dimension_joins(ReportingDimension::JOIN_METHODS[:left_outer_joins]),
         group: group_by_statement,
         having: having_statement,
         order: order_by_statement
@@ -82,8 +85,9 @@ module ActiveReporting
       end
     end
 
-    def dimension_joins
-      @dimensions.select { |d| d.type == :standard }.map { |d| d.name.to_sym }
+    def dimension_joins(join_method)
+      @dimensions.select { |d| d.type == Dimension::TYPES[:standard] && d.join_method == join_method }.
+                  map { |d| d.name.to_sym }
     end
 
     def group_by_statement

data/lib/active_reporting/reporting_dimension.rb

@@ -1,23 +1,54 @@
+# 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
+    JOIN_METHODS = { joins: :joins, left_outer_joins: :left_outer_joins }.freeze
+    attr_reader :join_method
+
+    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
-        new(found_dimension, label: label)
+
+        raise(UnknownDimension, "Dimension '#{dim}' not found on fact model '#{fact_model}'") if found_dimension.nil?
+
+        new(found_dimension, **label_config(label))
       end
     end
 
-    def initialize(dimension, label: nil)
+    # If you pass a symbol it means you just indicate
+    # 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)
+
+      {
+        label: label[:field],
+        label_name: label[:name],
+        join_method: label[:join_method]
+      }
+    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)
       @dimension = dimension
-      determine_label(label)
+
+      determine_label_field(label)
+      determine_label_name(label_name)
+      determine_join_method(join_method)
     end
 
     # The foreign key to use in queries
@@ -31,10 +62,10 @@ 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
+      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
     end
 
@@ -42,7 +73,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 +85,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
 
@@ -68,31 +99,77 @@ 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
+    def determine_label_field(label_field)
+      @label = if label_field.present? && validate_hierarchical_label(label_field)
+                 label_field.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}"
+    def determine_label_name(label_name)
+      @label_name = label_name ? "#{name}_#{label_name}" : name
+    end
+
+    def determine_join_method(join_method)
+      if join_method.blank?
+        @join_method = ReportingDimension::JOIN_METHODS[:joins]
+      elsif ReportingDimension::JOIN_METHODS.include?(join_method)
+        @join_method = join_method
+      else
+        raise UnknownJoinMethod, "Method '#{join_method}' not included in '#{ReportingDimension::JOIN_METHODS.values}'"
       end
-      unless dimension_fact_model.hierarchical_levels.include?(hierarchical_label.to_sym)
-        raise InvalidDimensionLabel, "#{hierarchical_label} is not a hierarchical label in #{name}"
+    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
       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
 
     def identifier_fragment
-      "#{klass.quoted_table_name}.#{klass.primary_key}"
+      "#{klass.quoted_table_name}.#{model.connection.quote_column_name(klass.primary_key)}"
     end
 
     def label_fragment
-      "#{klass.quoted_table_name}.#{@label}"
+      "#{klass.quoted_table_name}.#{model.connection.quote_column_name(@label)}"
     end
 
     def dimension_fact_model

data/lib/active_reporting/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: active_reporting
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.1
 platform: ruby
 authors:
 - Tony Drake
-autorequire: 
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2018-04-12 00:00:00.000000000 Z
+date: 2020-07-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -16,28 +16,28 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 4.2.0
+        version: '0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 4.2.0
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 4.2.0
+        version: '0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 4.2.0
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -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,7 +95,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: sqlite3
+  name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -109,7 +109,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '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:
     - - ">="
@@ -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
@@ -178,16 +178,15 @@ 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:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.6.14
-signing_key: 
+rubygems_version: 3.0.3
+signing_key:
 specification_version: 4
 summary: Add relational OLAP-like functionality for ActiveRecord
 test_files: []