dbee 2.0.2 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a6408442138aafff2ca06cd0161a5fd34a10270a773fb6bd90a9cde54c593b66
-  data.tar.gz: 8dfb19dc5001ba6e7718cac33e0041eaef49747343a189138dd165f82b825bfb
+  metadata.gz: 2b8250c307ad60bdb8bc51e19fdb93b2c9eb3db0cccfb5daad0a2e621aab57cb
+  data.tar.gz: db66f66f4a56dd40bbaa347218d0827291c789733b9c3f7086ca416e85a09246
 SHA512:
-  metadata.gz: d26d78a27695eb0c4ca15055ada5624c802d4f22c9d7a5fb110b940bcf1bdc56f1bdcb65f0c4754820439bf94fcc6ba029dd1f922c6e53f9a07698a862b5d897
-  data.tar.gz: 5074fbbc002af0e8e7335a2a1e25bfbaa25923cdbc6171d177de5ebee6147236248f2d7efd86ca4d398ac2abf2b4a4873d49d2cd2a38bfde8cbf46fc6e8bc7b8
+  metadata.gz: '0085b06c34404de9b93b728713fd118189a2693920668685e66574c2bd23b8cb2009d0ab4a047dbbc8b4e7c69084a3ec595d1fa80aaf6de06bce023d5fff3d1a'
+  data.tar.gz: a295c963939ce9df84689bd3ab34852df111a7c57e685ac07abdb661498dc269fe85e661fae49b77826e43054030fb09c18fe7da648a1cdc78020024bac15a52

data/.gitignore

@@ -4,3 +4,4 @@
 /coverage
 Gemfile.lock
 /pkg
+.vscode

data/.rubocop.yml

@@ -1,8 +1,15 @@
-Metrics/LineLength:
+AllCops:
+  TargetRubyVersion: 2.5
+  NewCops: enable
+
+Layout/LineLength:
   Max: 100
 
+Metrics/AbcSize:
+  Max: 16
+
 Metrics/BlockLength:
-  ExcludedMethods:
+  IgnoredMethods:
     - let
     - it
     - describe
@@ -10,14 +17,11 @@ Metrics/BlockLength:
     - specify
     - define
 
-Metrics/MethodLength:
-  Max: 25
-
-AllCops:
-  TargetRubyVersion: 2.3
-
-Metrics/AbcSize:
-  Max: 16
+Metrics/ParameterLists:
+  CountKeywordArgs: false
 
 Metrics/ClassLength:
   Max: 125
+
+Metrics/MethodLength:
+  Max: 25

data/.ruby-version

@@ -1 +1 @@
-2.6.3
+2.6.6

data/.travis.yml

@@ -1,13 +1,13 @@
 env:
   global:
     - CC_TEST_REPORTER_ID=e7db23dad7560a076e48357331b0362db3741b62dbdd537bc30de27fa9cab69b
+    - DISABLE_RSPEC_FOCUS=true
 language: ruby
 rvm:
   # Build on the latest stable of all supported Rubies (https://www.ruby-lang.org/en/downloads/):
-  - 2.3.8
-  - 2.4.6
-  - 2.5.5
-  - 2.6.3
+  - 2.5.8
+  - 2.6.6
+  - 2.7.2
 cache: bundler
 before_script:
   - curl -L https://codeclimate.com/downloads/test-reporter/test-reporter-latest-linux-amd64 > ./cc-test-reporter

data/CHANGELOG.md

