occams-record 1.6.2 → 1.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6a233847b8c1a9de8c77e8c5e1d12f70ea7c8b9efa498208491a17ff09a6f217
-  data.tar.gz: f87fbaf43703cd29b60b94a480ad903d00cad2b9b3bd9bfb4a77b7748f68aa81
+  metadata.gz: 0dc125a06b3fa732e1064483f13e5abbe2a7c64b4e6ac7f1b2d37337d8e233cb
+  data.tar.gz: 5c47a9a644b757463d5dd1961c1b86ed1de50cf247a286e8d1d0c3dd5daa99b8
 SHA512:
-  metadata.gz: 21115e90f5f455eaf33d5c0596d6276957905fb14932583fcdfacdb1a44f7afeaee029458de903fa58c2801e7504643c6c6e4a530822409ff93da6954648a06e
-  data.tar.gz: a38eba237379a4a0b55d027746a8796f9aa9904e60bb1ba6acd6fd46348fc84e0aef17fc6de482d5b32d6677c09b2ea53602b000bf6da9a60d5bd2dec0e72b3f
+  metadata.gz: 7fb55ec18a98e4d2bb4b3fab8d3f609a378bee578d1b405d56a43b1f035f40d53149fc8dabc321bbaf17b180eb9e3b1dda282cc2fd8675a3e10c8bc59a9f7a59
+  data.tar.gz: f9f28ad1537cc297a0b5b1fe8a5209d4f4dfa4529148a603f715da884fa9d9f8188836aca84c8e5dcc36f674bb6abe7211de57c014e90a4539d892da0192c28d

data/README.md

@@ -2,6 +2,8 @@
 
 > Do not multiply entities beyond necessity. -- Occam's Razor
 
+Full documentation is available at [rubydoc.info/gems/occams-record](http://www.rubydoc.info/gems/occams-record).
+
 OccamsRecord is a high-efficiency, advanced query library for use alongside ActiveRecord. It is **not** an ORM or an ActiveRecord replacement. OccamsRecord can breathe fresh life into your ActiveRecord app by giving it two things:
 
 ### 1) Huge performance gains
@@ -9,109 +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)
-```
-
-**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

data/lib/occams-record/pluck.rb

@@ -0,0 +1,15 @@
+module OccamsRecord
+  module Pluck
+    private
+
+    def pluck_results(results, cols)
+      if cols.size == 1
+        col = cols[0].to_s
+        results.map { |r| r[col] }
+      else
+        cols = cols.map(&:to_s)
+        results.map { |r| r.values_at(*cols) }
+      end
+    end
+  end
+end

data/lib/occams-record/query.rb

@@ -36,6 +36,7 @@ module OccamsRecord
     attr_reader :scope
 
     include OccamsRecord::Batches::CursorHelpers
+    include OccamsRecord::Pluck
     include EagerLoaders::Builder
     include Enumerable
     include Measureable
@@ -95,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!
@@ -225,5 +228,29 @@ module OccamsRecord
         use: @use, query_logger: @query_logger, eager_loaders: @eager_loaders,
       )
     end
+
+    #
+    # Returns the specified column(s) as an array of values.
+    #
+    # If more than one column is given, the result will be an array of arrays.
+    #
+    # @param cols [Array] one or more column names as Symbols or Strings. Also accepts SQL functions, e.g. "LENGTH(name)".
+    # @return [Array]
+    #
+    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!
+                 measure!(model.table_name, sql) {
+                   model.connection.exec_query sql
+                 }
+               else
+                 model.connection.exec_query sql
+               end
+      pluck_results result, cols
+    end
   end
 end

data/lib/occams-record/raw_query.rb

@@ -62,6 +62,7 @@ module OccamsRecord
     attr_reader :binds
 
     include OccamsRecord::Batches::CursorHelpers
+    include OccamsRecord::Pluck
     include EagerLoaders::Builder
     include Enumerable
     include Measureable
@@ -209,6 +210,28 @@ module OccamsRecord
       )
     end
 
+    #
+    # Returns the specified column(s) as an array of values.
+    #
+    # If more than one column is given, the result will be an array of arrays.
+    #
+    # @param cols [Array] one or more column names as Symbols or Strings. Also accepts SQL functions, e.g. "LENGTH(name)".
+    # @return [Array]
+    #
+    def pluck(*cols)
+      _escaped_sql = escaped_sql
+      @query_logger << _escaped_sql if @query_logger
+      result = if measure?
+                 record_start_time!
+                 measure!(table_name, _escaped_sql) {
+                   conn.exec_query _escaped_sql
+                 }
+               else
+                 conn.exec_query _escaped_sql
+               end
+      pluck_results result, cols
+    end
+
     private
 
     # Returns the SQL as a String with all variables escaped

data/lib/occams-record/version.rb

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

data/lib/occams-record.rb

@@ -5,6 +5,7 @@ require 'occams-record/measureable'
 require 'occams-record/eager_loaders/eager_loaders'
 require 'occams-record/results/results'
 require 'occams-record/results/row'
+require 'occams-record/pluck'
 require 'occams-record/cursor'
 require 'occams-record/errors'
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: occams-record
 version: !ruby/object:Gem::Version
-  version: 1.6.2
+  version: 1.7.1
 platform: ruby
 authors:
 - Jordan Hollinger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-02-21 00:00:00.000000000 Z
+date: 2023-05-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -74,6 +74,7 @@ files:
 - lib/occams-record/errors.rb
 - lib/occams-record/measureable.rb
 - lib/occams-record/merge.rb
+- lib/occams-record/pluck.rb
 - lib/occams-record/query.rb
 - lib/occams-record/raw_query.rb
 - lib/occams-record/results/results.rb