activerecord-refined 0.8.1 → 0.10.0

data/docs/windows.md

@@ -0,0 +1,41 @@
+# Window functions
+
+
+`over` gives a function a window, which is what turns an aggregate into a
+running one and the only thing `row_number` and its kind can be used with.
+The window is built by chaining, as Arel's own is:
+
+```ruby
+Author.select { avg(:age).over.partition(:country).as(:country_average) }
+# AVG("age") OVER (PARTITION BY "country") AS country_average
+
+Author.select { row_number.over.partition(:country).order(:age.desc).as(:rank) }
+# ROW_NUMBER() OVER (PARTITION BY "country" ORDER BY "age" DESC) AS rank
+
+Author.select { count(:*).over.as(:total) }   # COUNT(*) OVER () — every row
+```
+
+`row_number`, `rank`, `dense_rank`, `percent_rank`, `cume_dist`, `ntile`,
+`lag`, `lead`, `first_value`, `last_value` and `nth_value` are the functions
+that say nothing without a window; each raises `ArgumentError` if `over` never
+arrives, rather than reaching the database as an error there. Every adapter
+that has window functions at all spells them the same way, so unlike the
+scalar functions there is nothing here to translate.
+
+A frame is a range of rows counted from the current one — negative before it,
+positive after, 0 the row itself, and an open end for unbounded:
+
+```ruby
+Post.select { sum(:likes).over.order(:created_at).rows(..0).as(:running) }
+# SUM("likes") OVER (ORDER BY "created_at" ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW)
+
+Post.select { avg(:likes).over.order(:created_at).rows(-1..1).as(:smoothed) }
+# ... ROWS BETWEEN 1 PRECEDING AND 1 FOLLOWING
+
+Post.select { sum(:likes).over.order(:created_at).rows(0..).as(:remaining) }
+# ... ROWS BETWEEN CURRENT ROW AND UNBOUNDED FOLLOWING
+```
+
+`range` says `RANGE` where `rows` says `ROWS`, and a window has one frame or
+none. Named windows — `WINDOW w AS (...)` — have no clause in Active Record to
+live in, so they are not here.

data/docs/writing.md

@@ -0,0 +1,33 @@
+# Writing
+
+
+`update_all` reads its hash the way Active Record does — `update_all(likes: :likes)`
+sets the column to the symbol itself. The block reads a symbol as the column it
+names, as every other block here does, which is what lets the new value be
+worked out from the old:
+
+```ruby
+Post.where { :published == true }.update_all { { likes: :likes + 1 } }
+# UPDATE "posts" SET "likes" = ("posts"."likes" + 1) WHERE ...
+
+Post.update_all { { title: upper(:title), likes: case_when { :likes < 0 }.then(0).else(:likes) } }
+```
+
+`upsert_all` takes one too, for the part that decides what happens to a row
+that is already there. `excluded` is the row that could not be inserted:
+
+```ruby
+Tally.upsert_all(rows, unique_by: :page) { { hits: :hits + excluded(:hits) } }
+# ... ON CONFLICT ("page") DO UPDATE SET "hits"=("tallies"."hits" + "excluded"."hits")
+```
+
+PostgreSQL and SQLite name that row `excluded`; MySQL spells the same thing
+`VALUES(column)`, and the block comes out as whichever the adapter reads.
+Active Record's own `on_duplicate:` takes SQL text and nothing else, so this is
+the one place the DSL writes SQL out itself rather than handing Arel a tree —
+and the two cannot both be given.
+
+`insert_all` has no block: its values are literals by construction.
+Active Record type-casts each one on the way into the `VALUES` list, so an
+expression does not become SQL there — it becomes nothing, silently. Use
+`upsert_all` where a row's value has to be worked out.

data/examples/aggregations.rb

@@ -1,16 +1,18 @@
-$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+# frozen_string_literal: true
 
-require 'active_record'
-require 'activerecord-refined'
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), "..", "lib"))
 
-ActiveRecord::Base.establish_connection(adapter: 'sqlite3', database: ':memory:')
+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; t.integer :age; t.string :country }
-    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 }
+    create_table(:authors) { |t| t.string :name; t.integer :age; t.string :country }
+    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
 end
 Setup.new.up
@@ -54,11 +56,11 @@ puts
 #    coalesce function + GROUP BY + aggregates + multiple ORDER BY
 query2 =
   Author.
