activerecord-refined 0.3.3 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f20876b4eb0b36ece84fc2f6a1c828461846b29bd829e279d31b22735cbf0c15
-  data.tar.gz: 4a717ffaf4991fa3a113ea4a6a619b16d431e8308e1869e22c988885022d450a
+  metadata.gz: b3818aa9d45162578a7a0f01eae7b45f943e2a2b1708ec689cd7ba484af9011e
+  data.tar.gz: 27674049c82ce8ba096f6a9416b603b25c97d326cb3ea78e557b43ffe76b25a0
 SHA512:
-  metadata.gz: 56734a22e7667270892abf1d6ab9fb0816a37043c5f1fe61a7367c40403f782af6dff7875b0f520ada5aef6ce89155f39919414a71d3abec279ccf3c538db578
-  data.tar.gz: f0aa350bbf6b80d1e36b156d2e997930195f2fcfe99c53ae449f3d0f44efe3870671c45bae52a7eac5f39c5f39adf129cbe5a1a1d3776b07eb8d29b1cfa470d2
+  metadata.gz: 6a3d6b39152e68a21a21a14abd1092484eb335137a182db8068396ef7fa98ca17bd4bb152b0b028bc3ef2e1de17e8d257dcdb03a57cf093a650f387196e22ee9
+  data.tar.gz: 5e44084905b8c8d22bdde49aad72ceab1b22b1be4e139e8f60237a134a05c258413503595af0f49409ac19923ed296ecbd3f7c075c64b20e6e61f8c2100e5dd3

data/.github/workflows/test.yml

@@ -7,10 +7,10 @@ on:
   pull_request:
 
 jobs:
-  test:
+  sqlite:
     runs-on: ubuntu-latest
     env:
-      # SQLite only here, so skip building the pg and mysql2 extensions.
+      # Nothing here loads pg or mysql2, so skip building the extensions.
       BUNDLE_WITHOUT: db
     steps:
       - uses: actions/checkout@v5
@@ -21,3 +21,57 @@ jobs:
           ruby-version: head
           bundler-cache: true
       - run: bundle exec rake test
+
+  postgresql:
+    runs-on: ubuntu-latest
+    env:
+      ADAPTER: postgresql
+      DB_USERNAME: postgres
+      DB_PASSWORD: postgres
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_PASSWORD: postgres
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+    steps:
+      - uses: actions/checkout@v5
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: head
+          bundler-cache: true
+      - run: bundle exec rake test
+
+  mysql:
+    runs-on: ubuntu-latest
+    env:
+      ADAPTER: mysql2
+      # The suite creates its own database, which MYSQL_USER would not be
+      # granted; root is the account that can.
+      DB_USERNAME: root
+      DB_PASSWORD: root
+    services:
+      mysql:
+        image: mysql:8
+        env:
+          MYSQL_ROOT_PASSWORD: root
+        ports:
+          - 3306:3306
+        options: >-
+          --health-cmd "mysqladmin ping -proot"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+    steps:
+      - uses: actions/checkout@v5
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: head
+          bundler-cache: true
+      - run: bundle exec rake test

data/LICENSE.txt

@@ -1,4 +1,5 @@
 Copyright (c) 2012 Akira Matsuda
+Copyright (c) 2026 Shugo Maeda
 
 MIT License
 
@@ -19,4 +20,4 @@ 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.
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -1,5 +1,6 @@
 # ActiveRecord::Refined
 
