query_police 0.1.4.beta → 0.1.5.beta

data/README.md

@@ -1,16 +1,16 @@
 # QueryPolice
 
-It is a rule-based engine with custom rules to Analyze Active-Record relations using explain results to detect bad queries.
+It is a rule-based engine with custom rules to Analyze Active-Record relations using explain results and detect bad queries.
 
 ## Installation
 
 Install the gem and add it to the application's Gemfile by executing:
 
-    $ bundle add query_police
+    $ gem 'query_police', '~> 0.1.5.beta'
 
 If the bundler is not being used to manage dependencies, install the gem by executing:
 
-    $ gem install query_police
+    $ gem install query_police --pre
 
 ---
 
@@ -20,320 +20,318 @@ If the bundler is not being used to manage dependencies, install the gem by exec
 
 Use `QueryPolice.analyse` to generate an analysis object for your Active-Record relation or query and then you can use pretty print on the object.
 
-```
-analysis = QueryPolice.analyse(<active_record_relation>)
-puts analysis.pretty_analysis_for(<impact>)
+```ruby
+analysis = QueryPolice.analyse(<query>)
+puts analysis.pretty_analysis
 ```
 
 **Eg.** 
-```
+```ruby
 analysis = QueryPolice.analyse(
-  User.joins('join orders on orders.user_id = users.id')
+  User.joins('join orders on orders.user_id = users.id') # analyse query using active record relation
 )
-puts analysis.pretty_analysis_for('negative')
 # or
-puts analysis.pretty_analysis({'negative' => true, 'positive' => true})
+analysis = QueryPolice.analyse(
+  "select * from users join orders on orders.user_id = users.id" # analyse query using query string
+)
+
+puts analysis.pretty_analysis
 ```
 **Results**
 
