occams-record 0.14.0 → 0.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c38ef4286e850f0409ef60595a18e28dfce74f9b43b60fa776d782f899e800c9
-  data.tar.gz: 4960fa6e619bbc4e20dbaf94fb5d557ddd5f8ed50443b4ad5f5716fb4da1a383
+  metadata.gz: d8d0dd44c9dd065285ae2a1dfc0c5cd05f27d70b2b611011f128a7692c7afc31
+  data.tar.gz: 0b08d794ce884b340d00b72d531cc3e7e1c0ee4e200eed585c65edf5066e1a4d
 SHA512:
-  metadata.gz: d7f32e7259a88470318e0aac8e89d62c993d443c4ff379392cc7eb731f7649c5cb958994e25be2f23386e0ee0b73d05fc07998a71be6faf7f224c3231560010f
-  data.tar.gz: 9ced85fba2d01430725e33d97984775b7a2a59f14a0fa11b03965302a528cd99a138fa913e4d0ec2b58f7fd9356bfffe79359b3a2ed3a25fa9a99bcff040ee7c
+  metadata.gz: 7587c4c1d9464ac8a078b417afb4e9f2603419b9ef13ecc05da8496854fcf787bf93330756118e5e9b4696729f47c4c676bc9ad36b6ae4da0222c931c7bace0c
+  data.tar.gz: b897b931d76a8e87eb97a07319975cd57c6cfa355842f0097830dd75db09f22c158edcb40d476b7be2d54d8c3b489e87294bf66bf0147e234f1dbeba18c2b590

data/README.md

@@ -11,6 +11,7 @@ Occam's Record is a high-efficiency query API for ActiveRecord. It is **not** an
 * `find_each`/`find_in_batches` respects `order` and `limit`.
 * Allows eager loading of associations when using raw SQL.
 * Allows `find_each`/`find_in_batches` when using raw SQL.