-    group { coalesce(:country, 'unknown') }.
-    order { [count(:id).desc, coalesce(:country, 'unknown').asc] }.
+    group { coalesce(:country, "unknown") }.
+    order { [count(:id).desc, coalesce(:country, "unknown").asc] }.
     select {
       [
-        coalesce(:country, 'unknown').as(:country),
+        coalesce(:country, "unknown").as(:country),
         count(:id).as(:author_count),
         avg(:age).as(:avg_age),
       ]
@@ -74,7 +76,7 @@ query3 =
   Author.
     joins(:posts) { :posts[:author_id] == :authors[:id] }.
     joins(:comments) { :comments[:post_id] == :posts[:id] }.
-    where { !:posts[:title].include?('draft') & (:comments[:score] >= 0) }.
+    where { !:posts[:title].include?("draft") & (:comments[:score] >= 0) }.
     group { :authors[:id] }.
     having { sum(:comments[:score]) > 10 }.
     order { sum(:comments[:score]).desc }.
@@ -89,3 +91,21 @@ query3 =
 puts "--- 3. Comment score aggregation across multi-table JOIN ---"
 puts query3.to_sql
 puts
+
+# 4. The titles of each author's posts joined into one string
+#    string_agg + order inside the aggregate + filter; group_concat on SQLite
+query4 =
+  Author.
+    joins(:posts) { :posts[:author_id] == :authors[:id] }.
+    group { :authors[:id] }.
+    select {
+      [
+        :authors[:name],
+        string_agg(:posts[:title], ", ").order(:posts[:title]).as(:titles),
+        string_agg(:posts[:title], ", ").filter { :posts[:published] == true }.as(:published),
+      ]
+    }
+
+puts "--- 4. Titles per author, joined (string_agg / order / filter) ---"
+puts query4.to_sql
+puts

data/examples/complex_joins.rb

@@ -1,16 +1,18 @@
-$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+# frozen_string_literal: true
 
-require 'active_record'
-require 'activerecord-refined'
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), "..", "lib"))
 
-ActiveRecord::Base.establish_connection(adapter: 'sqlite3', database: ':memory:')
+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; 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 }
+    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
 end
 Setup.new.up
@@ -47,7 +49,7 @@ query2 =
     joins(:posts) { :posts[:author_id] == :authors[:id] }.
     joins(:comments) { :comments[:post_id] == :posts[:id] }.
     where {
-      !:posts[:title].include?('draft') &
+      !:posts[:title].include?("draft") &
         !:comments[:score].in?([0, -1]) &
         (:authors[:age] >= 18)
     }
@@ -98,14 +100,14 @@ puts
 begin
   Author.right_outer_joins(:posts)
 rescue ArgumentError => e
-  puts '--- and it says so without one ---'
+  puts "--- and it says so without one ---"
   puts "  #{e.message}"
   puts
 end
 
 # 6. CROSS JOIN: every row against every row, so there is no condition to
 #    give and no block to write it in.  `as` still names the table.
-puts '--- 6. CROSS JOIN ---'
+puts "--- 6. CROSS JOIN ---"
 puts Author.cross_joins(:posts).to_sql
 puts Author.cross_joins(:authors, as: :others).
   select { [:authors[:name].as(:a), :others[:name].as(:b)] }.to_sql

data/examples/ctes.rb

@@ -1,15 +1,17 @@
-$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+# frozen_string_literal: true
 
-require 'active_record'
-require 'activerecord-refined'
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), "..", "lib"))
 
-ActiveRecord::Base.establish_connection(adapter: 'sqlite3', database: ':memory:')
+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 }
+    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
@@ -20,14 +22,14 @@ 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')
+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)
+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
@@ -47,7 +49,7 @@ subtree =
     ]
   ).from_cte(:tree)
 
-puts '--- 1. Recursive CTE walking a category tree ---'
+puts "--- 1. Recursive CTE walking a category tree ---"
 puts subtree.to_sql
 puts subtree.order { :name }.pluck(:name).inspect
 puts
@@ -68,14 +70,14 @@ forest =
     ]
   ).from_cte(:tree).order { [:depth, :id] }
 
-puts '--- 2. Recursive CTE carrying the root and the depth down ---'
+puts "--- 2. Recursive CTE carrying the root and the depth down ---"
 puts forest.to_sql
