activerecord-refined 0.3.3 → 0.5.0

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: "alice").to_sql },
+    "string" => -> { User.where("name = ?", "alice").to_sql },
+    "arel"   => -> { User.where(T[:name].eq("alice")).to_sql },
+    "block"  => -> { User.where { :name == "alice" }.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?("al%") }.to_sql },
+  },
+  "compound AND/OR" => {
+    "string"   => -> { User.where("age >= ? AND (name = ? OR name = ?)", 18, "alice", "bob").to_sql },
+    "arel"     => -> { User.where(T[:age].gteq(18).and(T[:name].eq("alice").or(T[:name].eq("bob")))).to_sql },
+    "relation" => -> { User.where(age: 18..).and(User.where(name: "alice").or(User.where(name: "bob"))).to_sql },
+    "block"    => -> { User.where { (:age >= 18) & ((:name == "alice") | (:name == "bob")) }.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 == "alice" },
+  "compound AND/OR" => proc { (:age >= 18) & ((:name == "alice") | (:name == "bob")) },
+}.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 == "alice" }
+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

data/examples/expressions.rb

@@ -0,0 +1,87 @@
+$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(:line_items) {|t| t.string :sku; t.string :category; t.integer :price; t.integer :quantity }
+  end
+end
+Setup.new.up
+
+class LineItem < ActiveRecord::Base
+end
+
+LineItem.create!(sku: 'A-1', category: 'tools',  price: 1200, quantity: 2)
+LineItem.create!(sku: 'A-2', category: 'tools',  price: 300,  quantity: 5)
+LineItem.create!(sku: 'B-1', category: 'paper',  price: 80,   quantity: 10)
+LineItem.create!(sku: 'C-1', category: nil,      price: 50,   quantity: 1)
+
+def show(title, relation, rows = nil)
+  puts "--- #{title} ---"
+  puts relation.to_sql
+  puts rows.inspect unless rows.nil?
+  puts
+end
+
+# 1. Arithmetic.  Ruby puts + - * / above the comparison operators, so an
+#    expression groups the way it reads, without parentheses.
+show('arithmetic in a condition',
+  LineItem.where { :price * :quantity > 1000 },
+  LineItem.where { :price * :quantity > 1000 }.pluck(:sku))
+
+show('arithmetic in a select list, and aggregated',
+  LineItem.select { [:sku, (:price * :quantity).as(:subtotal)] },
+  LineItem.select { [:sku, (:price * :quantity).as(:subtotal)] }.
+    map {|i| [i.sku, i.subtotal] })
+
+show('an aggregate over an expression',
+  LineItem.select { sum(:price * :quantity).as(:total) },
+  LineItem.select { sum(:price * :quantity).as(:total) }.first.total)
+
+# 2. Aggregates.  count takes :* for COUNT(*) and distinct: true for
+#    COUNT(DISTINCT ...); the rest are sum, avg, min and max.
+show('COUNT(*) and COUNT(DISTINCT ...)',
+  LineItem.select { [count(:*).as(:rows), count(:category, distinct: true).as(:categories)] },
+  LineItem.select { [count(:*).as(:rows), count(:category, distinct: true).as(:categories)] }.
+    map {|i| [i.rows, i.categories] })
+
+# 3. Functions.  Seven scalar ones have methods of their own; fn reaches
+#    anything else, emitting the name as written.
+show('built-in functions and the fn escape hatch',
+  LineItem.
+    where { length(:sku) == 3 }.
+    select { [upper(:sku).as(:sku), coalesce(:category, 'unsorted').as(:category)] },
+  LineItem.
+    where { length(:sku) == 3 }.
+    select { [upper(:sku).as(:sku), coalesce(:category, 'unsorted').as(:category)] }.
+    map {|i| [i.sku, i.category] })
+
+show('fn, for a function without a method of its own',
+  LineItem.select { fn(:hex, :price).as(:hex_price) },
+  LineItem.select { fn(:hex, :price).as(:hex_price) }.map(&:hex_price))
+
+# 4. Ordering.  asc and desc take nulls_first / nulls_last.  MySQL has no
+#    such syntax, but Arel emulates it there, so the order is the same
+#    everywhere.
+show('NULLS LAST',
+  LineItem.order { [:category.asc.nulls_last, :sku.asc] },
+  LineItem.order { [:category.asc.nulls_last, :sku.asc] }.pluck(:category, :sku))
+
+# Aggregates and expressions can be ordered by, too.
+show('grouped, aggregated and ordered by the aggregate',
+  LineItem.
+    group { :category }.
+    having { count(:*) > 1 }.
+    order { sum(:price * :quantity).desc }.
+    select { [coalesce(:category, 'unsorted').as(:category), sum(:price * :quantity).as(:total)] },
+  LineItem.
+    group { :category }.
+    having { count(:*) > 1 }.
+    order { sum(:price * :quantity).desc }.
+    select { [coalesce(:category, 'unsorted').as(:category), sum(:price * :quantity).as(:total)] }.
+    map {|i| [i.category, i.total] })

