occams-record 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7363e28e8ba4c2d1fbbec8ea67e9cdbcfc9b1645
-  data.tar.gz: 5878b150352c20bcce6e88c831d361402c04e3ec
+  metadata.gz: f60c7e2adfe9a547efe1d4c9eccd25b8baa7c733
+  data.tar.gz: 7955381fac5f5792b7e9a537dd5962199dff7116
 SHA512:
-  metadata.gz: 7b9f69f663aed9de81807318203acc190930c29eff65e0c8dd82a6d3740f85cd6716ac0a8c588b67a082c5b93f6467fa76513be582c20f0f730b33410aeb4700
-  data.tar.gz: b041632604fddd68ee0249e235b92973da897a4a1aefa7f312b18b58a856f2471c0d29506421aa0fbbce30fe8c5b71d99d443024c64f68304672baab74e43be9
+  metadata.gz: 2e47c6911ac5648a01c9feeadcee5c1dd1e0a3d5dc9b475108bbbb86a6e06a87f31863521862ee6c807c33e85b34b793a9469188c1d72789d2cb389d088cdaf7
+  data.tar.gz: 0a35392419e4527552da87d433754d0a2998d016d5a27f332f78d6932605cdb856e256175d06cfbd9f8c214bd4908b5ed6d8455c38169f0568c3ad4ac5442ce0

data/README.md

@@ -2,18 +2,22 @@
 
 > Do not multiply entities beyond necessity. -- Occam's Razor
 
-EXPERIMENTAL. Occam's Record is a high-efficiency API for querying large sets with ActiveRecord. When loading thousands of records, ActiveRecord wastes a lot of RAM and CPU cycles on *things you'll never use.* Additionally, eagerly-loaded associations are forced to load each and every column, even if you only need a few.
+Occam's Record is a high-efficiency query API for ActiveRecord. When loading thousands of records, ActiveRecord wastes a lot of RAM and CPU cycles on *things you'll never use.* Additionally, eagerly-loaded associations are forced to load each and every column, even if you only need a few.
 
 For those stuck with ActiveRecord, OccamsRecord seeks to solve these issues by making some very specific trade-offs:
 
 * OccamsRecord results are **read-only**.
 * OccamsRecord objects are **purely database rows** - they don't have any instance methods from your Rails models.
+* OccamsRecord queries must specify each association that will be used. Otherwise they simply won't be availble.
 
 **What does this buy you?**
 
 * OccamsRecord results are **one-third the size** of ActiveRecord results.
 * OccamsRecord queries run **three to five times faster** than ActiveRecord queries.
-* When you're eager loading associations you may specify which columns to `SELECT`. (This can be a significant performance boost to both your database and Rails app, on top of the above numbers.)
+* When eager loading associations you may specify which columns to `SELECT`. (This can be a significant performance boost to both your database and Rails app, on top of the above numbers.)
+* When eager loading associations you may completely customize the query (`WHERE`, `ORDER BY`, `LIMIT`, etc.)
+* By forcing eager loading of associations, OccamsRecord bypasses the primary cause of performance problems in Rails: N+1 queries.
+* The forced eager loading helps the developer visualize the "shape" of the query/result, which can make obvious certain insights that would otherwise require lots of digging. For example, if you're eager loading 15 associations, maybe you need to add some redundant foreign keys or denormalize some fields.
 
 **What don't you give up?**
 