-puts forest.map {|c| [c.name, c.root_id, c.depth] }.inspect
+puts forest.map { |c| [c.name, c.root_id, c.depth] }.inspect
 
 # The alias from_cte puts on the CTE is what lets this `where` qualify
 # root_id; without it the column would be looked for in a table the query no
 # longer has.
-puts forest.where { :root_id == electronics.id }.map {|c| [c.name, c.depth] }.inspect
+puts forest.where { :root_id == electronics.id }.map { |c| [c.name, c.depth] }.inspect
 puts
 
 # 3. The same CTE as a subquery: products anywhere under 'electronics'.
@@ -88,7 +90,7 @@ products_below =
     ]
   ).joins(:tree) { :tree[:id] == :products[:category_id] }
 
-puts '--- 3. Recursive CTE joined from the outer query ---'
+puts "--- 3. Recursive CTE joined from the outer query ---"
 puts products_below.to_sql
 puts products_below.order { :name }.pluck(:name).inspect
 puts
@@ -107,7 +109,7 @@ expensive =
       ]
     }
 
-puts '--- 4. Plain CTE joined and aggregated ---'
+puts "--- 4. Plain CTE joined and aggregated ---"
 puts expensive.to_sql
-puts expensive.map {|c| [c.category, c.pricey_count, c.top_price] }.inspect
+puts expensive.map { |c| [c.category, c.pricey_count, c.top_price] }.inspect
 puts

data/examples/expressions.rb

@@ -1,9 +1,11 @@
-$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+# frozen_string_literal: true
 
-require 'active_record'
-require 'activerecord-refined'
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), "..", "lib"))
 
-ActiveRecord::Base.establish_connection(adapter: 'sqlite3', database: ':memory:')
+require "active_record"
+require "activerecord-refined"
+
+ActiveRecord::Base.establish_connection(adapter: "sqlite3", database: ":memory:")
 ActiveRecord::Migration.verbose = false
 
 class Setup < ActiveRecord::Migration[8.1]
@@ -14,6 +16,7 @@ class Setup < ActiveRecord::Migration[8.1]
       t.integer :price
       t.integer :quantity
       t.integer :flags
+      t.date :ordered_on
     end
   end
 end
@@ -22,10 +25,16 @@ Setup.new.up
 class LineItem < ActiveRecord::Base
 end
 
-LineItem.create!(sku: 'A-1', category: 'tools',  price: 1200, quantity: 2,  flags: 12)
-LineItem.create!(sku: 'A-2', category: 'tools',  price: 300,  quantity: 5,  flags: 10)
-LineItem.create!(sku: 'B-1', category: 'paper',  price: 80,   quantity: 10, flags: 3)
-LineItem.create!(sku: 'C-1', category: nil,      price: 50,   quantity: 1,  flags: 4)
+LineItem.create!(sku: "A-1", category: "tools",  price: 1200, quantity: 2,  flags: 12,
+                 ordered_on: Date.new(2026, 1, 5))
+LineItem.create!(sku: "A-2", category: "tools",  price: 300,  quantity: 5,  flags: 10,
+                 ordered_on: Date.new(2026, 1, 20))
+LineItem.create!(sku: "B-1", category: "paper",  price: 80,   quantity: 10, flags: 3,
+                 ordered_on: Date.new(2026, 2, 3))
+LineItem.create!(sku: "B-2", category: "paper",  price: 80,   quantity: 10, flags: 3,
+                 ordered_on: Date.new(2026, 2, 3))
+LineItem.create!(sku: "C-1", category: nil,      price: 50,   quantity: 1,  flags: 4,
+                 ordered_on: Date.new(2026, 2, 14))
 
 def show(title, relation, rows = nil)
   puts "--- #{title} ---"
@@ -36,31 +45,55 @@ end
 
 # 1. Arithmetic.  Ruby puts + - * / above the comparison operators, so an
 #    expression groups the way it reads, without parentheses.
-show('arithmetic in a condition',
+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',
+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] })
+    map { |i| [i.sku, i.subtotal] })
 