@@ -1,3 +1,46 @@
+# 3.0.0 (March 11th, 2021)
+
+### Additions
+
+* Support for graph based models. This paves the way for representing more advanced features, such as sub-queries in a more clear way. Since graph based models are similar to DSL models, the hope is that they will be easier to work with and understand.
+
+### Breaking Changes
+
+* The `to_model` method on `Dbee::Base` objects has been removed. Use `to_schema` instead.
+* The `ancestors!` method on `Dbee::Model` has been removed. Use `Dbee::Schema#expand_query_path` instead.
+
+# 2.1.1 (July 14th, 2020)
+
+* Removed guard that ensured a query has at least one field to establish a more rational base-case.
+
+# 2.1.0 (July 13th, 2020)
+
+### Additions:
+
+* Added Dbee::Query::Field#aggregator (such as ave, min, max, sum, etc.)
+* Added Dbee::Query::Field#filters (allows for doing select column filtering)
+
+### Changes:
+
+* Bumped minimum Ruby version to 2.5
+
+# 2.0.3 (January 7th, 2020)
+
+### Fixes:
+
+* Constant resolution will now explicitly set inherit to false when calling `Object#const_defined?` and `Object#const_get`.  This should equate to less false positives.  For example:
+
+```ruby
+class A; end
+
+module B
+  class A; end
+  class C; end
+end
+```
+
+If `B::A` is the desired class, it would not be suitable to just declare an association on `A` as that would resolve explicitly to `::A`.  It also means C cannot be auto-resolved without prefixing/sharing the namespace with parent association `A`.
+
 # 2.0.2 (November 7th, 2019)
 
 ### Additions:

data/README.md

@@ -20,7 +20,7 @@ Both of these solutions ended up closely coupling our domain data layer to ad-ho
 
 ## Installation
 
