activerecord-has_some_of_many 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a519b095203661135d0889d1679af1641796fd1ad08f22ef7c98018a907e700b
+  data.tar.gz: 6619a47edd047b8fe5bbc4c8c1ecc7c1c8b0b0d4d97f5230019104e1f359f290
+SHA512:
+  metadata.gz: 166385a50777f3b578a0d14d880ccd878510545942cab07208cc8ca5f7ab88a86e448df460d591d90d2e2afd68f8de8b776b079b965052d12b51526753ae9aa3
+  data.tar.gz: 3d76b0b5882c2baa1c597fc69fdb6a302b56c011433d8e6df370f220d1280d1f42bc18186c8fec388d3f0819d60eeec108793e2118831d6dc6738013fb0e43bf

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright Ben Sheldon [he/him]
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,110 @@
+# `activerecord-has_some_of_many`
+
+This gem adds new optimized Active Record association methods (`has_one_of_many`, `has_some_of_many`) for "top N" queries to ActiveRecord using `JOIN LATERAL` that are eager-loadable (`includes(:association)`, `preloads(:association)`) to avoid N+1 queries, and is compatible with typical queries and batch methods (`find_each`, `in_batches`, find_in_batches`). For example, you might have these types of queries in your application:
+
+- Users have many posts, and you want to query the most recent post for each user 
+- Posts have many comments, and you want to query the 5 most recent visible comments for each post
+- Posts have many comments, and you want to query the one comment with the largest `votes_count` for each post
+
+You can read more about these types of queries on [Benito Serna's "Fetching the top n per group with a lateral join with rails"](https://bhserna.com/fetching-the-top-n-per-group-with-a-lateral-join-with-rails.html).
+
+## Usage
+
+Add to your gemfile, and run `bundle install`:
+
+```ruby
+  gem "activerecord-has_some_of_many"
+```
+
+Then you can use `has_one_of_many` and `has_some_of_many` in your ActiveRecord models to define these associations.
+
+```ruby
+class User < ActiveRecord::Base
+  has_one_of_many :last_post, -> { order("created_at DESC") }, class_name: "Post"
+
+  # You can also use `has_some_of_many` to get the top N records. Be sure to add a limit to the scope.
+  has_some_of_many :last_five_posts, -> { order("created_at DESC").limit(5) }, class_name: "Post"
+
+  # More complex scopees are possible, for example:
+  has_one_of_many :top_comment, -> { where(published: true).order("votes_count DESC") }, class_name: "Comment"
+  has_some_of_many :top_ten_comments, -> { where(published: true).order("votes_count DESC").limit(10) }, class_name: "Comment"
+end
+
+# And then preload/includes and use them like any other Rails association:
+User.where(active: true).includes(:last_post, :last_five_posts, :top_comment).each do |user|
+  user.last_post
+  user.last_five_posts
+  user.top_comment
+end
+
+# Aad compound indexes to your database to make these queries fast!
+add_index :comments, [:post_id, :created_at]
+add_index :comments, [:post_id, :votes_count]
+```
+
+## Why?
+
+Finding the "Top N" is a common problem, that can be easily solved with a `JOIN LATERAL` when writing raw SQL queries. Lateral Joins were introduced in Postgres 9.3: 
+
+> a LATERAL join is like a SQL foreach loop, in which Postgres will iterate over each row in a result set and evaluate a subquery using that row as a parameter. ([source](https://www.heap.io/blog/postgresqls-powerful-new-join-type-lateral))
+ 
+For example, to find only the one most recent comments for a collection of posts, we might write:
+
+```sql
+SELECT "comments".*
+FROM "posts"
+INNER JOIN LATERAL (
+    SELECT "comments".*
+    FROM "comments"
+    WHERE "comments"."post_id" = "posts"."id"
+    ORDER BY "comments"."created_at" DESC
+    LIMIT 1
+) lateral_table ON TRUE
+WHERE "posts"."id" IN (1, 2, 3, 4, 5)
+```
+
+Active Record associations present a bit of a challenge. This is because the association query has `WHERE` conditions added _after_ the association scope that allows changing the foreign key, but not the column name. This means that some indirection is necessary in order to make the query work and have the conditions applied to the correct column in a way that the query planner can efficiently understand and optimize:
+
+```SQL
+SELECT "comments".*
+FROM (
+    SELECT
+        "posts"."id" AS post_id_alias,
+        "lateral_table".*
+    FROM "posts"
+    INNER JOIN LATERAL (
+        SELECT "comments".*
+        FROM "comments"
+        WHERE "comments"."post_id" = "posts"."id"
+        ORDER BY "comments"."created_at" DESC
+        LIMIT 1
+    ) lateral_table ON TRUE
+) comments
+WHERE "comments"."post_id_alias" IN (1, 2, 3, 4, 5)
+```
+
+The resulting optimized `EXPLAIN ANALYZE` looks like:
+
+```sql
+Nested Loop  (cost=0.56..41.02 rows=5 width=72) (actual time=0.058..0.082 rows=4 loops=1)
+  ->  Index Only Scan using posts_pkey on posts  (cost=0.28..17.46 rows=5 width=8) (actual time=0.022..0.027 rows=4 loops=1)
+        Index Cond: (id = ANY ('{1,2,3,4,5}'::bigint[]))
+        Heap Fetches: 0
+  ->  Limit  (cost=0.29..4.70 rows=1 width=64) (actual time=0.012..0.013 rows=1 loops=4)
+        ->  Index Scan Backward using index_comments_on_post_id_and_created_at on comments  (cost=0.29..44.46 rows=10 width=64) (actual time=0.012..0.012 rows=1 loops=4)
+              Index Cond: (post_id = posts.id)
+Planning Time: 0.200 ms
+Execution Time: 0.106 ms
+```
+
+## History
+
+Back in 2018 I (Ben Sheldon) was working to speed up [Open311 Status](https://status.open311.org), an uptime and performance monitor for government websites; I was using a Window Function at the time to query the most recent status for each monitored website, and it was _slow_ 🐌 I [tweeted about the problem](https://x.com/postgresql/status/1033797250936389633) and the Postgres Twitter account replied and told me about `LATERAL` joins ✨
+
+![Tweet from Postgres](history.jpg)
+
+A few years after that, Benito Serna shared on Reddit an excellent series of blog posts about fetching latest-N-of-each records. The first post didn't mention `LATERAL` joins, so [I commented on that](https://www.reddit.com/r/rails/comments/kmofhp/comment/ghnf0hy/) and he updated the posts to include it 🙌 Since then it's been a go-to reference for these types of queries.
+
+## Development
+
+- Run the tests with `bundle exec rake`

data/lib/activerecord/has_some_of_many/associations.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module HasSomeOfMany
+    module Associations
+      extend ActiveSupport::Concern
+
+      # @param [ActiveRecord::Base] klass The primary class
+      # @param [Symbol] association_type For example, `:has_one` or `:has_many`
+      # @param [Symbol] name The name of the association
+      # @param [Proc, nil] scope A scope to apply to the association
+      # @param [Hash] options Additional options to pass to the association
+      def self.build(klass, association_type, name, scope = nil, **options)
+        primary_key = options[:primary_key] || klass.primary_key
+        foreign_key = options[:foreign_key] || ActiveSupport::Inflector.foreign_key(klass, true)
+        foreign_key_alias = options[:foreign_key_alias] || "#{foreign_key}_alias"
+
+        lateral_subselection_scope = lambda do
+          relation = scope ? instance_exec(&scope) : self
+          limit = association_type == :has_one ? 1 : nil
+          ActiveRecord::HasSomeOfMany::Associations.build_scope(klass, relation, primary_key: primary_key, foreign_key: foreign_key, foreign_key_alias: foreign_key_alias, limit: limit)
+        end
+
+        options[:primary_key] = primary_key
+        options[:foreign_key] = foreign_key_alias
+
+        klass.send(association_type, name, lateral_subselection_scope, **options)
+      end
+
+      def self.build_scope(klass, relation, primary_key:, foreign_key:, foreign_key_alias:, limit: nil)
+        lateral_table = Arel::Table.new('lateral_table')
+        subselect = klass.unscope(:select, :joins, :where, :order, :limit)
+                      .select(klass.arel_table[primary_key].as(foreign_key_alias), lateral_table[Arel.star])
+                      .arel.join(
+                        relation
+                          .where(relation.arel_table[foreign_key].eq(klass.arel_table[primary_key]))
+                          .then { |query| limit ? query.limit(limit) : query }
+                          .arel.lateral(lateral_table.name)
+                      ).on("TRUE")
+
+        select_values = if relation.klass.ignored_columns.any?
+                          [relation.klass.arel_table[foreign_key_alias]] + relation.klass.columns.map { |column| relation.klass.arel_table[column.name] }
+                        else
+                          [relation.klass.arel_table[Arel.star]]
+                        end
+
+        relation.klass.select(select_values).from(subselect.as(relation.arel_table.name))
+      end
+
+      class_methods do
+        # Fetch the first record of a has_one-like association using a lateral join
+        #
+        # @example Given posts have many comments; query the most recent comment on a post
+        #   class Post < ApplicationRecord
+        #     one_of_many :last_comment, -> { order(created_at: :desc) }, class_name: 'Comment'
+        #   end
+        #
+        #   Post.published.includes(:last_comment).each do |post
+        #     posts.last_comment # => #<Comment>
+        #   end
+        def has_one_of_many(name, scope = nil, **options)
+          ActiveRecord::HasSomeOfMany::Associations.build(self, :has_one, name, scope, **options)
+        end
+
+        # Fetch a limited number of records of a has_many-like association using a lateral join
+        #
+        # @example The 10 most recent comments on a post
+        #   class Post < ApplicationRecord
+        #     has_some_of_many :last_ten_comments, -> { order(created_at: :desc).limit(10) }, class_name: 'Comment'
+        #   end
+        #
+        #   Post.published.includes(:last_ten_comments).each do |post
+        #     posts.last_ten_comments # => [#<Comment>, #<Comment>, ...]
+        #   end
+        def has_some_of_many(name, scope = nil, **options)
+          ActiveRecord::HasSomeOfMany::Associations.build(self, :has_many, name, scope, **options)
+        end
+      end
+    end
+  end
+end

data/lib/activerecord/has_some_of_many/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module HasSomeOfMany
+    VERSION = "1.0.0"
+  end
+end

data/lib/activerecord-has_some_of_many.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require 'active_support/lazy_load_hooks'
+require_relative "version"
+
+ActiveSupport.on_load(:active_record) do
+  require_relative "activerecord/has_some_of_many/associations"
+  include ActiveRecord::HasSomeOfMany::Associations
+end

metadata

@@ -0,0 +1,66 @@
+--- !ruby/object:Gem::Specification
+name: activerecord-has_some_of_many
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Ben Sheldon [he/him]
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-07-31 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.0.0.alpha
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.0.0.alpha
+description: An Active Record extension for creating associations through lateral
+  joins
+email:
+- bensheldon@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/activerecord-has_some_of_many.rb
+- lib/activerecord/has_some_of_many/associations.rb
+- lib/activerecord/has_some_of_many/version.rb
+homepage: https://github.com/bensheldon/activerecord-has_some_of_many
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/bensheldon/activerecord-has_some_of_many
+  source_code_uri: https://github.com/bensheldon/activerecord-has_some_of_many
+  changelog_uri: https://github.com/bensheldon/activerecord-has_some_of_many
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.11
+signing_key:
+specification_version: 4
+summary: An Active Record extension for creating associations through lateral joins
+test_files: []