+**Note:** [Query debt significance](#significance)  
+
+
 ```
-query_score: 330.0
+query_debt: 330.0
 
 +----------------------------------------------------------------------------------------------------------------------------------+
 |                                                              orders                                                              |
 +------------+---------------------------------------------------------------------------------------------------------------------+
-| score      | 200.0                                                                                                               |
+| debt      | 200.0                                                                                                               |
 +------------+---------------------------------------------------------------------------------------------------------------------+
 | column     | type                                                                                                                |
 | impact     | negative                                                                                                            |
-| tag_score  | 100.0                                                                                                               |
+| tag_debt  | 100.0                                                                                                               |
 | message    | Entire orders table is scanned to find matching rows, you have 0 possible keys to use.                              |
 | suggestion | Use index here. You can use index from possible key: absent or add new one to orders table as per the requirements. |
 +------------+---------------------------------------------------------------------------------------------------------------------+
 | column     | possible_keys                                                                                                       |
 | impact     | negative                                                                                                            |
-| tag_score  | 50.0                                                                                                                |
+| tag_debt  | 50.0                                                                                                                |
 | message    | There are no possible keys for orders table to be used, can result into full scan                                   |
 | suggestion | Please add index keys for orders table                                                                              |
 +------------+---------------------------------------------------------------------------------------------------------------------+
 | column     | key                                                                                                                 |
 | impact     | negative                                                                                                            |
-| tag_score  | 50.0                                                                                                                |
+| tag_debt  | 50.0                                                                                                                |
 | message    | There is no index key used for orders table, and can result into full scan of the orders table                      |
 | suggestion | Please use index from possible_keys: absent or add new one to orders table as per the requirements.                 |
 +------------+---------------------------------------------------------------------------------------------------------------------+
 +------------------------------------------------------------------------------------+
 |                                       users                                        |
 +------------+-----------------------------------------------------------------------+
-| score      | 130.0                                                                 |
+| debt      | 130.0                                                                 |
 +------------+-----------------------------------------------------------------------+
 | column     | detailed#used_columns                                                 |
 | impact     | negative                                                              |
-| tag_score  | 130.0                                                                 |
+| tag_debt  | 130.0                                                                 |
 | message    | You have selected 18 columns, You should not select too many columns. |
 | suggestion | Please only select required columns.                                  |
 +------------+-----------------------------------------------------------------------+
 ```
 
-### Add a logger for every query
-
-Add `QueryPolice.subscribe_logger` to your initial load file like `application.rb`
-
-You can make logger silence of error using `QueryPolice.subscribe_logger silent: true`.
-
-You can change logger config using `QueryPolice logger_config: <config>`, default logger_config `{'negative' => true}`, options `positive: <Boolean>, caution: <Boolean>`.
-
----
+###  Analysis for a Impact 
 
-## How it works?
+To print pretty analysis for different impacts
+```ruby
+analysis = QueryPolice.analyse("select * from users")
+puts analysis.pretty_analysis_for('positive') # impact negative, positive, caution
 
-1. Query police converts the relation into SQL query
-
-2. Query police generates an execution plan using EXPLAIN and EXPLAIN format=JSON based on the configuration.
-
-3. Query police load rules from the config file.
-
-4. Query police apply rules on the execution plan and generate a new analysis object.
-
-5. Analysis object provides different methods to print the analysis in a more descriptive format.
-
-
-## Execution plan
-
-We have 2 possible execution plans:-
-
-Normal - using `EXPLAIN`
-
-Detailed - using `EXPLAIN format=JSON`
-
-**NOTE:** By default Detailed execution plan is added in the final execution plan, you can remove that by `QueryPolice.detailed=false`
-
-### Normal execution plan
-
-Generated using `EXPAIN <query>`
-
-**Result**
-
-| id | select_type | table   | partitions | type.  | possible_keys             | key                 | key_len | ref                         | rows | filtered | Extra                    |
-|----|-------------|---------|------------|--------|---------------------------|---------------------|---------|-----------------------------|------|----------|--------------------------|
-|  1 | SIMPLE      | profile | NULL.      | index  | fk_rails_249a7ebca1       | fk_rails_249a7ebca1 | 5       | NULL                        |  603 |  100.00  | Using where; Using index |
-|  1 | SIMPLE      | users   | NULL       | eq_ref | PRIMARY,index_users_on_id | PRIMARY             | 4       | development.profile.user_id |1     |  100.00  | NULL                     |
-
-
-The result for this is added as it is in the final execution plan
+# puts
+# +----------------------------------------------------------+         
+# |                          users                           |         
+# +-----------+----------------------------------------------+         
+# | debt     | 330.0                                        |         
+# +-----------+----------------------------------------------+         
+# | column    | select_type                                  |
+# | impact    | positive                                     |
+# | tag_debt | 0                                            |
+# | message   | A simple query without subqueries or unions. |
+# +-----------+----------------------------------------------+
+```
 
-**Eg.**
+### Analysis for Multiple Impacts
 
+To print pretty analysis for multiple impacts, default: `{ 'negative' => true, 'caution' => true }`
+```ruby
+analysis = QueryPolice.analyse("select * from users")
+puts analysis.pretty_analysis({'negative' => true, 'positive' => true})
 ```
-{
-    "profile" => {
-                   "id" => 1,
-          "select_type" => "SIMPLE",
-                "table" => "profile",
-           "partitions" => nil,
-                 "type" => "index",
-        "possible_keys" => "fk_rails_249a7ebca1",
-                  "key" => "fk_rails_249a7ebca1",
-              "key_len" => "5",
-                  "ref" => nil,
-                 "rows" => 603,
-             "filtered" => 100.0,
-                "Extra" => "Using where; Using index"
-    },
-                  "users" => {
-                   "id" => 1,
-          "select_type" => "SIMPLE",
-                "table" => "users",
-           "partitions" => nil,
-                 "type" => "eq_ref",
-        "possible_keys" => "PRIMARY,index_users_on_id",
-                  "key" => "PRIMARY",
-              "key_len" => "4",
-                  "ref" => "development.profile.user_id",
-                 "rows" => 1,
-             "filtered" => 100.0,
-                "Extra" => nil
-    }
-}
-```
-
-### Detailed execution plan
 
-Generated using `EXPAIN format=JSON <query>`
+### Query debt
 
-**Truncated Result**
+To get the final debt of the query
+```ruby
+analysis = QueryPolice.analyse("select * from users")
+puts analysis.query_debt
 
+# puts
+# 100.0
 ```
-{
-  "query_block": {
-    "select_id": 1,
-    "cost_info": {
-      "query_cost": "850.20"
-    },
-    "nested_loop": [
-      {
-        "table": {
-          "table_name": "profile",
-          "access_type": "index",
-          "key_length": "5",
-          "cost_info": {
-            "read_cost": "6.00",
-            "eval_cost": "120.60",
-            "prefix_cost": "126.60",
-            "data_read_per_join": "183K"
-          },
-          "used_columns": [
-            "user_id"
-          ],
-          "attached_condition": "(`development`.`profile`.`user_id` is not null)"
-        }
-      }
-    ]
-  }
-}
-```
-
 
-The result for this is added in the flattened form to the final execution plan, where the `detailed#` prefix is added before each key.
+#### Significance
+Query debt signifies the quality of the query, high value represents a bad query. 
+- `0 - 199` - Good Query
+- `200 - 499` - Potentially Bad query
+- `>=500` - Bad query
 
-**Truncated Eg.**
+### Word wrap
 
-```
-{
-    "detailed#key_length" => "5",
-    "detailed#rows_examined_per_scan" => 603,
-    "detailed#rows_produced_per_join" => 603,
-    "detailed#filtered" => "100.00",
-    "detailed#using_index" => true,
-    "detailed#cost_info#read_cost" => "6.00",
-    "detailed#cost_info#eval_cost" => "120.60",
-    "detailed#cost_info#prefix_cost" => "126.60",
-    "detailed#cost_info#data_read_per_join" => "183K",
-    "detailed#used_columns" => ["user_id"]
-...
+To change the word wrap width for the pretty analysis result, default value: `100`
+```ruby
+analysis = QueryPolice.analyse("select * from users")
+puts analysis.pretty_analysis_for('positive', {'wrap_width' => 40})
+# or
+puts analysis.pretty_analysis({'positive' => true, 'wrap_width' => 40})
+
+# puts
+# +--------------------------------------------------+
+# |                      users                       |
+# +-----------+--------------------------------------+
+# | debt     | 330.0                                |
+# +-----------+--------------------------------------+
+# | column    | select_type                          |
+# | impact    | positive                             |
+# | tag_debt | 0                                    |
+# | message   | A simple query without subqueries or |
+# |           | unions.                              |
+# +-----------+--------------------------------------+
+
+puts analysis.pretty_analysis_for('positive', {'wrap_width' => 20})
+# or
+puts analysis.pretty_analysis({'positive' => true, 'wrap_width' => 20})
+
+# puts
+# +--------------------------------+
+# |             users              |
+# +-----------+--------------------+
+# | debt     | 330.0              |
+# +-----------+--------------------+
+# | column    | select_type        |
+# | impact    | positive           |
+# | tag_debt | 0                  |
+# | message   | A simple query     |
+# |           | without subqueries |
+# |           | or unions.         |
+# +-----------+--------------------+
+```
+
+### Skip footer
+
+To skip the footer (added in [query police config](#analysis-footer)) after an analysis of a query
+```ruby
+analysis = QueryPolice.analyse("select * from users")
+puts analysis.pretty_analysis_for('positive', {'skip_footer' => true})
+# or
+puts analysis.pretty_analysis({'positive' => true, 'skip_footer' => true})
 ```
 
+### Analysis Footer
+To define a footer text that will be added after an analysis for a query, by default there is no footer
+```ruby
+QueryPolice.analysis_footer = 'Please check more details with this link...'
+# or
+QueryPolice.configure do |config|
+  config.analysis_footer = 'Please check more details with this link...'
+end
+
+# puts
+# +----------------------------------------------------------+         
+# |                          users                           |         
+# +-----------+----------------------------------------------+         
+# | debt     | 330.0                                        |         
+# +-----------+----------------------------------------------+         
+# | column    | select_type                                  |
+# | impact    | positive                                     |
+# | tag_debt | 0                                            |
+# | message   | A simple query without subqueries or unions. |
+# +-----------+----------------------------------------------+
+# Please check more details with this link...
+```
+
+### Custom rules path
+
+To define custom rules path (More details about [how to define custom rules](#how-to-define-custom-rules))
+```ruby
+QueryPolice.rules_path = 'path/to/rules/file.<json/yml>'
+# or
+QueryPolice.configure do |config|
+  config.rules_path = 'path/to/rules/file.<json/yml>'
+end
+```
 
+### Verbosity
 
-##### Flatten
-
-`{a: {b: 1}, c: 2}` is converted into `{a#b: 1, c: 2}`.
+Verbosity defines which `EXPLAIN` result should be used for analysis. (More details about [EXPLAIN vs Detailed EXPLAIN](#execution-plan))
+- `basic` - It uses only `EXPLAIN`(basic) result
+- `detailed` - It uses both `EXPLAIN`(basic) and `EXPLAIN format=json`(detailed) results `(default value)`
+```ruby
+QueryPolice.verbosity = "detailed"
+# or
+QueryPolice.configure do |config|
+  config.verbosity = "detailed"
+end
+```
 
+### Disable Actions
 
-## Analysis object
+To disable actions that are performed on each query.
+```ruby
+# Note: A logger action is already added, so query police will log pretty analysis after each query by default
+QueryPolice.action_enabled = false
+# or
+QueryPolice.configure do |config|
+  config.action_enabled = false
+end
+```
 
-Analysis object stores a detailed analysis report of a relation inside `:tables :summary attributes`.
+### Custom Actions
 
-#### Attributes
+To add custom actions, by default a logger action is already added and enabled (More details about [Analysis Object](#analysis-object))
+```ruby
+QueryPolice.add_action do |analysis| # analysis object for the query
+  puts analysis.tables
+end
+```
 
-**tables [Hash] - detailed table analysis**
+### Logger config
 
-```
-{
-  'users' => {                        
-    'id'=>1,                    
-    'name' => 'users',               # table alias user in the execution plan
-    'score' => <float>               # score for the table   
-    'analysis' => {
-      'type' => {                    # attribute name
-        'value' => <string>,         # raw value of attribute in execution plan
-        'tags' => {
-          'all' => {                 # tag based on the value of a attribute
-            'impact'=> <string>,     # negative, positive, cautions
-            'warning'=> <string>,    # Eg. 'warning to represent the issue'
-            'suggestions'=> <string> # Eg. 'some follow-up suggestions'
-            'score' => <float>       # score for the tag
-          }
-        }
-      }
-    }
-  }
-}
-```
-**summary [Hash] - hash of analysis summary**
+To change the logger options which will be used to generate analysis
+```ruby
+QueryPolice.logger_options = {'negative' => true}
+# or
+QueryPolice.configure do |config|
+  config.logger_options = {'negative' => true}
+end
 
-```
-{
-  'cardinality' => {
-    'amount' => 10,
-    'warning' => 'warning to represent the issue',
-    'suggestions' => 'some follow up suggestions',
-    'score' => 100.0
-  }
-}
+# default logger_config: {'negative' => true, 'caution' => true}
+# options negative: <Boolean>, positive: <Boolean>, caution: <Boolean>, wrap_width: <Integer>, skip_footer: <Boolean>
 ```
 
+---
 
+## How to define custom rules?
 
-## How to define rules?
-
-Rules defined in the json file at config_path is applied to the execution plan. We have variety of option to define rules.
+Rules defined in the `json/yaml` file at rules_path is applied to the execution plan. Query Police have variety of option to define rules.
 
 You can change this by `QueryPolice.rules_path=<path>` and define your own rules
 
 ### Rule Structure
+**Note:** Check Query Police default rules defined at [rules.json](lib/query_police/rules.json) or examples at [examples/rules/](examples/rules/) for better clarity 
 
 A basic rule structure - 
-```
+
+JSON
+```json
 "<column_name>": { 
-  "description": <string>,
-  "value_type": <string>,
-  "delimiter": <string>, 
+  "description": "<string>",
+  "value_type": "<string>",
+  "delimiter": "<string>", 
   "rules": {
     "<rule>": {
-      "amount": <integer>
-      "impact": <string>,
-      "message": <string>,
-      "suggestion": <string>,
-      "score": {
-        "value": <integer>,
-        "type": <string>
+      "amount": "<integer>",
+      "impact": "<string>",
+      "message": "<string>",
+      "suggestion": "<string>",
+      "debt": {
+        "value": "<integer>",
+        "type": "<string>"
       } 
     }
   }
 }
 ```
-- `<column_name>` - attribute name in the final execution plan.
-
+YAML
+```yaml
+<column_name>:
+  description: <string>
+  value_type: <string>
+  delimiter: <string>
+  rules:
+    <rule>:
+      amount: <integer>
+      impact: <string>
+      message: <string>
+      suggestion: <string>
+      debt:
+        value: <integer>
+        type: <string>
+```
+- `<column_name>` - attribute name in the final execution plan. (more details about [attributes](#attributes-for-rules))
 - `description` - description of the attribute
-
 - `value_type` - value type of the attribute
-
 - `delimiter` - delimiter to parse array type attribute values, if no delimiter is passed engine will consider value is already in array form.
-
 - `<rule>` - kind of rule for the attribute
-
     - `<tag>` - direct value match eg. ALL, SIMPLE
-
     - `absent` - when the value is missing
-
     - `threshold` - a greater than threshold check based on the amount set inside the rule.
-
 - `amount` - the amount of threshold that needs to check for 
-
     - length for string
-
     - value for number
-
     - size for the array
-
 - `impact` - impact of the rule
-
     - `negative`
-
     - `postive`
-
     - `caution`
-
 - `message` - the message needs to provide the significance of the rule
-
 - `suggestion` - suggestion on how we can fix the issue
-- `score` - score-related config that will be affected to final query score
-    - `value` - value that will be added to the query score 
-    -  `type` - the type of scoring that will be added to the query score
+- `debt` - debt-related config that will be affected to final query debt
+    - `value` - value that will be added to the query debt 
+    -  `type` - the type of scoring that will be added to the query debt
         - `base`- value
         - `relative` - value * (amount for that column in query)
-        - `treshold_relative` - (value - (threshold amount)) * (amount for that column in query)
+        - `threshold_relative` - (value - (threshold amount)) * (amount for that column in query)
 
 
 
@@ -342,34 +340,22 @@ A basic rule structure -
 We can define dynamic messages and suggestions with variables provided by the engine.
 
 - `$amount` - the amount of the value 
-
     - length for string
-
     - value for number
-
     - size for the array
-
 - `$column` - attribute name
-
 - `$impact` - impact for the rule
-
 - `$table` - table alias used in the plan
-
 - `$tag` - tag for which rule is applied 
-
 - `$value` - original parsed value
-
 - `$<column_name>` - the value of that specific column in that table
-
 - `$amount_<column_name>` - amount of that specific column
 
-
-
 ### Rules Examples
 
 #### Basic rule example 
-
-```
+File: [JSON](examples/rules/json/basic_rule.json) | [YAML](examples/rules/yaml/basic_rule.yml)
+```json
 "type": {
   "description": "Join used in the query for a specific table.",
   "value_type": "string",
@@ -383,11 +369,12 @@ We can define dynamic messages and suggestions with variables provided by the en
       "impact": "negative",
       "message": "Entire $table table is scanned to find matching rows, you have $amount_possible_keys possible keys to use.",
       "suggestion": "Use index here. You can use index from possible key: $possible_keys or add new one to $table table as per the requirements.",
-      "score": {
+      "debt": {
         "value": 200,
         "type": "base" 
       }
     }
+  }
 }
 ```
 For the above rule, dynamic message will be generated as-
@@ -401,8 +388,8 @@ Use index here. You can use index from possible key: ["PRIMARY", "user_email"] o
 
 
 #### Absent rule example
-
-```
+File: [JSON](examples/rules/json/absent_rule.json) | [YAML](examples/rules/yaml/absent_rule.yml)
+```json
 "key": {
   "description": "index key used for the table",
   "value_type": "string",
@@ -427,8 +414,8 @@ Please use index from possible_keys: ["PRIMARY", "user_email"] or add new one to
 
 
 #### Threshold rule example
-
-```
+File: [JSON](examples/rules/json/threshold_rule.json) | [YAML](examples/rules/yaml/threshold_rule.yml)
+```json
 "possible_keys": {
   "description": "Index keys possible for a specifc table",
   "value_type": "array",
@@ -454,8 +441,8 @@ Please check if there are extra indexes in users table.
 
 
 #### Complex Detailed rule example
-
-```
+File: [JSON](examples/rules/json/complex_detailed_rule.json) | [YAML](examples/rules/yaml/complex_detailed_rule.yml)
+```json
 "detailed#used_columns": {
   "description": "",
   "value_type": "array",
@@ -465,9 +452,9 @@ Please check if there are extra indexes in users table.
       "impact": "negative",
       "message": "You have selected $amount columns, You should not select too many columns.",
       "suggestion": "Please only select required columns.",
-      "score": {
+      "debt": {
         "value": 10,
-        "type": "treshold_relative" 
+        "type": "threshold_relative" 
       }
     }
   }
@@ -483,9 +470,9 @@ Please only select required columns.
 ```
 
 
-### Summary
+### Summary in Analysis
 
-You can define similar rules for the summary. Current summary attribute supported - 
+You can define similar rules for the summary. Current only one attribute is supported in summary - 
 
 - `cardinality` - cardinality based on all tables
 
@@ -493,7 +480,7 @@ You can define similar rules for the summary. Current summary attribute supporte
 
 
 
-### Attributes
+### Attributes for Rules
 
 There are a lot of attributes for you to use based on the final execution plan. 
 
@@ -509,6 +496,185 @@ To check more keys you can use `EXPLAIN format=JSON <query>`
 
 ---
 
+## How Query Police works?
+
+1. Query police converts the relation into SQL query
+
+2. Query police generates an execution plan using EXPLAIN and EXPLAIN format=JSON based on the configuration.
+
+3. Query police load rules from the config file.
+
+4. Query police apply rules on the execution plan and generate a new analysis object.
+
+5. Analysis object provides different methods to print the analysis in a more descriptive format.
+
+
+## Execution plan
+
+We have 2 possible execution plans:-
+
+Normal - using `EXPLAIN`
+
+Detailed - using `EXPLAIN format=JSON`
+
+**NOTE:** By default Detailed execution plan is added in the final execution plan, you can remove that by `QueryPolice.detailed=false`
+
+### Normal execution plan
+
+Generated using `EXPAIN <query>`
+
+**Result**
+
+| id | select_type | table   | partitions | type.  | possible_keys             | key                 | key_len | ref                         | rows | filtered | Extra                    |
+|----|-------------|---------|------------|--------|---------------------------|---------------------|---------|-----------------------------|------|----------|--------------------------|
+|  1 | SIMPLE      | profile | NULL.      | index  | fk_rails_249a7ebca1       | fk_rails_249a7ebca1 | 5       | NULL                        |  603 |  100.00  | Using where; Using index |
+|  1 | SIMPLE      | users   | NULL       | eq_ref | PRIMARY,index_users_on_id | PRIMARY             | 4       | development.profile.user_id |1     |  100.00  | NULL                     |
+
+
+The result for this is added as it is in the final execution plan
+
+**Eg.**
+
+```ruby
+{
+    "profile" => {
+                   "id" => 1,
+          "select_type" => "SIMPLE",
+                "table" => "profile",
+           "partitions" => nil,
+                 "type" => "index",
+        "possible_keys" => "fk_rails_249a7ebca1",
+                  "key" => "fk_rails_249a7ebca1",
+              "key_len" => "5",
+                  "ref" => nil,
+                 "rows" => 603,
+             "filtered" => 100.0,
+                "Extra" => "Using where; Using index"
+    },
+                  "users" => {
+                   "id" => 1,
+          "select_type" => "SIMPLE",
+                "table" => "users",
+           "partitions" => nil,
+                 "type" => "eq_ref",
+        "possible_keys" => "PRIMARY,index_users_on_id",
+                  "key" => "PRIMARY",
+              "key_len" => "4",
+                  "ref" => "development.profile.user_id",
+                 "rows" => 1,
+             "filtered" => 100.0,
+                "Extra" => nil
+    }
+}
+```
+
+### Detailed execution plan
+
+Generated using `EXPAIN format=JSON <query>`
+
+**Truncated Result**
+
+```ruby
+{
+  "query_block": {
+    "select_id": 1,
+    "cost_info": {
+      "query_cost": "850.20"
+    },
+    "nested_loop": [
+      {
+        "table": {
+          "table_name": "profile",
+          "access_type": "index",
+          "key_length": "5",
+          "cost_info": {
+            "read_cost": "6.00",
+            "eval_cost": "120.60",
+            "prefix_cost": "126.60",
+            "data_read_per_join": "183K"
+          },
+          "used_columns": [
+            "user_id"
+          ],
+          "attached_condition": "(`development`.`profile`.`user_id` is not null)"
+        }
+      }
+    ]
+  }
+}
+```
+
+
+The result for this is added in the flattened form to the final execution plan, where the `detailed#` prefix is added before each key.
+
+**Truncated Eg.**
+
+```ruby
+{
+    "detailed#key_length" => "5",
+    "detailed#rows_examined_per_scan" => 603,
+    "detailed#rows_produced_per_join" => 603,
+    "detailed#filtered" => "100.00",
+    "detailed#using_index" => true,
+    "detailed#cost_info#read_cost" => "6.00",
+    "detailed#cost_info#eval_cost" => "120.60",
+    "detailed#cost_info#prefix_cost" => "126.60",
+    "detailed#cost_info#data_read_per_join" => "183K",
+    "detailed#used_columns" => ["user_id"]
+...
+```
+
+
+
+##### Flatten
+
+`{a: {b: 1}, c: 2}` is converted into `{a#b: 1, c: 2}`.
+
+---
+
+## Analysis object
+
+Analysis object stores a detailed analysis report of a relation inside `:tables :summary attributes`.
+
+#### Attributes
+
+**tables [Hash] - detailed table analysis**
+
+```ruby
+{
+  'users' => {                        
+    'id'=>1,                    
+    'name' => 'users',               # table alias user in the execution plan
+    'debt' => <float>               # debt for the table   
+    'analysis' => {
+      'type' => {                    # attribute name
+        'value' => <string>,         # raw value of attribute in execution plan
+        'tags' => {
+          'all' => {                 # tag based on the value of a attribute
+            'impact'=> <string>,     # negative, positive, cautions
+            'warning'=> <string>,    # Eg. 'warning to represent the issue'
+            'suggestions'=> <string> # Eg. 'some follow-up suggestions'
+            'debt' => <float>       # debt for the tag
+          }
+        }
+      }
+    }
+  }
+}
+```
+**summary [Hash] - hash of analysis summary**
+
+```ruby
+{
+  'cardinality' => {
+    'amount' => 10,
+    'warning' => 'warning to represent the issue',
+    'suggestions' => 'some follow up suggestions',
+    'debt' => 100.0
+  }
+}
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.