-This specific library is the core modeling component of the Dbee framework, but by itself, it not completely usable.  You will need to provide a SQL generator which understands how to convert the data and query modeling to actual SQL.  This library comes with a stub: Dbee::Providers::NullProvider, while the main reference implementation is split out into its own library: [dbee-active_record](https://github.com/bluemarblepayroll/dbee-active_record). Together these two libraries comprise a complete solution.  Refer to the other library for more information on installation.
+This specific library is the core modeling component of the Dbee framework, but by itself, it is not completely usable.  You will need to provide a SQL generator which understands how to convert the data and query modeling to actual SQL.  This library comes with a stub: Dbee::Providers::NullProvider, while the main reference implementation is split out into its own library: [dbee-active_record](https://github.com/bluemarblepayroll/dbee-active_record). Together these two libraries comprise a complete solution.  Refer to the other library for more information on installation.
 
 To install through Rubygems:
 
@@ -189,49 +189,58 @@ The two code-first examples above should be technically equivalent.
 You can choose to alternatively describe your data model using configuration.  The YAML below is equivalent to the Ruby sub-classes above:
 
 ````yaml
-name: practice
-models:
-  - name: patients
-    constraints:
-      - type: reference
-        name: practice_id
-        parent: id
-    models:
-      - name: notes
-        constraints:
-          - type: reference
-            name: patient_id
-            parent: id
-      - name: work_phone_number
-        table: phones
-        constraints:
-          - type: reference
-            name: patient_id
-            parent: id
-          - type: static
-            name: phone_number_type
-            value: work
-      - name: cell_phone_number
-        table: phones
-        constraints:
-          - type: reference
-            name: patient_id
-            parent: id
-          - type: static
-            name: phone_number_type
-            value: cell
-      - name: fax_phone_number
-        table: phones
-        constraints:
-          - type: reference
-            name: patient_id
-            parent: id
-          - type: static
-            name: phone_number_type
-            value: fax
+practice:
+  table: practices
+  relationships:
+    patients:
+      model: patient
+      constraints:
+        - type: reference
+          name: practice_id
+          parent: id
+patient:
+  table: patients
+  relationships:
+    notes:
+      model: note
+      constraints:
+        - type: reference
+          name: patient_id
+          parent: id
+    work_phone_number:
+      model: phone_number
+      constraints:
+        - type: reference
+          name: patient_id
+          parent: id
+        - type: static
+          name: phone_number_type
+          value: work
+    cell_phone_number:
+      model: phone_number
+      constraints:
+        - type: reference
+          name: patient_id
+          parent: id
+        - type: static
+          name: phone_number_type
+          value: cell
+    fax_phone_number:
+      model: phone_number
+      constraints:
+        - type: reference
+          name: patient_id
+          parent: id
+        - type: static
+          name: phone_number_type
+          value: fax
+note:
+  table: notes
+phone_number:
+  table: phones
 ````
 
-It is up to you to determine which modeling technique to use as both are equivalent.  Technically speaking, the code-first DSL is nothing more than syntactic sugar on top of Dbee::Model.
+It is up to you to determine which modeling technique to use as both are equivalent.  Technically speaking, the code-first DSL is nothing more than syntactic sugar on top of `Dbee::Schema` and `Dbee::Model`. Also note that prior to version three of this project, a more hierarchical tree based model configuration was used. See [Tree Based Model Backward Compatibility](#tree-based-model-backward-compatibility) below for more information on this.
 
 #### Table Partitioning
 
@@ -275,6 +284,7 @@ Cats:
 The Query API (Dbee::Query) is a simplified and abstract way to model an SQL query.  A Query has the following components:
 
 * fields (SELECT)
+* from (FROM)
 * filters (WHERE)
 * sorters (ORDER BY)
 * limit (LIMIT/TAKE)
@@ -291,6 +301,7 @@ Get all practices:
 
 ````ruby
 query = {
+  from: 'practice',
   fields: [
     { key_path: 'id' },
     { key_path: 'active' },
@@ -303,6 +314,7 @@ Get all practices, limit to 10, and sort by name (descending) then id (ascending
 
 ````ruby
 query = {
+  from: 'practice',
   fields: [
     { key_path: 'id' },
     { key_path: 'active' },
@@ -320,6 +332,7 @@ Get top 5 active practices and patient whose name start with 'Sm':
 
 ````ruby
 query = {
+  from: 'practice',
   fields: [
     { key_path: 'name', display: 'Practice Name' },
     { key_path: 'patients.first', display: 'Patient First Name' },
@@ -338,6 +351,7 @@ Get practice IDs, patient IDs, names, and cell phone numbers that starts with '5
 
 ````ruby
 query = {
+  from: 'practice',
   fields: [
     { key_path: 'id', display: 'Practice ID #' },
     { key_path: 'patients.id', display: 'Patient ID #' },
@@ -363,6 +377,22 @@ You execute a Query against a Data Model, using a Provider.  The sample provider
 
 Here are some sample executions based off the preceding examples:
 
+##### Base Case
+
+If a query has no fields then it is implied you would like all fields on the root table.  For example:
+
+````ruby
+require 'dbee/providers/active_record_provider'
+
+class Practice < Dbee::Base; end
+
+provider = Dbee::Providers::ActiveRecordProvider.new
+query    = { from: 'practice' }
+sql      = Dbee.sql(Practice, query, provider)
+````
+
+It equivalent to saying: `SELECT practices.* FROM practices`.  This helps to establish a deterministic base-case: it returns the same implicit columns that is independent of sql joins (sorters and/or filters may require sql joins.)
+
 ##### Code-First Execution
 
 ````ruby
@@ -373,6 +403,7 @@ class Practice < Dbee::Base; end
 provider = Dbee::Providers::ActiveRecordProvider.new
 
 query = {
+  from: 'practice',
   fields: [
     { key_path: 'id' },
     { key_path: 'active' },
@@ -391,10 +422,11 @@ require 'dbee/providers/active_record_provider'
 provider = Dbee::Providers::ActiveRecordProvider.new
 
 model = {
-  name: :practice
+  practice: { table: 'practices' }
 }
 
 query = {
+  from: 'practice',
   fields: [
     { key_path: 'id' },
     { key_path: 'active' },
@@ -407,7 +439,189 @@ sql = Dbee.sql(model, query, provider)
 
 The above examples showed how to use a plugin provider, see the plugin provider's documentation for more information about its options and use.
 
+#### Aggregation
+
+Fields can be configured to use aggregation by setting its `aggregator` attribute.  For example, say we wanted to count the number of patients per practice:
+
+**Data Model**:
+
+````yaml
+practice:
+  table: practices
+  relationships:
+    patients:
+      model: patient
+      constraints:
+        - type: reference
+          name: practice_id
+          parent: id
+patient:
+  table: patients
+````
+
+**Query**:
+
+````ruby
+query = {
+  from: 'practice',
+  fields: [
+    {
+      key_path: 'id',
+      display: 'Practice ID #',
+    },
+    {
+      key_path: 'name',
+      display: 'Practice Name',
+    },
+    {
+      key_path: 'patients.id',
+      display: 'Total Patients',
+      aggregator: :count
+    },
+  ]
+````
+
+An example of a materialized result would be something akin to:
+
+Practice ID # | Practice Name   | Total Patients
+------------- | --------------- | --------------
+1             | Families Choice | 293
+2             | Awesome Choice  | 2305
+3             | Best Value      | 1200
+
+A complete list of aggregator values can be found by inspecting the `Dbee::Query::Field::Aggregator` constant.
+
+#### Field/Column Level Filtering & Pivoting
+
+Fields can also have filters which provide post-filtering (on the select-level instead of at query-level.)  This can be used in conjunction with aggregate functions to provide pivoting.  For example:
+
+**Data/Schema Example**:
+
+patients:
+
+id | first | last
+-- | ----- | -----
+1  | frank | rizzo
+
+patient_fields:
+
+id | patient_id | key             | value
+-- | ---------- | --------------- | -----
+1  | 1          | dob             | 1900-01-01
+2  | 1          | drivers_license | ABC123
+
+**Model Configuration**:
+
+````yaml
+patients:
+  relationships:
+    - patient_fields:
+      constraints:
+        - type: reference
+          parent: id
+          name: patient_id
+patient_fields:
+````
+
+**Query**:
+
+````ruby
+query = {
+  from: 'patients',
+  fields: [
+    {
+      key_path: 'id',
+      display: 'ID #'
+    },
+    {
+      key_path: 'first',
+      display: 'First Name'
+    },
+    {
+      aggregator: :max,
+      key_path: 'patient_fields.value',
+      display: 'Date of Birth',
+      filters: [
+        {
+          key_path: 'patient_fields.key',
+          value: 'dob'
+        }
+      ]
+    },
+    {
+      aggregator: :max,
+      key_path: 'patient_fields.value',
+      display: 'Drivers License #',
+      filters: [
+        {
+          key_path: 'patient_fields.key',
+          value: 'drivers_license'
+        }
+      ]
+    }
+  }
+}
+````
+
+Executing the query above against the data and model would yield:
+
+ID # | First Name | Date of Birth | Drivers License #
+--   | ---------- | ------------- | -----------------
+1    | frank      | 1900-01-01    | ABC123
+
+## Tree Based Model Backward Compatibility
+
+In version three of this gem, the representation of configuration based models was changed to be more of a graph structure than the previous tree structure. For backwards compatibility, it is still possible to pass this older tree based structure as the first argument `Dbee.sql`. The practices example would be represented this way in the old structure:
+
+````yaml
+  # Deprecated tree based model configuration:
+  name: practice
+  table: practices
+  models:
+    - name: patients
+      constraints:
+        - type: reference
+          name: practice_id
+          parent: id
+      models:
+        - name: notes
+          constraints:
+            - type: reference
+              name: patient_id
+              parent: id
+        - name: work_phone_number
+          table: phones
+          constraints:
+            - type: reference
+              name: patient_id
+              parent: id
+            - type: static
+              name: phone_number_type
+              value: work
+        - name: cell_phone_number
+          table: phones
+          constraints:
+            - type: reference
+              name: patient_id
+              parent: id
+            - type: static
+              name: phone_number_type
+              value: cell
+        - name: fax_phone_number
+          table: phones
+          constraints:
+            - type: reference
+              name: patient_id
+              parent: id
+            - type: static
+              name: phone_number_type
+              value: fax
+````
 
+Also note to further maintain backwards compatibility, queries issued against
+tree based models do not need the "from" attribute to be defined. This is
+because the from/starting point of the query can be inferred as the model at
+the root of the tree.
 ## Contributing
 
 ### Development Environment Configuration