active_reporting 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: fafbed6f29c91ec920f27d8d06b31658010a6508
-  data.tar.gz: 71eae395b135e2d471d6d991110ae424b742f51f
+  metadata.gz: 9e776c2130450c3db98c5518529079744a8e3f7e
+  data.tar.gz: 8284510c02504a70d78e3db21ba9697ac95bece6
 SHA512:
-  metadata.gz: de74521cced32429f624da2e9518d811ec200e2762c4484a968754ca99934b7c56680d93845ea761ecd3ae454c655e5ba133d35bc3905df1815f36720d00347a
-  data.tar.gz: adfa7a3fbd3fb2e4552d91b1be8b8ec864e9424484378001f68a7cc11aff5c15cff59e46138e5f9febd41695e497a9ad5841641a52999b6f3f864eefc23074ba
+  metadata.gz: ab8d651c7b980707ad6d4af9736c444c1c021f3a3f6d967e7f9eb8398270c17579c0b3dd35049e426225a0448924fa49edb77d4db9d10e8784786ae710e3b1e6
+  data.tar.gz: 9b488e5c85ce172cf06103a244faaf6150c34039750c670d235792539c970642110f15692cf24fc3e714ec4a394f4d8fc922560f5b6b9c27d789779c63a125b5

data/.codeclimate.yml

@@ -0,0 +1,15 @@
+engines:
+  duplication:
+    enabled: true
+    config:
+      languages:
+      - ruby
+  fixme:
+    enabled: true
+  rubocop:
+    enabled: true
+ratings:
+  paths:
+  - "**.rb"
+exclude_paths:
+- test/

data/.gitignore

@@ -7,3 +7,4 @@
 /pkg/
 /spec/reports/
 /tmp/
+.DS_STORE

data/.rubocop.yml

@@ -0,0 +1,25 @@
+AllCops:
+  Exclude:
+    - test/**/*
+  TargetRubyVersion: 2.2
+
+Metrics/LineLength:
+  Max: 120
+
+Metrics/ParameterLists:
+  Max: 8
+
+MethodLength:
+  Max: 20
+
+Style/ClassAndModuleChildren:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
+
+Style/PredicateName:
+  Enabled: false
+
+Style/RaiseArgs:
+  Enabled: false

data/.travis.yml

@@ -1,5 +1,16 @@
 sudo: false
 language: ruby
 rvm:
-  - 2.2.4
-before_install: gem install bundler -v 1.12.5
+  - 2.2.7
+  - 2.3.4
+  - 2.4.1
+gemfiles:
+  - gemfiles/4.2.gemfile
+  - gemfiles/5.0.gemfile
+matrix:
+  exclude:
+    - rvm: 2.2
+      gemfile: gemfiles/5.0.gemfile
+script:
+  - bundle exec rake
+

data/CHANGELOG.md

@@ -0,0 +1,3 @@
+## 0.1.0 (2017-04-16)
+
+* Initial release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,74 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at t27duck@gmail.com. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at [http://contributor-covenant.org/version/1/4][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/4/

data/Gemfile

@@ -1,4 +1,6 @@
 source 'https://rubygems.org'
 
+gem 'simplecov', require: false
+
 # Specify your gem's dependencies in active_reporting.gemspec
 gemspec

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2016 Tony Drake
+Copyright (c) 2017 Tony Drake
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,8 +1,12 @@
+[![Build Status](https://travis-ci.org/t27duck/active_reporting.svg?branch=master)](https://travis-ci.org/t27duck/active_reporting)
+
+[![Code Climate](https://codeclimate.com/github/t27duck/active_reporting/badges/gpa.svg)](https://codeclimate.com/github/t27duck/active_reporting)
+
 # ActiveReporting
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/active_reporting`. To experiment with that code, run `bin/console` for an interactive prompt.
+ActiveReporting implements various terminology used in Relational Online Analytical Processing (Commonly referred to as ROLAP) with ActiveRecord. It provides a DSL to describe reports and analytics on your data.
 
-TODO: Delete this and the text above, and describe your gem
+ActiveReporting officially supports MySQL, PostgreSQL, and SQLite.
 
 ## Installation
 
@@ -20,9 +24,301 @@ Or install it yourself as:
 
     $ gem install active_reporting
 
-## Usage
+## What is "Reporting"?
+
+Reporting is the collection and presentation data so that it can be analyzed. Our databases only store one thing: data. Data is great for computers but mostly worthless to humans. What ActiveReoprting does is turn that *data* into *information* to help humans make decisions.
+
+## Terminology
+
+ROLAP uses a set of terms to describe how a report is generated. ActiveReporting implements them in the closest way possible in Ruby-land.
+
+### Fact table (can be sometimes called fact model)
+
+A fact table is the primary table where information is derived from in a report. It commonly contains fact columns (usually numeric values) and dimension columns (foreign keys to other tables or values that can be grouped together).
+
+SQL Equivalent: FROM
+Rails: ActiveRecord model
+
+### Dimension
+
+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
+* The manufacture on a fact table of widgets
+
+SQL Equivalent: JOIN, GROUP BY
+Rails: ActiveRecord relation or attribute
+
+### Dimension Hierarchy
+
+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
+
+### Dimension Member (also known as dimension labels)
+
+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")
+
+This isn't really an official term, but I like using it to describe further filtering of dimensionable data.
+
+SQL Equivalent: WHERE
+Rails: `where()`, scopes, etc.
+
+### Measure
+
+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
+
+SQL Equivalent: Column in the fact table used in an aggregation function
+Rails: ActiveRecord attribute
+
+### Metric
+
+A metric is a measured value and the subject of the report. It is the result of *the* question you want answered.
+
+SQL Equivalent: A query result
+Rails: The result of an ActiveRecord query
+
+### Star Schema
+
+Star schema is a way of structuring your relational data. It is one of the most common forms of organization for relational data warehousing. The layout of a star schema consists of a fact table referencing one or more dimension tables. When laid out in an entity relationship diagram, it resembles a star.
+
+[TODO: ADD PICTURE HERE]
+
+More information: https://en.wikipedia.org/wiki/Star_schema
+
+### Snowflake Schema
+
+Snowflake schema is a super class of star schema. A fact table still resides in the middle of the diagram, but dimension tables are normalized out into multiple tables resulting in the resemblance of a snowflake.
+
+[TODO: ADD PICTURE HERE]
+
+More information: https://en.wikipedia.org/wiki/Snowflake_schema
+
+ActiveReporting is built with star schema in mind, but will work with snowflake.
+
+## Configuration
+
+Configure ActiveReporting via block configuration or by setting individual settings:
+
+```ruby
+ActiveReporting::Configuration.config do |c|
+  c.setting = value
+end
+```
+
+```ruby
+ActiveReporting::Configuration.setting = value
+```
+
+### Configuration Options
+
+`default_dimension_label` - If a fact model does not have a default label set for when it's used as a dimension, this value will be used. (Default: `:name`)
+
+`default_measure` - If a fact model does not specify a measure to use for aggregates, this value will be used. (Default: `:value`)
+
+`ransack_fallback` - If the ransack gem is loaded, allow all unknown dimension filters to be delegated to ransack. (Default: `false`)
+
+`metric_lookup_class` - The name of a constant used to lookup prebuilt `Reporting::Metric` objects by name. The constant should define a class method called `#lookup` which can take a string or symbol of the metric name. (Default: `::Metric`)
+
+
+## ActiveReporting::FactModel
+
+In ActiveReporting, a fact model stores configuration information on how it can be used in reports. We use the term fact model instead of fact table because this class "models how the fact table interacts with dimensions and other reporting features".
+
+You can put these classes anywhere you want in your app, though I recommend putting them in `app/fact_models`
+
+### Linking a fact model to an ActiveRecord model
+
+Every fact model links to an ActiveRecord model. This is done either by naming convention or by explicitly declaring the model.
+
+This naming convention is `[ModelName]FactModel`. Meaning if you have an ActiveRecord model named `Ticket`, you'll then have a `TicketFactModel` to link them together.
+
+```ruby
+class TicketFactModel < ActiveRecord::FactModel
+
+end
+```
+
+Alternatively, you may manually specify the model manually with `use_model`
+
+```ruby
+class TicketFactModel < ActiveRecord::FactModel
+  use_model SomeOtherModel
+  # OR you may pass in a string or symbol
+  # use_model :some_other_model
+  # use_model 'some_other_model'
+  # use_model 'SomeOtherModel'
+end
+```
+
+### Configuring a fact model's measure
+
+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.
 
-TODO: Write usage instructions here
+```ruby
+class OrderFactModel < ActiveReporting::FactModel
+  measure = :total
+end
+```
+
+## Configuring Dimensions
+
+### Declaring dimensions on a fact model
+
+You must declare what a fact model is dimensional by. A valid dimension is a column on the fact model's ActiveRecord model or a `belongs_to`/`has_one through` relationship. `has_many` relationships do not work (well) at all.
+
+```ruby
+class TicketFactModel < ActiveReporting::FactModel
+  dimension :creator # belongs_to relationship
+  dimension :assignee # belongs_to relationship
+  dimension :category # Column on the tickets table
+end
+```
+
+### When a fact model is used as a dimension
+
+When another fact model uses a relationship as a dimension, that ActiveRecord model's fact model class can hold configuration information for how to act when used as a dimension.
+
+By default, it is assumed a dimension's label is a column called `name`. This can be changed on the fact model.
+
+```ruby
+class UserFactModel < ActiveReporting::FactModel
+  default_dimension_label :username
+end
+```
+
+### Dimension Hierarchies
+
+For dimensions that can have a hierarchy (such as a mobile phone), you can declare the what columns make it up. This will allow reports to dimension against a fact model and be able to use different labels to group by.
+
+```ruby
+class PhoneFactModel < ActiveReporting::FactModel
+  dimension_hierarchy [:model_name, :manufacturer, :os, :wireless_technology]
+end
+```
+
+## Configuring Dimension Filters
+
+A dimension filter provides filtering for a report. In SQL-land, this is the `WHERE` clause.
+
+Available dimension filters are defined on a `FactModel`. They can be implemented via a similar syntax to a Rails scope, link to the fact model's ActiveRecord model's scope, or delegate to ransack.
+
+```ruby
+class TicketFactModel < ActiveReporting::FactModel
+  dimension_filter :open
+  dimension_filter :for_category_name, ->(x) { joins(:category).where(categories: {name: x}) }
+  dimension_filter :subject_cont, :ransack
+end
+```
+
+The first example exposes the `Ticket.open` scope to the fact model allowing it to be used as a dimension filter.
+
+The second example defines a lambda to be invoked like a Rails scope. It joins against the `category` relationship on `Ticket` and filters by the category's name.
+
+The third example defines a filter called "subject_cont" and will delegate it to ransack when called.
+
+Only dimension filters defined in the fact model may be used. Whitelisting available filters allows for more control over what the user may filter by. Giving the user full control to call any scope or method from the ActiveRecord model could lead to unexpected results, poor performing queries, or possible security concerns.
+
+If ransack is available, you may flag a fact model to delegate all unknown dimension filters to ransack.
+
+```ruby
+class TicketFactModel < ActiveReporting::FactModel
+  use_ransack_for_unknown_dimension_filters
+end
+```
+
+## ActiveReporting::Metric
+
+A `Metric` is the basic building block used to describe a question you want to answer. At minimum, a metric needs a name, a fact table and an aggregate. You can expand a metric further by including dimensions and dimension filters.
+
+```ruby
+my_metric = ActiveReporting::Metric.new(
+  :order_total,
+  fact_model: OrderFactModel,
+  aggregate: :sum
+)
+```
+
+`name` - This is the identifying name of the metric.
+
+`fact_model` - An `ActiveReporting::FactModel` class
+
+`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}]`)
+
+`dimension_filter` - A hash were the keys are dimension filter names and the values are the values passed into the filter.
+
+`metric_filter` - An additional HAVING clause to be tacked on to the end of the query. This allows for the further filtering of the end results based on the value of the aggregate. (Examples: `{gt: 3}`, `{eq: 5}`, `{lte: 7}`)
+
+`order_by_dimension` - Allows you to set the ordering of the results based on a dimension label. (Examples: `{author: :desc}`, `{sales_ref: :asc}`)
+
+## 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],
+  dimension_filter: {months_ago: 1}
+)
+
+report = ActiveReporting.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}]
+```
+
+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_filter` - A hash that will be merged with the `Metric`'s dimension filters.
+
+`dimensions` - An array of additional dimensions which are merged with the `Metric`'s dimensions.
+
+`metric_filter` - Sets the HAVING clause of the final query and is merged with the `Metric`'s metric filter.
+
+```ruby
+metric = ActiveReporting::Metric.new(
+  :order_count,
+  fact_model: OrderFactModel,
+  dimension: [:sales_rep],
+  dimension_filter: {months_ago: 1}
+)
+
+report = ActiveReporting.new(metric, dimension_filter: {from_region: 'North'}, dimension_identifiers: false)
+report.run
+=> [{order_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`.
+
+```ruby
+class StoredMetrics
+  def lookup(metric_name)
+    # Code to construct and return an `ActiveReporting::Metric` object
+  end
+end
+
+ActiveReporting::Configuration.metric_lookup_class = StoredMetrics
+
+report = ActiveReporting::Report.new(:a_stored_metric, ...)
+```
 
 ## Development
 
@@ -32,7 +328,7 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/active_reporting.
+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