data/examples/postgresql.rb

@@ -0,0 +1,105 @@
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+
+require 'active_record'
+require 'activerecord-refined'
+require 'etc'
+
+# The features here are PostgreSQL's, so unlike the other examples this one
+# needs a server.  It connects the way the test suite does: on 127.0.0.1 as
+# the current user with no password, overridable through DB_HOST, DB_USERNAME
+# and DB_PASSWORD.
+begin
+  ActiveRecord::Base.establish_connection(
+    adapter: 'postgresql',
+    host: ENV.fetch('DB_HOST', '127.0.0.1'),
+    username: ENV.fetch('DB_USERNAME') { Etc.getlogin },
+    password: ENV['DB_PASSWORD'],
+    database: ENV.fetch('DB_NAME', 'postgres'))
+  ActiveRecord::Base.lease_connection
+rescue StandardError => e
+  abort "needs a PostgreSQL server: #{e.message}"
+end
+
+ActiveRecord::Migration.verbose = false
+
+class Setup < ActiveRecord::Migration[8.1]
+  def up
+    create_table(:articles, force: true) do |t|
+      t.string :title
+      t.string :tags, array: true, default: []
+      t.integer :scores, array: true, default: []
+    end
+  end
+end
+Setup.new.up
+
+class Article < ActiveRecord::Base
+end
+
+Article.delete_all
+Article.create!(title: 'Refinements',  tags: %w[ruby lang],  scores: [5, 4])
+Article.create!(title: 'Rails 8',      tags: %w[ruby rails], scores: [5])
+Article.create!(title: 'Postgres CTEs', tags: %w[sql db],    scores: [3])
+Article.create!(title: '100% pure',    tags: ['100%', 'a,b'], scores: [])
+
+def show(title, relation, rows = nil)
+  puts "--- #{title} ---"
+  puts relation.to_sql
+  puts rows.inspect unless rows.nil?
+  puts
+end
+
+# 1. Array columns.  Each name carries the meaning of its Ruby namesake:
+#    member? is Enumerable's element test, superset? and subset? are Set's
+#    containment, and intersect? is Array's "any element in common".
+show('member? tests one element',
+  Article.where { :tags.member?('ruby') },
+  Article.where { :tags.member?('ruby') }.pluck(:title))
+
+show('superset? requires every element',
+  Article.where { :tags.superset?(%w[ruby rails]) },
+  Article.where { :tags.superset?(%w[ruby rails]) }.pluck(:title))
+
+show('subset? and intersect?',
+  Article.where { :tags.intersect?(%w[sql lang]) },
+  [
+    Article.where { :tags.subset?(%w[ruby lang extra]) }.pluck(:title),
+    Article.where { :tags.intersect?(%w[sql lang]) }.pluck(:title),
+  ])
+
+# The element is serialized into an array literal, so commas, quotes and %
+# are matched literally rather than parsed or treated as wildcards.
+show('elements are matched literally',
+  Article.where { :tags.member?('a,b') },
+  Article.where { :tags.member?('a,b') }.pluck(:title))
+
+# member? works on any element type; the literal is coerced to the column's.
+show('a numeric array',
+  Article.where { :scores.member?(4) },
+  Article.where { :scores.member?(4) }.pluck(:title))
+
+# 2. Regular expressions.  =~ and !~ become ~ and !~ here, REGEXP on MySQL.
+#    SQLite has no regexp operator, which is why this example is not one of
+#    the portable ones.
+show('=~ matches a regular expression',
+  Article.where { :title =~ '^R' },
+  Article.where { :title =~ '^R' }.pluck(:title))
+
+show('a Regexp literal works too, and !~ negates',
+  Article.where { :title !~ /s$/ },
+  Article.where { :title !~ /s$/ }.pluck(:title))
+
+# 3. Case.  like? is case-sensitive LIKE everywhere, including here, where
+#    Arel would otherwise reach for ILIKE.  ilike? is the one that asks for
+#    it, and casecmp? is case-insensitive equality.
+show('like? stays case-sensitive; ilike? does not',
+  Article.where { :title.ilike?('r%') },
+  [
+    Article.where { :title.like?('r%') }.pluck(:title),
+    Article.where { :title.ilike?('r%') }.pluck(:title),
+  ])
+
+# 4. NULL as a value.  PostgreSQL spells this IS [NOT] DISTINCT FROM.
+show('null-safe comparison',
+  Article.where { :title.not_distinct_from?('Rails 8') },
+  Article.where { :title.not_distinct_from?('Rails 8') }.pluck(:title))

