occams-record 1.7.0 → 1.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5f2590ba264934763d86310d4cd9b92459cb053589afa23fb4ea4c4b423f2eb7
-  data.tar.gz: abb8aad716399e6b87d351e33a8f9ff629256964aed2f131795255cec3353b2a
+  metadata.gz: 846af974c8bc267fe8e901995d0aa3341b018d135eeb267c11d9add447cd0155
+  data.tar.gz: 763f8a038908cb9a990bcf305644661736dd9133e51a9d8fb8ece2b8ff018fd2
 SHA512:
-  metadata.gz: 2aa46cce2b26cd5a6e0219651dcdace5391a7a1b67ae5d4e6c3a9a849c6b12a63a2c913208af0ae58d5e7c7ce6880fdc2c1081a3a4b7582b2a8300f76548c0e3
-  data.tar.gz: c3cdc38d42b7c97894bbe34215e9a8143209732c78fd8b5d8351932d5e7290783ec8239c8f5c21e6fa4f2f36325b97a76088953a9b0a28a7fd71c697aaa91993
+  metadata.gz: 24e1c5dfb09cb35b2b7116cb40aafcb1eb215ac96e3c8bab7ff6558598b31e8abb77b49c2b711392567862b182e1aed705888e939f8b66f15285f2ca352dbc89
+  data.tar.gz: 04f78d14765b6ae4d9ccee5f01633132ed1e39662071dfc39f6e33583e9cd3e6214841225eb35ce2f678472ce34bf45e27e23660114f28cede6a27cdb38613b0

data/README.md

@@ -11,120 +11,33 @@ OccamsRecord is a high-efficiency, advanced query library for use alongside Acti
 * 3x-5x faster than ActiveRecord queries, *minimum*.
 * Uses 1/3 the memory of ActiveRecord query results.
 * Eliminates the N+1 query problem. (This often exceeds the baseline 3x-5x gain.)
-* Support for cursors (Postgres only, new in v1.4.0)
 
 ### 2) Supercharged querying & eager loading
 
-Continue using ActiveRecord's query builder, but let Occams take over running them, eager loading, and raw SQL calls. None of the examples below are possible with ActiveRecord, but OccamsRecord makes them trivial. (More complete examples are shown later, but these should whet your appetite.)
-
-**Customize the SQL used to eager load associations**
-
-```ruby
-OccamsRecord
-  .query(User.active)
-  .eager_load(:orders) { |l|
-    l.scope { |q| q.where("created_at >= ?", date).order("created_at DESC") }
-  }
-```
-
-**Use `ORDER BY` with `find_each`/`find_in_batches`**
-
-```ruby
-OccamsRecord
-  .query(Order.order("created_at DESC"))
-  .find_each { |order|
-    ...
-  }
-```
-
-**Use cursors**
-
-```ruby
-OccamsRecord
-  .query(Order.order("created_at DESC"))
-  .find_each_with_cursor { |order|
-    ...
-  }
-```
-
-**Use `find_each`/`find_in_batches` with raw SQL**
-
-```ruby
-OccamsRecord
-  .sql("
-    SELECT * FROM orders
-    WHERE created_at >= %{date}
-    LIMIT %{batch_limit}
-    OFFSET %{batch_offset}",
-    {date: 10.years.ago}
-  )
-  .find_each { |order|
-    ...
-  }
-```
-
-**Eager load associations when you're writing raw SQL**
-
-```ruby
-OccamsRecord
-  .sql("
-    SELECT * FROM users
-    LEFT OUTER JOIN ...
-  ")
-  .model(User)
-  .eager_load(:orders)
-```
-
-**Use `pluck` with raw SQL**
-
-```ruby
-OccamsRecord
-  .sql("
-    SELECT some_col FROM users
-    INNER JOIN ...
-  ")
-  .pluck(:some_col)
-```
-
-**Eager load "ad hoc associations" using raw SQL**
-
-Relationships are complicated, and sometimes they can't be expressed in ActiveRecord models. Define your relationship on the fly!
-(Don't worry, there's a full explanation later on.)
-
-```ruby
-OccamsRecord
-  .query(User.all)
-  .eager_load_many(:orders, {:id => :user_id}, "
-    SELECT user_id, orders.*
-    FROM orders INNER JOIN ...
-    WHERE user_id IN (%{ids})
-  ")
-```
+* Customize the SQL used to eager load associations (order them, apply filters, etc)
+* Use cursors (Postgres only)
+* Use `ORDER BY` with `find_each`/`find_in_batches`
+* Use `find_each`/`find_in_batches` with raw SQL
+* Eager load associations off of raw SQL queries
+* Use `pluck` with raw SQL queries
 