+[![gem](https://img.shields.io/gem/v/activerecord-refined.svg)](https://rubygems.org/gems/activerecord-refined)
 [![test](https://github.com/shugo/activerecord-refined/actions/workflows/test.yml/badge.svg)](https://github.com/shugo/activerecord-refined/actions/workflows/test.yml)
 
 Adding clean and powerful query syntax on ActiveRecord using refinements.
@@ -87,6 +88,15 @@ Author.where { :id.in?(Post.published.select(:author_id)) }
 # "authors"."id" IN (SELECT "posts"."author_id" FROM "posts" WHERE ...)
 ```
 
+A relation on the right of a comparison is a scalar subquery. It has to select
+one value, so unlike `in?` there is no default select list and one is
+required:
+
+```ruby
+Author.where { :age >= Author.select { avg(:age) } }
+# "authors"."age" >= (SELECT AVG("authors"."age") FROM "authors")
+```
+
 `exists?` takes a relation and becomes `EXISTS (SELECT ...)`. Correlate the
 subquery with the outer table through qualified columns — its `where` block
 goes through the DSL like any other:
@@ -100,7 +110,26 @@ Author.where { !exists?(Post.where { :posts[:author_id] == :authors[:id] }) }
 ```
 
 `like?` is case-sensitive `LIKE` on every adapter, including PostgreSQL, where
-Arel would otherwise reach for `ILIKE`.
+Arel would otherwise reach for `ILIKE`. `ilike?` is the one that asks for
+`ILIKE`; off PostgreSQL it is plain `LIKE`, which those adapters already match
+case-insensitively under their default collations. `casecmp?` is
+case-insensitive equality, folded on both sides rather than left to the
+collation, so it means the same thing everywhere:
+
+```ruby
+Author.where { :name.ilike?('ma%') }        # ILIKE 'ma%' / LIKE 'ma%'
+Author.where { :name.casecmp?('Matz') }     # LOWER(name) = LOWER('Matz')
+```
+
+`not_distinct_from?` and `distinct_from?` compare with NULL treated as a
+value, rather than as the unknown that makes `=` and `<>` neither true nor
+false. PostgreSQL spells this `IS [NOT] DISTINCT FROM`, SQLite `IS` / `IS NOT`
+and MySQL `<=>`, and the rows that come back are the same on all three:
+
+```ruby
+Author.where { :country.not_distinct_from?(params[:country]) }  # matches NULL to nil
+Author.where { :country.distinct_from?('JP') }                  # keeps the NULL rows
+```
 
 `start_with?`, `end_with?` and `include?` are shortcuts for the usual `like?`
 patterns. Unlike `like?`, they treat their argument as a literal string, so `%`
@@ -120,17 +149,24 @@ Author.where { :name.start_with?('A', 'B') }
 # (name LIKE 'A%' OR name LIKE 'B%')
 ```
 
-`member?` tests containment in a PostgreSQL array column. The two flavors of
-"does it contain this?" split by name the way Ruby's own classes do: `include?`
-is String's substring match, `member?` is Enumerable's element test, which
-String does not have. Pass an array to require every element:
+`member?`, `superset?`, `subset?` and `intersect?` compare against a
+PostgreSQL array column, each carrying the meaning of its Ruby namesake:
+`member?` is Enumerable's element test (which String does not have — that is
+what separates it from `include?`), `superset?` and `subset?` are Set's
+whole-array containment, and `intersect?` is Array's "any element in common":
 
 ```ruby
-Article.where { :tags.member?('ruby') }         # "tags" @> '{ruby}'
-Article.where { :tags.member?(%w[ruby rails]) } # "tags" @> '{ruby,rails}'
-Article.where { :scores.member?(80) }           # "scores" @> '{80}'
+Article.where { :tags.member?('ruby') }            # tags @> '{ruby}'
+Article.where { :scores.member?(80) }              # scores @> '{80}'
+Article.where { :tags.superset?(%w[ruby rails]) }  # tags @> '{ruby,rails}'
+Article.where { :tags.subset?(%w[ruby rails go]) } # tags <@ '{ruby,rails,go}'
+Article.where { :tags.intersect?(%w[ruby go]) }    # tags && '{ruby,go}'
 ```
 
+Like its namesake, `member?` takes one element — `[1, 2].member?([1])` is
+false in Ruby, so an Array argument raises rather than quietly meaning
+something `Array#member?` does not. Requiring every element is `superset?`.
+
 `=~` and `!~` match a regular expression: `REGEXP` and `NOT REGEXP` on MySQL,
 `~` and `!~` on PostgreSQL. SQLite has no regexp operator of its own, so it
 raises there.
@@ -155,8 +191,10 @@ Reservation.where { :period == (from...to) }   # daterange = '[from,to)'
 Article.where { :tags == %w[ruby rails] }      # text[] = '{ruby,rails}'
 ```
 
-For the same reason `== nil` raises `ArgumentError`: `= NULL` is never true in
-SQL, so a NULL test has to be spelled as one. Use `null?`:
+`!=` is SQL `!=` under the same rules, value passed through untouched.
+
+For the same reason `== nil` and `!= nil` raise `ArgumentError`: `= NULL` is
+never true in SQL, so a NULL test has to be spelled as one. Use `null?`:
 
 ```ruby
 Author.where { :country.null? }             # country IS NULL
@@ -186,18 +224,118 @@ Author.
 Author.left_outer_joins(:posts) { :posts[:author_id] == :authors[:id] }
 ```
 
+`as` names the table within the query, which is what makes a self join
+expressible — the qualified columns in the block go by that name:
+
+```ruby
+Employee.joins(:employees, as: :managers) { :managers[:id] == :employees[:manager_id] }
+# SELECT "employees".* FROM "employees"
+#   INNER JOIN "employees" "managers" ON "managers"."id" = "employees"."manager_id"
+```
+
+### Common table expressions
+
+ActiveRecord's `with` and `with_recursive` need nothing from this gem: a CTE
+is joined by name like any other table, so its `ON` clause is a block, where
+Rails' own documentation reaches for a string join.
+
+`from` takes the CTE's name as a symbol, with `as` to select it under the
+model's own table name so the model's columns resolve:
+
+```ruby
+Node.with_recursive(
+  tree: [
+    Node.where { :id == root.id },
+    Node.joins(:tree) { :nodes[:parent_id] == :tree[:id] },
+  ]
+).from(:tree, as: :nodes)
+# WITH RECURSIVE "tree" AS (
+#   SELECT "nodes".* FROM "nodes" WHERE "nodes"."id" = 1
+#   UNION ALL
+#   SELECT "nodes".* FROM "nodes" INNER JOIN "tree" ON "nodes"."parent_id" = "tree"."id"
+# ) SELECT "nodes".* FROM "tree" AS "nodes"
+```
+
+A non-recursive CTE joins the same way:
+
+```ruby
+Node.with(roots: Node.where { :parent_id.null? }).
+  joins(:roots) { :roots[:id] == :nodes[:parent_id] }
+```
+
+`examples/ctes.rb` walks a category tree with these.
+
 ### Aggregates, functions and aliases
 
-`count`, `sum`, `avg`, `min` and `max` are available as methods, as are the scalar
-functions `upper`, `lower`, `length`, `trim`, `coalesce`, `abs` and `round`. Use `.as`
-for a column alias, and `.asc` / `.desc` for the sort direction. Return an array to
-select or order by multiple expressions.
+`count`, `sum`, `avg`, `min` and `max` are available as methods, as are the
+scalar functions below, with `fn` for anything else. Use `.as` for a column
+alias, and `.asc` / `.desc` for the sort direction. Return an array to select
+or order by multiple expressions.
+
+The scalar functions are real methods rather than anything caught dynamically,
+so a misspelling is a `NoMethodError` where you wrote it, and a name Ruby also
+answers to — `rand` — means the SQL one inside a block:
+
+```
+abs  ceil  char_length  coalesce  concat  date_trunc  exp  floor  format
+greatest  least  length  ln  log  lower  ltrim  mod  now  nullif  power  rand
+replace  round  rtrim  sqrt  substr  trim  upper
+```
+
+Most are spelled the same everywhere. Where they are not, the method names one
+meaning and each adapter gets its own spelling: `char_length`, `greatest` and
+`least` become `LENGTH`, `MAX` and `MIN` on SQLite, and `rand` is `RAND` on
+MySQL and `RANDOM` elsewhere. Where an adapter has no equivalent — `date_trunc`
+outside PostgreSQL, `now` on SQLite — the block raises `NotImplementedError`
+rather than leaving the database to reject the SQL.
 
-Pass `:*` to `count` for `COUNT(*)`:
+`format` is printf formatting, and raises on MySQL, where a function of the
+same name does something else entirely: it puts separators in a number, and
+reads a printf template as the number zero rather than complaining. `fn` still
+reaches it, spelled as the different thing it is:
+
+```ruby
+Post.select { fn(:format, :amount, 2) }   # MySQL's, on purpose
+```
+
+Pass `:*` to `count` for `COUNT(*)`, and `distinct: true` for
+`COUNT(DISTINCT ...)`:
 
 ```ruby
 Author.group { :country }.having { count(:*) > 1 }
 # SELECT "authors".* FROM "authors" GROUP BY "authors"."country" HAVING COUNT(*) > 1
+
+Post.select { count(:author_id, distinct: true) }   # COUNT(DISTINCT "author_id")
+```
+
+Values are quoted by the adapter wherever they appear, as they are in
+ActiveRecord. Column aliases and `fn`'s function name are not — they are
+written into the SQL as given — so those two have to be plain names,
+optionally qualified by a schema in `fn`'s case. Anything else raises
+`ArgumentError` rather than reaching the query.
+
+`fn` reaches functions without a method of their own. Its name is emitted as
+written, so a case-sensitive one can be spelled exactly:
+
+```ruby
+Post.select { fn(:date_trunc, 'day', :created_at).as(:day) }
+# SELECT date_trunc('day', "posts"."created_at") AS day
+```
+
+`+`, `-`, `*` and `/` build arithmetic. Ruby puts them above the comparison
+operators, so an expression groups the way it reads:
+
+```ruby
+Item.where { :price * :quantity > 1000 }
+Item.select { sum(:price * :quantity).as(:total) }
+```
+
+`.asc` and `.desc` take `.nulls_first` / `.nulls_last`. MySQL has no such
+syntax, but Arel emulates it there, so the resulting order is the same
+everywhere:
+
+```ruby
+Author.order { :country.asc.nulls_last }
 ```
 
 ```ruby
@@ -216,7 +354,68 @@ Author.
   }
 ```
 
-See `examples/` for complete, runnable scripts.
+## Examples
+
+`examples/` holds runnable scripts, each printing the SQL it builds and, where
+the result is the point, the rows that come back. All but the last run against
+an in-memory SQLite database and need no setup.
+
+| | |
+| --- | --- |
+| `predicates.rb` | the `where` vocabulary: ranges, sets, NULL, text matching |
+| `subqueries.rb` | `in?` with a relation, `exists?`, scalar subqueries |
+| `expressions.rb` | arithmetic, aggregates, functions, `NULLS LAST` |
+| `complex_joins.rb` | compound `ON` clauses, outer joins, a self join |
+| `aggregations.rb` | `GROUP BY`, `HAVING` and aggregates across joins |
+| `ctes.rb` | `with` and `with_recursive` |
+| `postgresql.rb` | array columns, regular expressions, `ILIKE` (needs a server) |
+
+## Performance
+
+`benchmark/query_building.rb` compares building the same queries through the
+block DSL and through ActiveRecord's other argument styles. Only query
+construction (through `to_sql`) is measured — every style produces the same
+SQL, so execution costs the same regardless.
+
+Queries built per second (ruby 4.1.0dev, ActiveRecord 8.1.3, one machine —
+treat the ratios, not the absolute numbers, as the result):
+
+| query | string | arel | block (this gem) | hash | relation and/or |
+| --- | --- | --- | --- | --- | --- |
+| simple equality | 42.5k | 42.0k | 37.7k | 31.5k | — |
+| range (BETWEEN) | — | 34.6k | 32.7k | 24.8k | — |
+| LIKE | 41.5k | 41.0k | 36.8k | — | — |
+| compound AND/OR | 34.4k | 27.7k | 24.4k | — | 11.9k |
+
+Allocated memory per built query:
+
+| query | arel | block (this gem) | hash | string | relation and/or |
+| --- | --- | --- | --- | --- | --- |
+| simple equality | 2,600 B | 2,832 B | 3,328 B | 3,448 B | — |
+| compound AND/OR | 3,208 B | 3,584 B | — | 4,680 B | 9,120 B |
+
+In short: the block DSL is 6–13% slower than hand-written Arel (which it
+compiles to), a little faster than hash conditions, and both faster and
+leaner than `where(...).and(where(...).or(where(...)))` relation chains,
+which pay for structural-compatibility checks and relation copies. The
+`Proc#refined` call itself costs about 150 ns of the ~25 μs build — the
+re-interpretation of the block is not where the time goes. Against a
+database round trip of tens to hundreds of microseconds, none of these
+differences are visible in an application.
+
+One memory cost sits outside the per-query numbers above: to run a block
+under the refinements, `Proc#refined` deep-copies its instruction sequence,
+nested blocks included. The copy is made lazily on the refined proc's first
+call and memoized per block and refinement list for the life of the process,
+so it is paid once per `where { ... }` call site, not per query — the
+benchmark measures the copy at the size of the original (568 bytes for the
+simple-equality block, 888 bytes for the compound one), and a thousand
+further calls from the same call site copy nothing. Steady state, an
+application holds one extra copy of each distinct query block's bytecode:
+a few hundred bytes per call site. "Per call site" assumes blocks compiled
+once, as normal code is — building query blocks with a string `eval` mints
+a fresh instruction sequence per pass, each earning a copy of its own, and
+the memo keeps both alive for the life of the process.
 
 ## Running the tests
 
@@ -237,12 +436,15 @@ database is created on first use.
 
 The `pg` and `mysql2` gems are in the Gemfile's `db` group, since building them
 needs the client libraries installed. Skip them if SQLite is all you need,
-which is what CI does:
+which is what CI's SQLite job does:
 
 ```sh
 bundle config set --local without db
 ```
 
+CI runs all three, one job per adapter, with PostgreSQL and MySQL as service
+containers.
+
 ## Releasing
 
 Pushing a `v*` tag runs `.github/workflows/push_gem.yml`, which builds the gem

data/benchmark/query_building.rb

@@ -0,0 +1,129 @@
+# Compares the cost of building the same queries through this gem's block
+# DSL and through ActiveRecord's other argument styles: hash conditions,
+# string conditions, raw Arel, and relation and/or chains.  Only query
+# construction (through to_sql) is measured; every style produces the same
+# SQL, which the script prints first as a sanity check.
+#
+# Run without bundler, so the profiling gems don't need to live in the
+# Gemfile:
+#
+#   gem install benchmark-ips memory_profiler
+#   ruby -Ilib benchmark/query_building.rb
+
+require "benchmark/ips"
+require "memory_profiler"
+require "active_record"
+require "activerecord-refined"
+
+ActiveRecord::Base.establish_connection(adapter: "sqlite3", database: ":memory:")
+ActiveRecord::Schema.verbose = false
+ActiveRecord::Schema.define do
+  create_table(:users) {|t| t.string :name; t.integer :age }
+end
+
+class User < ActiveRecord::Base; end
+
+T = User.arel_table
+
+# Each variant must generate equivalent SQL; sanity-print once.
+VARIANTS = {
+  "simple equality" => {
+    "hash"   => -> { User.where(name: "matz").to_sql },
+    "string" => -> { User.where("name = ?", "matz").to_sql },
+    "arel"   => -> { User.where(T[:name].eq("matz")).to_sql },
+    "block"  => -> { User.where { :name == "matz" }.to_sql },
+  },
+  "range (BETWEEN)" => {
+    "hash"   => -> { User.where(age: 20..40).to_sql },
+    "arel"   => -> { User.where(T[:age].between(20..40)).to_sql },
+    "block"  => -> { User.where { :age.in?(20..40) }.to_sql },
+  },
+  "LIKE" => {
+    "string" => -> { User.where("name LIKE ?", "ma%").to_sql },
+    "arel"   => -> { User.where(T[:name].matches("ma%", nil, true)).to_sql },
+    "block"  => -> { User.where { :name.like?("ma%") }.to_sql },
+  },
+  "compound AND/OR" => {
+    "string"   => -> { User.where("age >= ? AND (name = ? OR name = ?)", 18, "matz", "nobu").to_sql },
+    "arel"     => -> { User.where(T[:age].gteq(18).and(T[:name].eq("matz").or(T[:name].eq("nobu")))).to_sql },
+    "relation" => -> { User.where(age: 18..).and(User.where(name: "matz").or(User.where(name: "nobu"))).to_sql },
+    "block"    => -> { User.where { (:age >= 18) & ((:name == "matz") | (:name == "nobu")) }.to_sql },
+  },
+}
+
+puts "=== generated SQL (sanity) ==="
+VARIANTS.each do |group, variants|
+  puts "--- #{group} ---"
+  variants.each {|name, thunk| puts "  #{name.ljust(8)} #{thunk.call}" }
+end
+
+puts
+puts "=== speed (queries built per second) ==="
+VARIANTS.each do |group, variants|
+  puts "--- #{group} ---"
+  Benchmark.ips do |x|
+    x.config(warmup: 0.5, time: 2)
+    variants.each {|name, thunk| x.report(name, &thunk) }
+    x.compare!
+  end
+end
+
+puts
+puts "=== memory (per single call) ==="
+fmt = "%-18s %-9s %12s %12s"
+puts format(fmt, "group", "variant", "allocated B", "objects")
+VARIANTS.each do |group, variants|
+  variants.each do |name, thunk|
+    thunk.call # warm caches (schema, statement caches) outside the report
+    report = MemoryProfiler.report { thunk.call }
+    puts format(fmt, group, name, report.total_allocated_memsize, report.total_allocated)
+  end
+end
+
+puts
+puts "=== Proc#refined ISeq copy (memory) ==="
+require "objspace"
+
+# Proc#refined runs the block under the refinements by deep-copying its
+# instruction sequence, nested blocks included.  The copy is made lazily on
+# the refined proc's first call and memoized per source iseq and refinement
+# list for the life of the VM, so it is paid once per block call site, not
+# per query.
+iseq_count = -> {
+  counts = ObjectSpace.count_imemo_objects
+  counts[:imemo_iseq] || counts[:iseq]
+}
+context = ActiveRecord::Refined::BlockContext.new
+syntax = ActiveRecord::Refined::BlockSyntax
+
+{
+  "simple equality" => proc { :name == "matz" },
+  "compound AND/OR" => proc { (:age >= 18) & ((:name == "matz") | (:name == "nobu")) },
+}.each do |label, blk|
+  refined = blk.refined(syntax)
+  context.instance_exec(&refined) # the copy is made here, on the first call
+  original = ObjectSpace.memsize_of(RubyVM::InstructionSequence.of(blk))
+  copy = ObjectSpace.memsize_of(RubyVM::InstructionSequence.of(refined))
+  puts "#{label}: original iseq #{original} B, refined copy #{copy} B"
+end
+
+make_proc = -> { proc { :age > 20 } }
+context.instance_exec(&make_proc.call.refined(syntax))
+before = iseq_count.call
+1000.times { context.instance_exec(&make_proc.call.refined(syntax)) }
+puts "1000 more calls from the same call site copied #{iseq_count.call - before} iseqs"
+
+puts
+puts "=== where the block path spends its time ==="
+block = proc { :name == "matz" }
+refined_block = block.refined(ActiveRecord::Refined::BlockSyntax)
+context = ActiveRecord::Refined::BlockContext.new
+Benchmark.ips do |x|
+  x.config(warmup: 0.5, time: 2)
+  x.report("Proc#refined alone") { block.refined(ActiveRecord::Refined::BlockSyntax) }
+  x.report("instance_exec of pre-refined proc") { context.instance_exec(&refined_block) }
+  x.report("refined + instance_exec") {
+    ActiveRecord::Refined::BlockContext.new.instance_exec(&block.refined(ActiveRecord::Refined::BlockSyntax))
+  }
+  x.compare!
+end

data/examples/complex_joins.rb

@@ -8,7 +8,7 @@ ActiveRecord::Migration.verbose = false
 
 class Setup < ActiveRecord::Migration[8.1]
   def up
-    create_table(:authors) {|t| t.string :name; t.integer :age; t.string :country }
+    create_table(:authors) {|t| t.string :name; t.integer :age; t.string :country; t.integer :mentor_id }
     create_table(:posts)   {|t| t.string :title; t.integer :author_id; t.integer :likes; t.boolean :published }
     create_table(:comments){|t| t.string :body; t.integer :post_id; t.integer :score }
   end
@@ -67,3 +67,16 @@ query3 =
 puts "--- 3. LEFT OUTER JOIN with negation ---"
 puts query3.to_sql
 puts
+
+# 4. Self join.  `as` names the table within the query, and the block's
+#    qualified columns go by that name, which is what makes a table joinable
+#    to itself.
+query4 =
+  Author.
+    joins(:authors, as: :mentors) { :mentors[:id] == :authors[:mentor_id] }.
+    where { :mentors[:country] != :authors[:country] }.
+    select { [:authors[:name].as(:author), :mentors[:name].as(:mentor)] }
+
+puts "--- 4. Self join through an alias ---"
+puts query4.to_sql
+puts

data/examples/ctes.rb

@@ -0,0 +1,82 @@
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+
+require 'active_record'
+require 'activerecord-refined'
+
+ActiveRecord::Base.establish_connection(adapter: 'sqlite3', database: ':memory:')
+ActiveRecord::Migration.verbose = false
+
+class Setup < ActiveRecord::Migration[8.1]
+  def up
+    create_table(:categories) {|t| t.string :name; t.integer :parent_id }
+    create_table(:products)   {|t| t.string :name; t.integer :category_id; t.integer :price }
+  end
+end
+Setup.new.up
+
+class Category < ActiveRecord::Base
+end
+
+class Product < ActiveRecord::Base
+end
+
+electronics = Category.create!(name: 'electronics')
+computers   = Category.create!(name: 'computers', parent_id: electronics.id)
+laptops     = Category.create!(name: 'laptops', parent_id: computers.id)
+groceries   = Category.create!(name: 'groceries')
+
+Product.create!(name: 'ultrabook', category_id: laptops.id, price: 1200)
+Product.create!(name: 'keyboard', category_id: computers.id, price: 80)
+Product.create!(name: 'apple', category_id: groceries.id, price: 2)
+
+# 1. Recursive CTE: every category below 'electronics', itself included.
+#    The recursive member joins the CTE by name, so its ON clause is a block
+#    rather than the string join Rails' own documentation reaches for.  `from`
+#    then selects the CTE under the model's table name, which is what lets
+#    Category's own columns resolve against it.
+subtree =
+  Category.with_recursive(
+    tree: [
+      Category.where { :id == electronics.id },
+      Category.joins(:tree) { :categories[:parent_id] == :tree[:id] },
+    ]
+  ).from(:tree, as: :categories)
+
+puts '--- 1. Recursive CTE walking a category tree ---'
+puts subtree.to_sql
+puts subtree.order { :name }.pluck(:name).inspect
+puts
+
+# 2. The same CTE as a subquery: products anywhere under 'electronics'.
+#    The outer query joins the CTE by name like any other table.
+products_below =
+  Product.with_recursive(
+    tree: [
+      Category.where { :id == electronics.id },
+      Category.joins(:tree) { :categories[:parent_id] == :tree[:id] },
+    ]
+  ).joins(:tree) { :tree[:id] == :products[:category_id] }
+
+puts '--- 2. Recursive CTE joined from the outer query ---'
+puts products_below.to_sql
+puts products_below.order { :name }.pluck(:name).inspect
+puts
+
+# 3. A plain CTE, named once and used twice: categories that hold something
+#    expensive, and the count of products in each.
+expensive =
+  Category.with(pricey: Product.where { :price >= 100 }).
+    joins(:pricey) { :pricey[:category_id] == :categories[:id] }.
+    group { :categories[:id] }.
+    select {
+      [
+        :categories[:name].as(:category),
+        count(:pricey[:id]).as(:pricey_count),
+        max(:pricey[:price]).as(:top_price),
+      ]
+    }
+
+puts '--- 3. Plain CTE joined and aggregated ---'
+puts expensive.to_sql
+puts expensive.map {|c| [c.category, c.pricey_count, c.top_price] }.inspect
+puts