@@ -25,6 +29,10 @@ For those stuck with ActiveRecord, OccamsRecord seeks to solve these issues by m
 
 Glad you asked. [Look over the results yourself.](https://github.com/jhollinger/occams-record/wiki/Measurements)
 
+**Why not use a different ORM?**
+
+That's a great idea; check out [sequel](https://rubygems.org/gems/sequel) or [rom](https://rubygems.org/gems/rom)! But for large, legacy codebases heavily invested in ActiveRecord, switching ORMs often isn't practical. OccamsRecord can help you get some of those wins without throwing everything out.
+
 ## Usage
 
 **Add to your Gemfile**

data/lib/occams-record.rb

@@ -1,5 +1,6 @@
 require 'active_record'
 require 'occams-record/version'
+require 'occams-record/merge'
 require 'occams-record/eager_loaders'
 require 'occams-record/result_row'
 require 'occams-record/query'

data/lib/occams-record/batches.rb

@@ -1,12 +1,15 @@
 module OccamsRecord
   #
-  # Methods for building batch finding methods.
+  # Methods for building batch finding methods. It expects "model" and "scope" methods to be present.
   #
   module Batches
     #
     # Load records in batches of N and yield each record to a block if given.
     # If no block is given, returns an Enumerator.
     #
+    # NOTE Unlike ActiveRecord's find_each, order IS respected. The primary key will be appended
+    # to the ORDER BY clause to help ensure consistent batches.
+    #
     # @param batch_size [Integer]
     # @return [Enumerator] will yield each record
     #
@@ -27,6 +30,9 @@ module OccamsRecord
     # Load records in batches of N and yield each batch to a block if given.
     # If no block is given, returns an Enumerator.
     #
+    # NOTE Unlike ActiveRecord's find_in_batches, order IS respected. The primary key will be appended
+    # to the ORDER BY clause to help ensure consistent batches.
+    #
     # @param batch_size [Integer]
     # @return [Enumerator] will yield each batch
     #
@@ -44,7 +50,7 @@ module OccamsRecord
     #
     # Returns an Enumerator that yields batches of records, of size "of".
     # NOTE ActiveRecord 5+ provides the 'in_batches' method to do something
-    # similiar, but 4.2 doesn't have it, so...
+    # similiar, although 4.2 does not. Also it does not respect ORDER BY.
     #
     # @param of [Integer] batch size
     # @return [Enumerator] yields batches
@@ -58,7 +64,7 @@ module OccamsRecord
 
         until out_of_records
           l = limit && batch_size > limit - count ? limit - count : batch_size
-          q = scope.offset(offset).limit(l)
+          q = scope.order(model.primary_key.to_sym).offset(offset).limit(l)
           results = Query.new(q, use: @use, query_logger: @query_logger, eager_loaders: @eager_loaders).run
 
           y.yield results if results.any?

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

@@ -20,7 +20,6 @@ module OccamsRecord
       def initialize(ref, scope = nil, use = nil, &eval_block)
         @ref, @scope, @use, @eval_block = ref, scope, use, eval_block
         @name, @model = ref.name.to_s, ref.klass
-        @assign = "#{@name}="
       end
 
       #

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

@@ -19,17 +19,8 @@ module OccamsRecord
       # @param rows [Array<OccamsRecord::ResultRow>] rows loaded from the main model
       #
       def merge!(assoc_rows, rows)
-        pkey_col = @model.primary_key.to_s
-        assoc_rows_by_id = assoc_rows.reduce({}) { |a, assoc_row|
-          id = assoc_row.send pkey_col
-          a[id] = assoc_row
-          a
-        }
-
-        rows.each do |row|
-          fkey = row.send @ref.foreign_key
-          row.send @assign, fkey ? assoc_rows_by_id[fkey] : nil
-        end
+        Merge.new(rows, name).
+          single!(assoc_rows, @ref.foreign_key.to_s, @model.primary_key.to_s)
       end
     end
   end

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

@@ -32,11 +32,12 @@ module OccamsRecord
           a
         }
 
+        assign = "#{name}="
         rows.each do |row|
           id = row.send(@ref.active_record_primary_key).to_s
           assoc_fkeys = (joins_by_id[id] || []).uniq
           associations = assoc_rows_by_id.values_at(*assoc_fkeys).compact.uniq
-          row.send @assign, associations
+          row.send assign, associations
         end
       end
 

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

@@ -9,11 +9,8 @@ module OccamsRecord
       # @param rows [Array<OccamsRecord::ResultRow>] rows loaded from the main model
       #
       def merge!(assoc_rows, rows)
-        assoc_rows_by_fkey = assoc_rows.group_by(&@ref.foreign_key.to_sym)
-        rows.each do |row|
-          pkey = row.send @ref.active_record_primary_key
-          row.send @assign, assoc_rows_by_fkey[pkey] || []
-        end
+        Merge.new(rows, name).
+          many!(assoc_rows, @ref.active_record_primary_key, @ref.foreign_key)
       end
     end
   end

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

@@ -8,6 +8,7 @@ module OccamsRecord
       # @param rows [Array<OccamsRecord::ResultRow>] Array of rows used to calculate the query.
       #
       def query(rows)
+        return if rows.empty?
         ids = rows.map { |r| r.send @ref.active_record_primary_key }.compact.uniq
         q = base_scope.where(@ref.foreign_key => ids)
         q.where!(@ref.type => rows[0].class.try!(:model_name)) if @ref.options[:as]
@@ -21,18 +22,8 @@ module OccamsRecord
       # @param rows [Array<OccamsRecord::ResultRow>] rows loaded from the main model
       #
       def merge!(assoc_rows, rows)
-        fkey_col = @ref.foreign_key.to_s
-        assoc_rows_by_fkey = assoc_rows.reduce({}) { |a, assoc_row|
-          fid = assoc_row.send fkey_col
-          a[fid] = assoc_row
-          a
-        }
-
-        pkey_col = @ref.active_record_primary_key.to_s
-        rows.each do |row|
-          pkey = row.send pkey_col
-          row.send @assign, pkey ? assoc_rows_by_fkey[pkey] : nil
-        end
+        Merge.new(rows, name).
+          single!(assoc_rows, @ref.active_record_primary_key.to_s, @ref.foreign_key.to_s)
       end
     end
   end

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