-show('an aggregate over an expression',
+show("an aggregate over an expression",
   LineItem.select { sum(:price * :quantity).as(:total) },
   LineItem.select { sum(:price * :quantity).as(:total) }.first.total)
 
+# The number may stand on the left; only a column or an expression on the
+# right builds a query, so Ruby's own arithmetic is untouched.  BigDecimal
+# is a number here too -- what a decimal column's values are.
+show("the number on the left, and a BigDecimal",
+  LineItem.select { [:sku, (12 - :quantity).as(:to_the_dozen)] },
+  LineItem.select { [:sku, (12 - :quantity).as(:to_the_dozen)] }.
+    map { |i| [i.sku, i.to_the_dozen] })
+
+show("a tax through BigDecimal, exact on the wire",
+  LineItem.select { [:sku, (BigDecimal("1.1") * :price).as(:taxed)] },
+  LineItem.select { [:sku, (BigDecimal("1.1") * :price).as(:taxed)] }.
+    map { |i| [i.sku, i.taxed] })
+
+# A duration moves a date.  Each adapter spells the move its own way; SQLite
+# has date() and datetime(), and a date column keeps being a date.
+show("a date moved by a duration",
+  LineItem.where { :ordered_on + 30.days < Date.new(2026, 2, 10) },
+  LineItem.where { :ordered_on + 30.days < Date.new(2026, 2, 10) }.pluck(:sku))
+
+show("a due date a month on",
+  LineItem.select { [:sku, (:ordered_on + 1.month).as(:due_on)] },
+  LineItem.select { [:sku, (:ordered_on + 1.month).as(:due_on)] }.
+    map { |i| [i.sku, i.due_on] })
+
 # The bitwise operators.  & and | are AND and OR between conditions, which is
 # what leaves them free here.  Each expression parenthesises itself, so the
 # grouping is Ruby's rather than the adapter's.
-show('a bit test in a condition',
+show("a bit test in a condition",
   LineItem.where { :flags & 4 > 0 },
   LineItem.where { :flags & 4 > 0 }.pluck(:sku))
 
 # XOR is the one the three adapters do not share.  SQLite has none, so it gets
 # the two operations XOR is made of; PostgreSQL would say #, MySQL ^.
-show('xor, spelled the way the adapter spells it',
+show("xor, spelled the way the adapter spells it",
   LineItem.select { [:sku, (:flags ^ 10).as(:xored)] },
-  LineItem.select { [:sku, (:flags ^ 10).as(:xored)] }.map {|i| [i.sku, i.xored] })
+  LineItem.select { [:sku, (:flags ^ 10).as(:xored)] }.map { |i| [i.sku, i.xored] })
 
 # A condition cannot be an operand, and neither can a boolean column: two of
 # the three adapters would quietly answer as AND does and the third has no
@@ -68,86 +101,118 @@ show('xor, spelled the way the adapter spells it',
 begin
   LineItem.where { :flags & (:price == 1) }
 rescue ArgumentError => e
-  puts '--- a condition is not an operand of & ---'
+  puts "--- a condition is not an operand of & ---"
   puts "  #{e.message}"
   puts
 end
 
 # 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 ...)',
+#    COUNT(DISTINCT ...), which sum and avg take too; the rest are 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] })
+    map { |i| [i.rows, i.categories] })
+
+show("SUM(DISTINCT ...), each quantity counted once",
+  LineItem.select { [sum(:quantity).as(:all), sum(:quantity, distinct: true).as(:once)] },
+  LineItem.select { [sum(:quantity).as(:all), sum(:quantity, distinct: true).as(:once)] }.
+    map { |i| [i.all, i.once] })
 
 # filter takes the aggregate over the rows a condition holds for.  SQLite and
 # PostgreSQL have the FILTER clause; MySQL gets the CASE that means the same,
 # since an aggregate passes over the NULL a missed row leaves.
-show('two aggregates over different rows of the same query',
+show("two aggregates over different rows of the same query",
   LineItem.select {
-    [count(:*).as(:all), sum(:price).filter { :category == 'tools' }.as(:tools)]
+    [count(:*).as(:all), sum(:price).filter { :category == "tools" }.as(:tools)]
   },
   LineItem.select {
-    [count(:*).as(:all), sum(:price).filter { :category == 'tools' }.as(:tools)]
-  }.map {|i| [i.all, i.tools] })
+    [count(:*).as(:all), sum(:price).filter { :category == "tools" }.as(:tools)]
+  }.map { |i| [i.all, i.tools] })
 
 # CASE has two shapes: an operand to compare each when against, or a condition
 # on every when.  case is a Ruby keyword, so the method behind both is only
 # reachable through the receiver -- self.case -- and each shape has a shorthand
 # that does not need it.
-show('a CASE with an operand, through the shorthand',
-  LineItem.select { [:sku, :category.when('tools').then('hardware').else('other').as(:kind)] },
-  LineItem.select { [:sku, :category.when('tools').then('hardware').else('other').as(:kind)] }.
-    map {|i| [i.sku, i.kind] })
+show("a CASE with an operand, through the shorthand",
+  LineItem.select { [:sku, :category.when("tools").then("hardware").else("other").as(:kind)] },
+  LineItem.select { [:sku, :category.when("tools").then("hardware").else("other").as(:kind)] }.
+    map { |i| [i.sku, i.kind] })
 
-show('a CASE where each when carries its own condition',
+show("a CASE where each when carries its own condition",
   LineItem.select {
-    [:sku, case_when { :price >= 1000 }.then('dear').when { :price >= 100 }.
-      then('middling').else('cheap').as(:band)]
+    [:sku, case_when { :price >= 1000 }.then("dear").when { :price >= 100 }.
+      then("middling").else("cheap").as(:band)]
   },
   LineItem.select {
-    [:sku, case_when { :price >= 1000 }.then('dear').when { :price >= 100 }.
-      then('middling').else('cheap').as(:band)]
-  }.map {|i| [i.sku, i.band] })
+    [:sku, case_when { :price >= 1000 }.then("dear").when { :price >= 100 }.
+      then("middling").else("cheap").as(:band)]
+  }.map { |i| [i.sku, i.band] })
 
 # It is an expression like any other, so it goes inside an aggregate too.