data/examples/predicates.rb

@@ -0,0 +1,93 @@
+$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(:accounts) {|t| t.string :login; t.string :country; t.integer :age }
+  end
+end
+Setup.new.up
+
+class Account < ActiveRecord::Base
+end
+
+Account.create!(login: 'alice',     country: 'JP', age: 60)
+Account.create!(login: 'bob',       country: 'JP', age: 50)
+Account.create!(login: 'carol',     country: 'US', age: 45)
+Account.create!(login: '100%_pure', country: nil,  age: 30)
+Account.create!(login: '1002000',   country: 'US', age: 25)
+
+def show(title, relation, rows)
+  puts "--- #{title} ---"
+  puts relation.to_sql
+  puts rows.inspect
+  puts
+end
+
+# 1. Ranges and sets.  in? is one name for "belongs to this set": a Range
+#    becomes BETWEEN, an endless Range a bare comparison, a list an IN.
+show('in? with a Range becomes BETWEEN',
+  Account.where { :age.in?(40..55) },
+  Account.where { :age.in?(40..55) }.pluck(:login))
+
+show('endless range and IN',
+  Account.where { :age.in?(50..) | :country.in?(%w[US]) },
+  Account.where { :age.in?(50..) | :country.in?(%w[US]) }.pluck(:login))
+
+# 2. NULL.  = NULL is never true in SQL, so == nil raises and the test is
+#    spelled null?.  not_distinct_from? is the null-safe equality, which is
+#    what to reach for when the value may or may not be nil.
+show('null? and its negation',
+  Account.where { :country.null? },
+  Account.where { :country.null? }.pluck(:login))
+
+wanted = nil
+show('not_distinct_from? matches NULL to nil',
+  Account.where { :country.not_distinct_from?(wanted) },
+  Account.where { :country.not_distinct_from?(wanted) }.pluck(:login))
+
+# Unlike !=, distinct_from? keeps the NULL row.
+show('distinct_from? keeps NULLs, != drops them',
+  Account.where { :country.distinct_from?('JP') },
+  [
+    Account.where { :country.distinct_from?('JP') }.pluck(:login),
+    Account.where { :country != 'JP' }.pluck(:login),
+  ])
+
+# 3. Text.  like? takes a pattern; start_with?, end_with? and include? take
+#    literals, so % and _ in them are escaped rather than matched as
+#    wildcards.  Note the last row matches only the literal-minded one.
+show('like? takes a pattern',
+  Account.where { :login.like?('%rol') },
+  Account.where { :login.like?('%rol') }.pluck(:login))
+
+show('start_with? takes any number of literals, like String#start_with?',
+  Account.where { :login.start_with?('al', 'bo') },
+  Account.where { :login.start_with?('al', 'bo') }.pluck(:login))
+
+# The % in the argument is escaped, so only the account whose login really
+# contains "100%" matches; the same pattern spelled with like? treats it as a
+# wildcard and catches 1002000 as well.
+show('include? escapes wildcards; like? does not',
+  Account.where { :login.include?('100%') },
+  [
+    Account.where { :login.include?('100%') }.pluck(:login),
+    Account.where { :login.like?('%100%%') }.pluck(:login),
+  ])
+
+# casecmp? folds both sides rather than trusting the collation, so it means
+# the same thing on every adapter.
+show('casecmp? is case-insensitive equality',
+  Account.where { :login.casecmp?('AlIcE') },
+  Account.where { :login.casecmp?('AlIcE') }.pluck(:login))
+
+# 4. Combining.  & | ! build the tree; Ruby's precedence puts & and | above
+#    the comparison operators, hence the parentheses around each comparison.
+show('compound conditions',
+  Account.where { (:age >= 40) & (:country.in?(%w[JP US]) | :country.null?) },
+  Account.where { (:age >= 40) & (:country.in?(%w[JP US]) | :country.null?) }.pluck(:login))