@@ -16,11 +16,10 @@ module OccamsRecord
       # @param eval_block [Proc] a block where you may perform eager loading on *this* association (optional)
       #
       def initialize(ref, scope = nil, use = nil, &eval_block)
-        @ref, @name, @scope, @eval_block = ref, ref.name.to_s, scope, eval_block
+        @ref, @scope, @use, @eval_block = ref, scope, use, eval_block
+        @name = ref.name.to_s
         @foreign_type = @ref.foreign_type.to_sym
         @foreign_key = @ref.foreign_key.to_sym
-        @use = use
-        @assign = "#{@name}="
       end
 
       #
@@ -45,7 +44,9 @@ module OccamsRecord
         return if assoc_rows_of_type.empty?
         type = assoc_rows_of_type[0].class.model_name
         rows_of_type = rows.select { |r| r.send(@foreign_type) == type }
-        merge_model!(assoc_rows_of_type, rows_of_type, type.constantize)
+        model = type.constantize
+        Merge.new(rows_of_type, name).
+          single!(assoc_rows_of_type, @ref.foreign_key.to_s, model.primary_key.to_s)
       end
 
       private
@@ -56,20 +57,6 @@ module OccamsRecord
         q = q.instance_exec(&@scope) if @scope
         q
       end
-
-      def merge_model!(assoc_rows, rows, model)
-        pkey_col = model.primary_key.to_s
-        assoc_rows_by_id = assoc_rows.reduce({}) { |a, assoc_row|
-          id = assoc_row.send pkey_col
-          a[id] = assoc_row
-          a
-        }
-
-        rows.each do |row|
-          fkey = row.send @ref.foreign_key
-          row.send @assign, fkey ? assoc_rows_by_id[fkey] : nil
-        end
-      end
     end
   end
 end

data/lib/occams-record/merge.rb

@@ -0,0 +1,57 @@
+module OccamsRecord
+  #
+  # Represents a merge operation to be performed. Merges are always "left" merges. You initialize the
+  # Merge with the "left" records, and the name of the attribute into which "right" records will be placed.
+  #
+  # After initializing, perform a specific type of merge by calling the appropriate *! method.
+  #
+  class Merge
+    # @return [Array<OccamsRecord::ResultRow>] the rows into which associated rows will be merged
+    attr_reader :target_rows
+
+    #
+    # Initialize a new Merge operation.
+    #
+    # @param target_rows [Array<OccamsRecord::ResultRow] the rows into which associated rows should be merged
+    # @param assoc_name [String|Symbol] name of the attribute where associated rows will be put
+    #
+    def initialize(target_rows, assoc_name)
+      @target_rows = target_rows
+      @assign = "#{assoc_name}="
+    end
+
+    #
+    # Merge a single assoc_row into each target_rows (or nil if one can't be found).
+    # target_attr and assoc_attr are the matching keys on target_rows and assoc_rows, respectively.
+    #
+    # @param assoc_rows [Array<OccamsRecord::ResultRow>] rows to merge into target_rows
+    # @param target_attr [String|Symbol] name of the matching key on the target records
+    # @param assoc_attr [String] name of the matching key on the associated records
+    #
+    def single!(assoc_rows, target_attr, assoc_attr)
+      assoc_rows_by_id = assoc_rows.reduce({}) { |a, assoc_row|
+        id = assoc_row.send assoc_attr
+        a[id] = assoc_row
+        a
+      }
+
+      target_rows.each do |row|
+        attr = row.send target_attr
+        row.send @assign, attr ? assoc_rows_by_id[attr] : nil
+      end
+    end
+
+    #
+    # Merge an array of assoc_rows into the target_rows. Some target_rows may end up with 0 matching
+    # associations, and they'll be assigned empty arrays.
+    # target_attr and assoc_attr are the matching keys on target_rows and assoc_rows, respectively.
+    #
+    def many!(assoc_rows, target_attr, assoc_attr)
+      assoc_rows_by_attr = assoc_rows.group_by(&assoc_attr.to_sym)
+      target_rows.each do |row|
+        pkey = row.send target_attr
+        row.send @assign, assoc_rows_by_attr[pkey] || []
+      end
+    end
+  end
+end

data/lib/occams-record/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: occams-record
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Jordan Hollinger
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-09-09 00:00:00.000000000 Z
+date: 2017-09-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -47,6 +47,7 @@ files:
 - lib/occams-record/eager_loaders/has_many.rb
 - lib/occams-record/eager_loaders/has_one.rb
 - lib/occams-record/eager_loaders/polymorphic_belongs_to.rb
+- lib/occams-record/merge.rb
 - lib/occams-record/query.rb
 - lib/occams-record/result_row.rb
 - lib/occams-record/version.rb