+* Eager load data from arbitrary SQL (no association required).
 
 [Look over the speed and memory measurements yourself!](https://github.com/jhollinger/occams-record/wiki/Measurements) OccamsRecord achieves all of this by making some very specific trade-offs:
 
@@ -86,6 +87,28 @@ widgets = OccamsRecord.
   run
 ```
 
+**Eager load using raw SQL without a predefined association**
+
+Let's say we want to load each widget and eager load all the customers who've ever ordered it. We could do that using the above example, but we end up loading a bunch of stuff we don't care about. What if we could define an ad hoc association using raw SQL? Enter `eager_load_one` and `eager_load_many`! See the full documentation for a full description of all options.
+
+```ruby
+widgets = OccamsRecord.
+  query(Widget.order("name")).
+
+  # load the results of the query into "customers", matching "widget_id"
+  # in the results to the "id" field of the widgets
+  eager_load_many(:customers, {:widget_id => :id}, %(
+    SELECT DISTINCT customers.id, customers.name, order_items.widget_id
+    FROM customers
+      INNER JOIN orders ON orders.customer_id = customers.id
+      INNER JOIN order_items ON order_items.order_id = orders.id
+    WHERE order_items.widget_id IN (%{ids})
+  ), binds: {
+    # additional bind values (ids will be passed in for you)
+  }).
+  run
+```
+
 ## Injecting instance methods
 
 By default your results will only have getters for selected columns and eager-loaded associations. If you must, you *can* inject extra methods into your results by putting those methods into a Module. NOTE this is discouraged, as you should try to maintain a clear separation between your persistence layer and your domain.

data/lib/occams-record/eager_loaders.rb

@@ -10,6 +10,10 @@ module OccamsRecord
     autoload :HasMany, 'occams-record/eager_loaders/has_many'
     autoload :Habtm, 'occams-record/eager_loaders/habtm'
 
+    autoload :AdHocBase, 'occams-record/eager_loaders/ad_hoc_base'
+    autoload :AdHocOne, 'occams-record/eager_loaders/ad_hoc_one'
+    autoload :AdHocMany, 'occams-record/eager_loaders/ad_hoc_many'
+
     # Methods for adding eager loading to a query.
     module Builder
       #
@@ -34,15 +38,72 @@ module OccamsRecord
         self
       end
 
+      #
+      # Specify some arbitrary SQL to be loaded into some arbitrary attribute ("name"). The attribute will
+      # hold either one record or none.
+      #
+      # In the example below, :category is NOT an association on Widget. Though if it where it would be a belongs_to. The
+      # mapping argument says "The id column in this table (categories) maps to the category_id column in the other table (widgets)".
+      # The %{ids} bind param will be provided for you, and in this case will be all the category_id values from the main
+      # query.
+      #
+      #   res = OccamsRecord.
+      #     query(Widget.order("name")).
+      #     eager_load_one(:category, {:id => :category_id}, %(
+      #       SELECT * FROM categories WHERE id IN (%{ids}) AND name != %{bad_name}
+      #     ), binds: {
+      #       bad_name: "Bad Category"
+      #     }).
+      #     run
+      #
+      # @param name [Symbol] name of attribute to load records into
+      # @param mapping [Hash] a one element Hash with the key being the local/child id and the value being the foreign/parent id
+      # @param sql [String] the SQL to query the associated records. Include a bind params called '%{ids}' for the foreign/parent ids.
+      # @param binds [Hash] any additional binds for your query.
+      # @param model [ActiveRecord::Base] optional - ActiveRecord model that represents what you're loading. required when using Sqlite.
+      # @param use [Array<Module>] optional - Ruby modules to include in the result objects (single or array)
+      #
+      def eager_load_one(*args, &eval_block)
+        @eager_loaders << EagerLoaders::AdHocOne.new(*args, &eval_block)
+        self
+      end
+
+      #
+      # Specify some arbitrary SQL to be loaded into some arbitrary attribute ("name"). The attribute will
+      # hold an array of 0 or more associated records.
+      #
+      # In the example below, :parts is NOT an association on Widget. Though if it where it would be a has_many. The
+      # mapping argument says "The widget_id column in this table (parts) maps to the id column in the other table (widgets)".
+      # The %{ids} bind param will be provided for you, and in this case will be all the id values from the main
+      # query.
+      #
+      #   res = OccamsRecord.
+      #     query(Widget.order("name")).
+      #     eager_load_many(:parts, {:widget_id => :id}, %(
+      #       SELECT * FROM parts WHERE widget_id IN (%{ids}) AND sku NOT IN (%{bad_skus})
+      #     ), binds: {
+      #       bad_skus: ["G90023ASDf0"]
+      #     }).
+      #     run
+      #
+      # @param name [Symbol] name of attribute to load records into
+      # @param mapping [Hash] a one element Hash with the key being the local/child id and the value being the foreign/parent id
+      # @param sql [String] the SQL to query the associated records. Include a bind params called '%{ids}' for the foreign/parent ids.
+      # @param use [Array<Module>] optional - Ruby modules to include in the result objects (single or array)
+      # @param binds [Hash] any additional binds for your query.
+      # @param model [ActiveRecord::Base] optional - ActiveRecord model that represents what you're loading. required when using Sqlite.
+      #
+      def eager_load_many(*args, &eval_block)
+        @eager_loaders << EagerLoaders::AdHocMany.new(*args, &eval_block)
+        self
+      end
+
       private
 
       # Run all defined eager loaders into the given result rows
       def eager_load!(rows)
         @eager_loaders.each { |loader|
-          loader.query(rows) { |scope|
-            assoc_rows = Query.new(scope, use: loader.use, query_logger: @query_logger, &loader.eval_block).run
-            loader.merge! assoc_rows, rows
-          }
+          loader.run(rows, query_logger: @query_logger)
         }
       end
 

data/lib/occams-record/eager_loaders/ad_hoc_base.rb

@@ -0,0 +1,61 @@
+module OccamsRecord
+  module EagerLoaders
+    #
+    # Base class for eager loading ad hoc associations.
+    #
+    class AdHocBase
+      # @return [String] association name
+      attr_reader :name
+
+      #
+      # Initialize a new add hoc association.
+      #
+      # @param name [Symbol] name of attribute to load records into
+      # @param mapping [Hash] a one element Hash with the key being the local/child id and the value being the foreign/parent id
+      # @param sql [String] the SQL to query the associated records. Include a bind params called '%{ids}' for the foreign/parent ids.
+      # @param binds [Hash] any additional binds for your query.
+      # @param model [ActiveRecord::Base] optional - ActiveRecord model that represents what you're loading. required when using Sqlite.
+      # @param use [Array<Module>] optional - Ruby modules to include in the result objects (single or array)
+      # @yield
+      #
+      def initialize(name, mapping, sql, binds: {}, model: nil, use: nil, &eval_block)
+        @name = name.to_s
+        @sql, @binds, @use, @model, @eval_block = sql, binds, use, model, eval_block
+        raise ArgumentError, "Add-hoc eager loading mapping must contain exactly one key-value pair" unless mapping.size == 1
+        @local_key = mapping.keys.first
+        @foreign_key = mapping.fetch(@local_key)
+      end
+
+      #
+      # Run the query and merge the results into the given rows.
+      #
+      # @param rows [Array<OccamsRecord::Results::Row>] Array of rows used to calculate the query.
+      # @param query_logger [Array<String>]
+      #
+      def run(rows, query_logger: nil)
+        calc_ids(rows) { |ids|
+          binds = @binds.merge({:ids => ids})
+          assoc_rows = RawQuery.new(@sql, binds, use: @use, query_logger: query_logger, &@eval_block).model(@model).run
+          merge! assoc_rows, rows
+        }
+      end
+
+      private
+
+      #
+      # Yield ids from the parent association to a block.
+      #
+      # @param rows [Array<OccamsRecord::Results::Row>] Array of rows used to calculate the query.
+      # @yield
+      #
+      def calc_ids(rows)
+        ids = rows.map { |r| r.send @foreign_key }.compact.uniq
+        yield ids
+      end
+
+      def merge!(assoc_rows, rows)
+        raise 'Not Implemented'
+      end
+    end
+  end
+end

data/lib/occams-record/eager_loaders/ad_hoc_many.rb

@@ -0,0 +1,21 @@
+module OccamsRecord
+  module EagerLoaders
+    #
+    # Eager loader for an ad hoc association of 0 or many records (like has_many).
+    #
+    class AdHocMany < AdHocBase
+      private
+
+      #
+      # Merge the association rows into the given rows.
+      #
+      # @param assoc_rows [Array<OccamsRecord::Results::Row>] rows loaded from the associated table
+      # @param rows [Array<OccamsRecord::Results::Row>] rows loaded from the main table
+      #
+      def merge!(assoc_rows, rows)
+        Merge.new(rows, name).
+          many!(assoc_rows, @foreign_key.to_s, @local_key.to_s)
+      end
+    end
+  end
+end

data/lib/occams-record/eager_loaders/ad_hoc_one.rb

@@ -0,0 +1,21 @@
+module OccamsRecord
+  module EagerLoaders
+    #
+    # Eager loader for an ad hoc association of 0 or 1 records (like belongs_to or has_one).
+    #
+    class AdHocOne < AdHocBase
+      private
+
+      #
+      # Merge the association rows into the given rows.
+      #
+      # @param assoc_rows [Array<OccamsRecord::Results::Row>] rows loaded from the associated table
+      # @param rows [Array<OccamsRecord::Results::Row>] rows loaded from the main table
+      #
+      def merge!(assoc_rows, rows)
+        Merge.new(rows, name).
+          single!(assoc_rows, @foreign_key.to_s, @local_key.to_s)
+      end
+    end
+  end
+end

data/lib/occams-record/eager_loaders/base.rb

@@ -6,10 +6,6 @@ module OccamsRecord
     class Base
       # @return [String] association name
       attr_reader :name
-      # @return [Array<Module>] optional Module to include in the result class (single or array)
-      attr_reader :use
-      # @return [Proc] optional Proc for eager loading things on this association
-      attr_reader :eval_block
 
       #
       # @param ref [ActiveRecord::Association] the ActiveRecord association
@@ -25,6 +21,21 @@ module OccamsRecord
         @name = (as || ref.name).to_s
       end
 
+      #
+      # Run the query and merge the results into the given rows.
+      #
+      # @param rows [Array<OccamsRecord::Results::Row>] Array of rows used to calculate the query.
+      # @param query_logger [Array<String>]
+      #
+      def run(rows, query_logger: nil)
+        query(rows) { |scope|
+          assoc_rows = Query.new(scope, use: @use, query_logger: query_logger, &@eval_block).run
+          merge! assoc_rows, rows
+        }
+      end
+
+      private
+
       #
       # Yield one or more ActiveRecord::Relation objects to a given block.
       #

data/lib/occams-record/eager_loaders/belongs_to.rb

@@ -2,6 +2,8 @@ module OccamsRecord
   module EagerLoaders
     # Eager loader for belongs_to associations.
     class BelongsTo < Base
+      private
+
       #
       # Yield one or more ActiveRecord::Relation objects to a given block.
       #

data/lib/occams-record/eager_loaders/habtm.rb

@@ -2,6 +2,8 @@ module OccamsRecord
   module EagerLoaders
     # Eager loader for has_and_belongs_to_many associations.
     class Habtm < Base
+      private
+
       #
       # Yield one or more ActiveRecord::Relation objects to a given block.
       #

data/lib/occams-record/eager_loaders/has_many.rb

@@ -2,6 +2,8 @@ module OccamsRecord
   module EagerLoaders
     # Eager loader for has_many associations.
     class HasMany < HasOne
+      private
+
       #
       # Merge the association rows into the given rows.
       #

data/lib/occams-record/eager_loaders/has_one.rb

@@ -2,6 +2,8 @@ module OccamsRecord
   module EagerLoaders
     # Eager loader for has_one associations.
     class HasOne < Base
+      private
+
       #
       # Yield one or more ActiveRecord::Relation objects to a given block.
       #

data/lib/occams-record/eager_loaders/polymorphic_belongs_to.rb

@@ -4,10 +4,6 @@ module OccamsRecord
     class PolymorphicBelongsTo
       # @return [String] association name
       attr_reader :name
-      # @return [Array<Module>] optional Module to include in the result class (single or array)
-      attr_reader :use
-      # @return [Proc] optional Proc for eager loading things on this association
-      attr_reader :eval_block
 
       #
       # @param ref [ActiveRecord::Association] the ActiveRecord association
@@ -24,6 +20,21 @@ module OccamsRecord
         @foreign_key = @ref.foreign_key.to_sym
       end
 
+      #
+      # Run the query and merge the results into the given rows.
+      #
+      # @param rows [Array<OccamsRecord::Results::Row>] Array of rows used to calculate the query.
+      # @param query_logger [Array<String>]
+      #
+      def run(rows, query_logger: nil)
+        query(rows) { |scope|
+          assoc_rows = Query.new(scope, use: @use, query_logger: query_logger, &@eval_block).run
+          merge! assoc_rows, rows
+        }
+      end
+
+      private
+
       #
       # Yield ActiveRecord::Relations to the given block, one for every "type" represented in the given rows.
       #

data/lib/occams-record/raw_query.rb

@@ -49,8 +49,8 @@ module OccamsRecord
     # @return [Hash]
     attr_reader :binds
 
-    include EagerLoaders::Builder
     include Batches
+    include EagerLoaders::Builder
 
     #
     # Initialize a new query.
@@ -61,7 +61,7 @@ module OccamsRecord
     # @param eager_loaders [OccamsRecord::EagerLoaders::Base]
     # @param query_logger [Array] (optional) an array into which all queries will be inserted for logging/debug purposes
     #
-    def initialize(sql, binds, use: nil, eager_loaders: [], query_logger: nil)
+    def initialize(sql, binds, use: nil, eager_loaders: [], query_logger: nil, &eval_block)
       @sql = sql
       @binds = binds
       @use = use
@@ -69,6 +69,7 @@ module OccamsRecord
       @query_logger = query_logger
       @model = nil
       @conn = @model&.connection || ActiveRecord::Base.connection
+      instance_eval(&eval_block) if eval_block
     end
 
     #
@@ -92,7 +93,9 @@ module OccamsRecord
     # @return [Array<OccamsRecord::Results::Row>]
     #
     def run
-      result = @conn.exec_query escaped_sql
+      _escaped_sql = escaped_sql
+      @query_logger << _escaped_sql if @query_logger
+      result = @conn.exec_query _escaped_sql
       row_class = OccamsRecord::Results.klass(result.columns, result.column_types, @eager_loaders.map(&:name), model: @model, modules: @use)
       rows = result.rows.map { |row| row_class.new row }
       eager_load! rows

data/lib/occams-record/version.rb

@@ -3,5 +3,5 @@
 #
 module OccamsRecord
   # Library version
-  VERSION = '0.14.0'.freeze
+  VERSION = '0.15.0'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: occams-record
 version: !ruby/object:Gem::Version
-  version: 0.14.0
+  version: 0.15.0
 platform: ruby
 authors:
 - Jordan Hollinger
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-03-19 00:00:00.000000000 Z
+date: 2018-03-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -41,6 +41,9 @@ files:
 - lib/occams-record.rb
 - lib/occams-record/batches.rb
 - lib/occams-record/eager_loaders.rb
+- lib/occams-record/eager_loaders/ad_hoc_base.rb
+- lib/occams-record/eager_loaders/ad_hoc_many.rb
+- lib/occams-record/eager_loaders/ad_hoc_one.rb
 - lib/occams-record/eager_loaders/base.rb
 - lib/occams-record/eager_loaders/belongs_to.rb
 - lib/occams-record/eager_loaders/habtm.rb