data/examples/subqueries.rb

@@ -0,0 +1,67 @@
+$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(:authors) {|t| t.string :name }
+    create_table(:posts)   {|t| t.string :title; t.integer :author_id; t.integer :likes; t.boolean :published }
+  end
+end
+Setup.new.up
+
+class Author < ActiveRecord::Base
+  has_many :posts
+end
+
+class Post < ActiveRecord::Base
+  belongs_to :author
+
+  def self.published = where { :published == true }
+end
+
+alice  = Author.create!(name: 'alice')
+bob  = Author.create!(name: 'bob')
+quiet = Author.create!(name: 'quiet')
+
+Post.create!(title: 'refinements', author_id: alice.id, likes: 100, published: true)
+Post.create!(title: 'parser',      author_id: alice.id, likes: 40,  published: true)
+Post.create!(title: 'draft',       author_id: bob.id, likes: 5,   published: false)
+
+def show(title, relation)
+  puts "--- #{title} ---"
+  puts relation.to_sql
+  puts relation.pluck(relation.model.table_name == 'authors' ? :name : :title).inspect
+  puts
+end
+
+# 1. in? takes a relation as a subquery.  With an explicit select list the
+#    subquery selects that column; without one it selects the primary key,
+#    the same way ActiveRecord's own where(id: relation) does.
+show('in? with a subquery',
+  Author.where { :id.in?(Post.published.select(:author_id)) })
+
+# 2. exists? asks whether the subquery returns a row.  Correlate it with the
+#    outer table through qualified columns; the inner where block is the same
+#    DSL as the outer one.
+show('exists?',
+  Author.where { exists?(Post.published.where { :posts[:author_id] == :authors[:id] }) })
+
+show('!exists? finds what has nothing to show',
+  Author.where { !exists?(Post.where { :posts[:author_id] == :authors[:id] }) })
+
+# 3. A relation on the right of a comparison is a scalar subquery.  It has to
+#    yield a single value, so unlike in? there is no default select list and
+#    one is required.
+show('a scalar subquery on the right of a comparison',
+  Post.where { :likes >= Post.select { avg(:likes) } })
+
+# The three compose like any other predicate.
+show('combined with the rest of the vocabulary',
+  Author.
+    where { exists?(Post.where { :posts[:author_id] == :authors[:id] }) }.
+    where { !:id.in?(Post.where { :published == false }.select(:author_id)) })