+### How does OccamsRecord do all this?
 [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:**
 
 * OccamsRecord results are *read-only*.
 * OccamsRecord results are *purely database rows* - they don't have any instance methods from your Rails models.
-* You *must eager load* each assocation you intend to use. If you forget one, an exception will be raised.
+* You *must eager load* each assocation you intend to use. If you try to use one you didn't eager load, an exception will be raised.
 
----
+# Overview
 
-# Installation
+Full documentation is available at [rubydoc.info/gems/occams-record](http://www.rubydoc.info/gems/occams-record). Code lives at at [github.com/jhollinger/occams-record](https://github.com/jhollinger/occams-record). Contributions welcome!
 
-Simply add it to your `Gemfile`:
+Simply add `occams-record` to your `Gemfile`:
 
 ```ruby
 gem 'occams-record'
 ```
 
----
-
-# Overview
-
-Full documentation is available at [rubydoc.info/gems/occams-record](http://www.rubydoc.info/gems/occams-record).
-
-Code lives at at [github.com/jhollinger/occams-record](https://github.com/jhollinger/occams-record). Contributions welcome!
-
 Build your queries like normal, using ActiveRecord's excellent query builder. Then pass them off to Occams Record.
 
 ```ruby
@@ -371,7 +284,6 @@ The following ActiveRecord features are under consideration, but not high priori
 The following ActiveRecord features are not supported, and likely never will be. Pull requests are still welcome, though.
 
 * Eager loading `through` associations that involve a polymorphic association.
-* ActiveRecord enum types
 * ActiveRecord serialized types
 
 ---

data/lib/occams-record/pluck.rb

@@ -2,13 +2,54 @@ module OccamsRecord
   module Pluck
     private
 
-    def pluck_results(results, cols)
+    def pluck_results(results, cols, model: nil)
       if cols.size == 1
-        col = cols[0].to_s
+        pluck_results_single(results, cols[0].to_s, model: model)
+      else
+        pluck_results_multi(results, cols.map(&:to_s), model: model)
+      end
+    end
+
+    # returns an array of values
+    def pluck_results_single(results, col, model: nil)
+      enum = model&.defined_enums&.[](col)
+      inv_enum = enum&.invert
+      if enum
+        results.map { |r|
+          val = r[col]
+          enum.has_key?(val) ? val : inv_enum[val]
+        }
+      else
+        # micro-optimization for when there are no enums
         results.map { |r| r[col] }
+      end
+    end
+
+    # returns an array of arrays
+    def pluck_results_multi(results, cols, model: nil)
+      any_enums = false
+      cols_with_enums = cols.map { |col|
+        enum = model&.defined_enums&.[](col)
+        any_enums ||= !!enum
+        [col, enum, enum&.invert]
+      }
+
+      if any_enums
+        results.map { |row|
+          cols_with_enums.map { |(col, enum, inv_enum)|
+            if enum
+              val = row[col]
+              enum.has_key?(val) ? val : inv_enum[val]
+            else
+              row[col]
+            end
+          }
+        }
       else
-        cols = cols.map(&:to_s)
-        results.map { |r| r.values_at(*cols) }
+        # micro-optimization for when there are no enums
+        results.map { |row|
+          cols.map { |col| row[col] }
+        }
       end
     end
   end

data/lib/occams-record/query.rb

@@ -96,6 +96,8 @@ module OccamsRecord
     #
     def run
       sql = block_given? ? yield(scope).to_sql : scope.to_sql
+      return [] if sql.blank? # return early in case ActiveRecord::QueryMethods#none was used
+
       @query_logger << "#{@eager_loaders.tracer}: #{sql}" if @query_logger
       result = if measure?
                  record_start_time!
@@ -237,6 +239,8 @@ module OccamsRecord
     #
     def pluck(*cols)
       sql = (block_given? ? yield(scope).to_sql : scope).select(*cols).to_sql
+      return [] if sql.blank? # return early in case ActiveRecord::QueryMethods#none was used
+
       @query_logger << "#{@eager_loaders.tracer}: #{sql}" if @query_logger
       result = if measure?
                  record_start_time!
@@ -246,7 +250,7 @@ module OccamsRecord
                else
                  model.connection.exec_query sql
                end
-      pluck_results result, cols
+      pluck_results result, cols, model: @model
     end
   end
 end

data/lib/occams-record/raw_query.rb

@@ -229,7 +229,7 @@ module OccamsRecord
                else
                  conn.exec_query _escaped_sql
                end
-      pluck_results result, cols
+      pluck_results result, cols, model: @eager_loaders.model
     end
 
     private

data/lib/occams-record/results/results.rb

@@ -54,16 +54,41 @@ module OccamsRecord
           # * MySQL ?
           #
           type = column_types[col] || model_column_types&.[](col)
+
+          #
+          # NOTE is also some variation in when enum values are mapped in different AR versions.
+          # In >=5.0, <=7.0, ActiveRecord::Result objects contain the human-readable values. In 4.2 and
+          # pre-release versions of 7.1, they instead have the RAW values (e.g. integers) which we must map ourselves.
+          #
+          enum = model&.defined_enums&.[](col)
+          inv_enum = enum&.invert
+
           case type&.type
           when nil
-            define_method(col) { @raw_values[idx] }
+            if enum
+              define_method(col) {
+                val = @raw_values[idx]
+                enum.has_key?(val) ? val : inv_enum[val]
+              }
+            else
+              define_method(col) { @raw_values[idx] }
+            end
           when :datetime
             define_method(col) { @cast_values[idx] ||= type.send(CASTER, @raw_values[idx])&.in_time_zone }
           when :boolean
             define_method(col) { @cast_values[idx] ||= type.send(CASTER, @raw_values[idx]) }
             define_method("#{col}?") { !!send(col) }
           else
-            define_method(col) { @cast_values[idx] ||= type.send(CASTER, @raw_values[idx]) }
+            if enum
+              define_method(col) {
+                @cast_values[idx] ||= (
+                  val = type.send(CASTER, @raw_values[idx])
+                  enum.has_key?(val) ? val : inv_enum[val]
+                )
+              }
+            else
+              define_method(col) { @cast_values[idx] ||= type.send(CASTER, @raw_values[idx]) }
+            end
           end
         end
       end

data/lib/occams-record/results/row.rb

@@ -40,7 +40,7 @@ module OccamsRecord
       #
       # Hash-like accessor for attributes and associations.
       #
-      # @param attr [String|Symbol\
+      # @param attr [String|Symbol]
       # @return [Object]
       #
       def [](attr)

data/lib/occams-record/version.rb

@@ -3,5 +3,5 @@
 #
 module OccamsRecord
   # @private
-  VERSION = "1.7.0".freeze
+  VERSION = "1.8.0".freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: occams-record
 version: !ruby/object:Gem::Version
-  version: 1.7.0
+  version: 1.8.0
 platform: ruby
 authors:
 - Jordan Hollinger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-03-28 00:00:00.000000000 Z
+date: 2023-07-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord