activerecord-refined 0.5.0 → 0.6.0

data/examples/ctes.rb

@@ -31,23 +31,54 @@ 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.
+#    rather than the string join Rails' own documentation reaches for.
+#    `from_cte` then selects the CTE under the model's table name.
+#
+#    That alias is ActiveRecord's requirement rather than SQL's: by hand the
+#    last line would be `SELECT * FROM tree`.  ActiveRecord keeps qualifying
+#    columns with the model's table name, so without it `where` and `find_by`
+#    look for a table the query does not have.  `count`, `order` and `select`
+#    never qualify and would work either way, which makes it easy to miss.
 subtree =
   Category.with_recursive(
     tree: [
       Category.where { :id == electronics.id },
       Category.joins(:tree) { :categories[:parent_id] == :tree[:id] },
     ]
-  ).from(:tree, as: :categories)
+  ).from_cte(:tree)
 
 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'.
+# 2. One walk over every tree, carrying down where each row started and how
+#    far it has come.  Which tree is wanted is then an ordinary `where`, asked
+#    afterwards, so the CTE is not rebuilt for each root.  0 is a value rather
+#    than SQL: at the top of a select list a bare string would be SQL, so
+#    numbers say `.as` directly and anything else says `value(...).as`.
+forest =
+  Category.with_recursive(
+    tree: [
+      Category.where { :parent_id.null? }.
+        select { [:id, :name, :parent_id, :id.as(:root_id), 0.as(:depth)] },
+      Category.joins(:tree) { :categories[:parent_id] == :tree[:id] }.
+        select { [:id, :name, :parent_id,
+                  :tree[:root_id], (:tree[:depth] + 1).as(:depth)] },
+    ]
+  ).from_cte(:tree).order { [:depth, :id] }
+
+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
+
+# 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
+
+# 3. 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(
@@ -57,26 +88,26 @@ products_below =
     ]
   ).joins(:tree) { :tree[:id] == :products[:category_id] }
 
-puts '--- 2. 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
 
-# 3. A plain CTE, named once and used twice: categories that hold something
+# 4. 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] }.
+    group { :id }.
     select {
       [
-        :categories[:name].as(:category),
+        :name.as(:category),
         count(:pricey[:id]).as(:pricey_count),
         max(:pricey[:price]).as(:top_price),
       ]
     }
 
-puts '--- 3. 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

data/examples/expressions.rb

@@ -8,7 +8,13 @@ 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 }
+    create_table(:line_items) do |t|
+      t.string :sku
+      t.string :category
+      t.integer :price
+      t.integer :quantity
+      t.integer :flags
+    end
   end
 end
 Setup.new.up
@@ -16,10 +22,10 @@ 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)
+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)
 
 def show(title, relation, rows = nil)
   puts "--- #{title} ---"
@@ -43,6 +49,30 @@ show('an aggregate over an expression',
   LineItem.select { sum(:price * :quantity).as(:total) },
   LineItem.select { sum(:price * :quantity).as(:total) }.first.total)
 
+# 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',
+  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',
+  LineItem.select { [:sku, (:flags ^ 10).as(: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
+# such operator, so the block refuses instead.
+begin
+  LineItem.where { :flags & (:price == 1) }
+rescue ArgumentError => e
+  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 ...)',
@@ -50,6 +80,42 @@ show('COUNT(*) and COUNT(DISTINCT ...)',
   LineItem.select { [count(:*).as(:rows), count(:category, distinct: true).as(:categories)] }.
     map {|i| [i.rows, i.categories] })
 
+# 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',
+  LineItem.select {
+    [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] })
+
+# 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 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)]
+  },
+  LineItem.select {
+    [: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',
+  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 })
+
 # 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',

data/examples/json.rb

@@ -0,0 +1,94 @@
+$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(:documents) {|t| t.string :name; t.json :meta }
+  end
+end
+Setup.new.up
+
+class Document < ActiveRecord::Base
+end
+
+Document.create!(name: 'guide',
+  meta: {'author' => {'name' => 'alice', 'country' => 'JP'},
+         'tags' => %w[ruby sql], 'views' => 120, 'draft' => false})
+Document.create!(name: 'notes',
+  meta: {'author' => {'name' => 'bob'}, 'tags' => ['ruby'], 'views' => 8})
+Document.create!(name: 'empty', meta: {})
+
+def show(title, relation, rows = nil)
+  puts "--- #{title} ---"
+  puts relation.to_sql
+  puts rows.inspect unless rows.nil?
+  puts
+end
+
+# 1. Reading.  dig takes the path Hash#dig takes: a string or symbol steps
+#    into an object, an integer into an array.  What comes back is the value
+#    rather than the JSON around it, which is what a comparison wants.
+show('dig reads a value out of the document',
+  Document.select { [:name, :meta.dig(:author, :name).as(:author)] },
+  Document.select { [:name, :meta.dig(:author, :name).as(:author)] }.
+    map {|d| [d.name, d.author] })
+
+show('an integer steps into an array',
+  Document.select { [:name, :meta.dig(:tags, 0).as(:first_tag)] },
+  Document.select { [:name, :meta.dig(:tags, 0).as(:first_tag)] }.
+    map {|d| [d.name, d.first_tag] })
+
+# A dug value is an expression like any other, so it compares and orders.
+show('dig in a condition',
+  Document.where { :meta.dig(:author, :country) == 'JP' },
+  Document.where { :meta.dig(:author, :country) == 'JP' }.pluck(:name))
+
+# dig_json keeps the JSON, for a part of the document to be dug into further
+# or compared whole.  The quotes around the string are the sign of it.
+show('dig_json keeps the JSON',
+  Document.select { [:name, :meta.dig_json(:author).as(:author)] },
+  Document.select { [:name, :meta.dig_json(:author).as(:author)] }.
+    map {|d| [d.name, d.author] })
+
+# 2. Asking whether a key is there at all, which is not the same as asking
+#    whether its value is null -- and is spelled key? for the reason Ruby's
+#    Hash spells it that way.
+show('key? asks whether the key is there',
+  Document.where { :meta.key?(:draft) },
+  Document.where { :meta.key?(:draft) }.pluck(:name))
+
+# key? takes the one key Hash#key? takes; a path is what dig is for.
+show('and ! is its negation',
+  Document.where { !:meta.key?(:draft) },
+  Document.where { !:meta.key?(:draft) }.pluck(:name))
+
+# 3. Writing.  bury sets what dig reads, at the path given: JSON_SET on SQLite
+#    and MySQL, jsonb_set on PostgreSQL.
+show('the expression bury builds',
+  Document.select { [:name, :meta.bury(:author, :country, 'US').as(:updated)] })
+
+# It is an expression, so it is what update_all sets the column to.
+Document.where { :name == 'notes' }.update_all { {meta: :meta.bury(:author, :country, 'US')} }
+puts '--- what the update left behind ---'
+puts "  #{Document.find_by(name: 'notes').meta.inspect}"
+puts
+
+# A whole object or array goes in at once.
+Document.where { :name == 'empty' }.update_all { {meta: :meta.bury(:author, {'name' => 'carol'})} }
+puts '--- a whole object at once ---'
+puts "  #{Document.find_by(name: 'empty').meta.inspect}"
+puts
+
+# The path is what makes the SQL, so it cannot be empty.
+begin
+  Document.select { :meta.bury('US') }
+rescue ArgumentError => e
+  puts '--- bury needs a path ---'
+  puts "  #{e.message}"
+  puts
+end

data/examples/postgresql.rb

@@ -4,8 +4,9 @@ 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
+# What is here is what SQLite cannot run, so unlike the other examples this
+# one needs a server.  Most of it is PostgreSQL's alone; ANY and ALL, JSON
+# containment, the bit aggregates and LATERAL are MySQL's too.  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
@@ -24,23 +25,40 @@ ActiveRecord::Migration.verbose = false
 
 class Setup < ActiveRecord::Migration[8.1]
   def up
+    create_table(:writers, force: true) {|t| t.string :name; t.string :country }
     create_table(:articles, force: true) do |t|
       t.string :title
       t.string :tags, array: true, default: []
       t.integer :scores, array: true, default: []
+      t.integer :writer_id
+      t.integer :likes
+      t.integer :flags
+      t.jsonb :meta
     end
   end
 end
 Setup.new.up
 
+class Writer < ActiveRecord::Base
+end
+
 class Article < ActiveRecord::Base
+  belongs_to :writer
 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: [])
+Writer.delete_all
+alice = Writer.create!(name: 'alice', country: 'JP')
+bob   = Writer.create!(name: 'bob',   country: 'JP')
+carol = Writer.create!(name: 'carol', country: 'US')
+Article.create!(title: 'Refinements',   tags: %w[ruby lang],   scores: [5, 4],
+                writer: alice, likes: 120, flags: 5, meta: {'draft' => false, 'lang' => 'ja'})
+Article.create!(title: 'Rails 8',       tags: %w[ruby rails],  scores: [5],
+                writer: alice, likes: 80,  flags: 1, meta: {'draft' => false})
+Article.create!(title: 'Postgres CTEs', tags: %w[sql db],      scores: [3],
+                writer: bob,   likes: 30,  flags: 3, meta: {'draft' => true})
+Article.create!(title: '100% pure',     tags: ['100%', 'a,b'], scores: [],
+                writer: carol, likes: 5,   flags: 4, meta: {'draft' => true, 'lang' => 'ja'})
 
 def show(title, relation, rows = nil)
   puts "--- #{title} ---"
@@ -103,3 +121,68 @@ show('like? stays case-sensitive; ilike? does not',
 show('null-safe comparison',
   Article.where { :title.not_distinct_from?('Rails 8') },
   Article.where { :title.not_distinct_from?('Rails 8') }.pluck(:title))
+
+# 5. Keeping one row per group.  DISTINCT ON is PostgreSQL's: the first row of
+#    each group the order brings up, which is why the order has to start with
+#    what the distinct is on.  Arel refuses to write it for the others, so the
+#    portable shape is a row_number window in a subquery.
+show('the most liked article of each writer',
+  Article.distinct_on { :writer_id }.order { [:writer_id, :likes.desc] },
+  Article.distinct_on { :writer_id }.order { [:writer_id, :likes.desc] }.
+    pluck(:title))
+
+# 6. Grouping several ways at once.  Each grouping set produces its own rows,
+#    and an empty one is the grand total; rollup and cube are the two shapes
+#    that come up often enough to have names of their own.  MySQL has only
+#    WITH ROLLUP, which is a different clause, and SQLite has none of it.
+sets = Article.
+  joins(:writers) { :writers[:id] == :articles[:writer_id] }.
+  group { grouping_sets([:writers[:country]], [:articles[:writer_id]], []) }.
+  select { [:writers[:country], :articles[:writer_id], sum(:likes).as(:likes)] }
+show('by country, by writer, and both together',
+  sets,
+  sets.map {|a| [a.country, a.writer_id, a.likes] })
+
+show('rollup is the nested case of the same thing',
+  Article.group { rollup(:writer_id, :flags) }.select { [:writer_id, :flags, count(:*).as(:n)] })
+
+# 7. Lateral joins.  A lateral join lets the relation joined see the row being
+#    joined to, which is what makes the top row of each group reachable in one
+#    query.  Without a block the join is ON TRUE, the usual shape: what the
+#    subquery may see is said in its own where.
+top = Article.select { :title }.
+  where { :articles[:writer_id] == :writers[:id] }.
+  order { :likes.desc }.limit(1)
+lateral = Writer.left_outer_joins(top, as: :top, lateral: true).
+  select { [:name, :top[:title].as(:top_article)] }
+show('the top article beside each writer',
+  lateral,
+  lateral.map {|w| [w.name, w.top_article] })
+
+# 8. ANY and ALL, which quantify a comparison over a subquery where a scalar
+#    subquery would have to return the one row.  MySQL has them too; SQLite
+#    has neither, and says so rather than leaving its parser to.
+show('more liked than some article of alice, and than all of them',
+  Article.where { :likes > any(Article.where { :writer_id == alice.id }.select(:likes)) },
+  [
+    Article.where { :likes > any(Article.where { :writer_id == alice.id }.select(:likes)) }.
+      pluck(:title),
+    Article.where { :likes > all(Article.where { :writer_id == alice.id }.select(:likes)) }.
+      pluck(:title),
+  ])
+
+# 9. JSON containment and the bit aggregates, which PostgreSQL and MySQL have
+#    and SQLite does not.  contains? asks whether the document holds the one
+#    given, which is @> here and JSON_CONTAINS on MySQL.
+show('containment asks about a whole document',
+  Article.where { :meta.contains?(draft: true) },
+  Article.where { :meta.contains?(draft: true) }.pluck(:title))
+
+show('the bits every article has, and the bits any of them has',
+  Article.select { [bit_and(:flags).as(:common), bit_or(:flags).as(:any)] },
+  Article.select { [bit_and(:flags).as(:common), bit_or(:flags).as(:any)] }.
+    map {|a| [a.common, a.any] })
+
+show('and how many bits are set in each',
+  Article.select { [:title, bit_count(:flags).as(:bits)] },
+  Article.select { [:title, bit_count(:flags).as(:bits)] }.map {|a| [a.title, a.bits] })

data/examples/predicates.rb

@@ -8,7 +8,12 @@ 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 }
+    create_table(:accounts) do |t|
+      t.string :login
+      t.string :country
+      t.integer :age
+      t.boolean :verified
+    end
   end
 end
 Setup.new.up
@@ -16,11 +21,11 @@ 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: 'alice',     country: 'JP', age: 60, verified: true)
+Account.create!(login: 'bob',       country: 'JP', age: 50, verified: false)
+Account.create!(login: 'carol',     country: 'US', age: 45, verified: true)
 Account.create!(login: '100%_pure', country: nil,  age: 30)
-Account.create!(login: '1002000',   country: 'US', age: 25)
+Account.create!(login: '1002000',   country: 'US', age: 25, verified: false)
 
 def show(title, relation, rows)
   puts "--- #{title} ---"
@@ -59,6 +64,28 @@ show('distinct_from? keeps NULLs, != drops them',
     Account.where { :country != 'JP' }.pluck(:login),
   ])
 
+# A boolean column has true? and false?, which become IS TRUE and IS FALSE,
+# and the negation of each.  All four are spelled and answered the same way by
+# every adapter, NULL included.
+show('the four truth tests',
+  Account.where { :verified.false? },
+  [
+    Account.where { :verified.true? }.pluck(:login),
+    Account.where { :verified.false? }.pluck(:login),
+    Account.where { :verified.not_true? }.pluck(:login),
+    Account.where { :verified.not_false? }.pluck(:login),
+  ])
+
+# They answer for a NULL row where a comparison against the literal does not,
+# so it is negating them that tells the two apart: not_true? has the
+# unverified accounts and the one never asked, !(== true) only the former.
+show('not_true? keeps the NULLs that != TRUE drops',
+  Account.where { :verified.not_true? },
+  [
+    Account.where { :verified.not_true? }.pluck(:login),
+    Account.where { !(:verified == true) }.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.

data/examples/windows.rb

@@ -0,0 +1,96 @@
+$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(:sales) {|t| t.string :region; t.string :day; t.integer :amount }
+  end
+end
+Setup.new.up
+
+class Sale < ActiveRecord::Base
+end
+
+Sale.create!(region: 'east', day: '2026-01-01', amount: 100)
+Sale.create!(region: 'east', day: '2026-01-02', amount: 40)
+Sale.create!(region: 'east', day: '2026-01-03', amount: 60)
+Sale.create!(region: 'west', day: '2026-01-01', amount: 20)
+Sale.create!(region: 'west', day: '2026-01-02', amount: 90)
+
+def show(title, relation, rows = nil)
+  puts "--- #{title} ---"
+  puts relation.to_sql
+  puts rows.inspect unless rows.nil?
+  puts
+end
+
+# 1. A window on an aggregate.  over turns an aggregate into a window
+#    function: the rows stay, and the aggregate is worked out over the window
+#    beside each one.  Without partition or order the window is every row.
+show('the total beside every row',
+  Sale.select { [:region, :amount, sum(:amount).over.as(:total)] },
+  Sale.select { [:region, :amount, sum(:amount).over.as(:total)] }.
+    map {|s| [s.region, s.amount, s.total] })
+
+# partition divides the rows into groups the window is worked out within.
+totals = -> {
+  Sale.select { [:region, :amount, sum(:amount).over.partition(:region).as(:region_total)] }
+}
+show('a total per region, still row by row',
+  totals.call,
+  totals.call.map {|s| [s.region, s.amount, s.region_total] })
+
+# 2. Frames.  With an order, the window can be cut down to a range of rows
+#    around the current one.  A Range of integers is what says which: 0 is the
+#    current row, a beginless range reaches back to the start of the
+#    partition, an endless one forward to its end.
+running = -> {
+  Sale.select {
+    [:region, :day, :amount,
+     sum(:amount).over.partition(:region).order(:day).rows(..0).as(:running)]
+  }
+}
+show('a running total within each region',
+  running.call,
+  running.call.map {|s| [s.region, s.day, s.amount, s.running] })
+
+# 3. The functions that say nothing without a window.  row_number, rank and
+#    dense_rank number the rows of each partition; lag and lead reach the row
+#    before and after.  Each raises rather than reaching the database if over
+#    never arrives.
+ranked = -> {
+  Sale.select {
+    [:region, :amount,
+     row_number.over.partition(:region).order(:amount.desc).as(:place),
+     lag(:amount).over.partition(:region).order(:day).as(:previous)]
+  }
+}
+show('the place within the region, and the day before',
+  ranked.call,
+  ranked.call.map {|s| [s.region, s.amount, s.place, s.previous] })
+
+begin
+  Sale.select { row_number }
+rescue ArgumentError => e
+  puts '--- a window function needs a window ---'
+  puts "  #{e.message}"
+  puts
+end
+
+# 4. The top row of each group, which is what a window is most often for: the
+#    numbering goes in a subquery, since a window function cannot be used in
+#    the WHERE of the query that computes it.
+numbered = Sale.select {
+  [:region, :day, :amount, row_number.over.partition(:region).order(:amount.desc).as(:place)]
+}
+# The subquery is named after the model's own table because ActiveRecord goes
+# on qualifying columns with that name, so where has to find it there.
+show('the biggest sale of each region',
+  Sale.from(numbered, :sales).where { :place == 1 },
+  Sale.from(numbered, :sales).where { :place == 1 }.
+    map {|s| [s.region, s.day, s.amount] })

data/examples/writes.rb

@@ -0,0 +1,84 @@
+$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(:pages) do |t|
+      t.string :path
+      t.integer :hits
+      t.integer :bonus
+      t.string :title
+      t.index :path, unique: true
+    end
+  end
+end
+Setup.new.up
+
+class Page < ActiveRecord::Base
+end
+
+Page.create!(path: '/index', hits: 10, bonus: 1, title: 'home')
+Page.create!(path: '/about', hits: 3,  bonus: 0, title: 'about us')
+Page.create!(path: '/faq',   hits: 0,  bonus: 5, title: 'faq')
+
+# These statements run rather than being built, so unlike the other examples
+# the SQL is taken from the notification ActiveRecord sends for each one.
+def write(title)
+  statements = []
+  subscriber = ActiveSupport::Notifications.subscribe('sql.active_record') do |*, payload|
+    statements << payload[:sql] unless %w[SCHEMA TRANSACTION].include?(payload[:name])
+  end
+  yield
+  ActiveSupport::Notifications.unsubscribe(subscriber)
+  puts "--- #{title} ---"
+  statements.each {|sql| puts sql }
+  Page.order(:path).each {|p| puts "  #{p.path} hits=#{p.hits} title=#{p.title}" }
+  puts
+end
+
+# 1. update_all.  ActiveRecord reads its hash as literals -- update_all(hits:
+#    :hits) would set the column to the symbol itself -- and the block reads a
+#    symbol as the column it names, which is what lets the new value be worked
+#    out from the old.
+write('hits made from the old hits') do
+  Page.where { :hits > 0 }.update_all { {hits: :hits + :bonus} }
+end
+
+write('a function over the column') do
+  Page.update_all { {title: upper(:title)} }
+end
+
+# An expression as involved as any other block builds.
+write('CASE in an update') do
+  Page.update_all { {hits: case_when { :hits > 10 }.then(10).else(:hits)} }
+end
+
+# 2. upsert_all.  The block is the part that decides what happens to a row
+#    that is already there, and excluded is the row that could not be
+#    inserted.  PostgreSQL and SQLite name it that; MySQL says VALUES(column),
+#    and the block comes out as whichever the adapter reads.
+incoming = [
+  {path: '/index', hits: 100, bonus: 0, title: 'HOME'},
+  {path: '/new',   hits: 7,   bonus: 0, title: 'NEW'},
+]
+write('the old value and the new one added together') do
+  Page.upsert_all(incoming, unique_by: :path) { {hits: :hits + excluded(:hits)} }
+end
+
+# Without a block, upsert_all overwrites -- that is ActiveRecord's own
+# behaviour, and the block is what makes the old value reachable.
+write('and without a block it is a plain overwrite') do
+  Page.upsert_all([{path: '/index', hits: 1, bonus: 0, title: 'HOME'}],
+                  unique_by: :path)
+end
+
+# insert_all has no block: ActiveRecord type-casts each value into the VALUES
+# list, so an expression there would become nothing rather than SQL.
+write('insert_all takes literals') do
+  Page.insert_all([{path: '/legal', hits: 0, bonus: 0, title: 'legal'}])
+end