-show('counting with a CASE',
+show("counting with a CASE",
   LineItem.select { sum(case_when { :price >= 100 }.then(1).else(0)).as(:dear_ones) },
   LineItem.select { sum(case_when { :price >= 100 }.then(1).else(0)).as(:dear_ones) }.
-    map {|i| i.dear_ones })
+    map { |i| i.dear_ones })
 
 # 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',
+show("built-in functions and the fn escape hatch",
   LineItem.
     where { length(:sku) == 3 }.
-    select { [upper(:sku).as(:sku), coalesce(:category, 'unsorted').as(:category)] },
+    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] })
+    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',
+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))
 
+# op is the same for operators: the operator is emitted as written --
+# checked against the operator characters -- and both sides are quoted
+# values, columns or expressions.  What it gives compares like any other
+# expression.
+show("op, for an operator without a method of its own",
+  LineItem.where { op("%", :quantity, 2) == 1 },
+  LineItem.where { op("%", :quantity, 2) == 1 }.pluck(:sku))
+
+# sql is the last resort, and the one way a string means SQL inside a block:
+# a bare string is refused there, and ? and :name placeholders take quoted
+# values.  What it gives is parenthesized wherever it stands as an operand.
+show("sql, for what neither fn nor op can spell",
+  LineItem.where { sql("price % ?", 100) == 0 },
+  LineItem.where { sql("price % ?", 100) == 0 }.pluck(:sku))
+
+# A string sent `as` is a value, like a number.
+show("a string literal in a select list",
+  LineItem.select { [:sku, "listed".as(:state)] },
+  LineItem.select { [:sku, "listed".as(:state)] }.map { |i| [i.sku, i.state] })
+
 # 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',
+show("NULLS LAST",
   LineItem.order { [:category.asc.nulls_last, :sku.asc] },
   LineItem.order { [:category.asc.nulls_last, :sku.asc] }.pluck(:category, :sku))
 
+# collate names a collation -- how the database compares and orders strings --
+# and gives back an expression, so it carries into a comparison or an order.
+# The names are the database's own; nocase is SQLite's case-insensitive one.
+show("a case-insensitive comparison under a collation",
+  LineItem.where { :category.collate(:nocase) == "TOOLS" },
+  LineItem.where { :category.collate(:nocase) == "TOOLS" }.pluck(:sku))
+
 # Aggregates and expressions can be ordered by, too.
-show('grouped, aggregated and ordered by the aggregate',
+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)] },
+    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] })
+    select { [coalesce(:category, "unsorted").as(:category), sum(:price * :quantity).as(:total)] }.
+    map { |i| [i.category, i.total] })