activerecord-refined 0.9.0 → 0.10.0

data/docs/grouping.md

@@ -0,0 +1,55 @@
+# Grouping
+
+## Keeping one row per group
+
+
+`distinct_on` is PostgreSQL's `DISTINCT ON`: the first row of each group the
+order brings up.
+
+```ruby
+Post.distinct_on { :author_id }.order { [:author_id, :likes.desc] }
+# SELECT DISTINCT ON ( "author_id" ) "posts".* FROM "posts"
+#   ORDER BY "author_id", "likes" DESC
+```
+
+Arel carries the node and refuses to write it for the others, the way it does
+a regexp, so it raises `NotImplementedError` on SQLite and MySQL. The shape
+that runs everywhere is a `row_number` window in a subquery, which says the
+same thing at more length:
+
+```ruby
+ranked = Post.select {
+  [:author_id, :likes, row_number.over.partition(:author_id).order(:likes.desc).as(:rn)]
+}
+Post.from(ranked, :posts).where { :rn == 1 }
+```
+
+The subquery is named after the model's own table for the reason `from_cte`
+is: Active Record goes on qualifying columns with that name, so `where` needs
+to find it.
+
+## Grouping several ways at once
+
+
+`grouping_sets`, `rollup` and `cube` ask for more than one grouping in a
+single query, the totals of each coming back beside the rows. Each set is a
+list of its own, and an empty one is the grand total:
+
+```ruby
+Sale.group { grouping_sets([:region], [:product], []) }.
+  select { [:region, :product, sum(:amount).as(:total)] }
+# GROUP BY GROUPING SETS( ( "region" ), ( "product" ), (  ) )
+
+Sale.group { rollup(:region, :product) }   # GROUP BY ROLLUP( "region", "product" )
+Sale.group { cube(:region, :product) }     # GROUP BY CUBE( "region", "product" )
+```
+
+A row that a set did not group by comes back with NULL there, which is also
+what a real NULL looks like; `fn(:grouping, :region)` tells the two apart.
+
+`grouping_sets` and `cube` are PostgreSQL's; SQLite has none of the three and
+both raise `NotImplementedError` elsewhere. `rollup` runs on MySQL and
+MariaDB too, spelled as their `WITH ROLLUP` — which trails the whole group
+list, so there a rollup cannot stand beside other group entries the way
+`ROLLUP(...)` can, and the block says so. MariaDB is also the one that
+refuses `ORDER BY` next to it, and the one without `fn(:grouping, ...)`.

data/docs/joins.md

@@ -0,0 +1,73 @@
+# Joins
+
+## Joins
+
+
+The block is the `ON` clause:
+
+```ruby
+Author.
+  joins(:posts) { :posts[:author_id] == :authors[:id] }.
+  joins(:comments) { :comments[:post_id] == :posts[:id] }
+
+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"
+```
+
+`right_outer_joins` and `full_outer_joins` are the two Active Record has no
+method for, and they take what `joins` takes. An association name is not among
+it: what Active Record reads out of one is an inner or a left join and nothing
+else, so these two want the block that says how to join.
+
+```ruby
+Author.right_outer_joins(:posts) { :posts[:author_id] == :authors[:id] }
+Author.full_outer_joins(:posts) { :posts[:author_id] == :authors[:id] }
+```
+
+MySQL has no `FULL OUTER JOIN` and neither has MariaDB, so `full_outer_joins`
+raises `NotImplementedError` there. SQLite has had one since 3.39.
+
+`cross_joins` is every row of one table against every row of the other. There
+is no condition to give, so it takes no block — `as` still names the table:
+
+```ruby
+Post.cross_joins(:authors)              # FROM "posts" CROSS JOIN "authors"
+Post.cross_joins(:posts, as: :others)   # FROM "posts" CROSS JOIN "posts" "others"
+```
+
+## Lateral joins
+
+
+A relation marked `lateral` joins in place of a table, and sees the row being
+joined to — in SQL the keyword modifies the subquery, not the join, so that is
+where it is written. It is what makes the top row of each group reachable in
+one query:
+
+```ruby
+top_post = Post.select { :title }.
+  where { :posts[:author_id] == :authors[:id] }.
+  order { :likes.desc }.limit(1)
+
+Author.left_outer_joins(top_post.lateral, as: :top).
+  select { [:name, :top[:title].as(:top_post)] }
+# SELECT "name", "top"."title" AS "top_post" FROM "authors"
+#   LEFT OUTER JOIN LATERAL (SELECT "title" FROM "posts"
+#     WHERE "posts"."author_id" = "authors"."id" ORDER BY "likes" DESC LIMIT 1) "top" ON TRUE
+```
+
+`as` is required — the relation has no name of its own to qualify with. Without
+a block the join is `ON TRUE`, which is the usual shape: what the subquery is
+allowed to see is said inside it. A block writes a real `ON` clause.
+
+PostgreSQL has `LATERAL` and so has MySQL, from 8.0.14. SQLite has none, and
+neither has MariaDB, which answers to the same adapter as MySQL; both raise
+`NotImplementedError`. Arel has a node for it but only PostgreSQL's visitor
+writes it, so the SQL is written here instead.

data/docs/json.md

@@ -0,0 +1,230 @@
+# JSON
+
+
+`dig` reads inside a JSON document, by the name of what `Hash` does. A string
+or symbol steps into an object, an integer into an array, and what comes back
+is still JSON — the way `Hash#dig` hands back the structure itself — for a
+document to be dug into further or asked the JSON questions. `dig_text` gives
+the value as text instead, which is what a comparison wants:
+
+```ruby
+Post.where { :meta.dig_text(:author, :name) == "alice" }
+Post.select { :meta.dig(:author).as(:author) }
+Post.where { :meta.key?(:draft) }
+Post.where { :meta.contains?(status: "open") }
+```
+
+No two adapters spell any of this alike, and the block is the same on all
+three:
+
+| | PostgreSQL | SQLite | MySQL |
+| --- | --- | --- | --- |
+| `dig(:a, :b)` | `#> '{a,b}'` | `-> '$.a.b'` | `JSON_EXTRACT(…, '$.a.b')` |
+| `dig_text(:a, :b)` | `#>> '{a,b}'` | `->> '$.a.b'` | `JSON_UNQUOTE(JSON_EXTRACT(…, '$.a.b'))` |
+| `key?(:a)` | `? 'a'` | `json_type(…, '$.a') IS NOT NULL` | `JSON_CONTAINS_PATH(…, 'one', '$.a')` |
+| `contains?(…)` | `@>` | — | `JSON_CONTAINS` |
+
+MariaDB answers to the `mysql2` adapter and has none of `->` or `->>`, so the
+MySQL family goes through the functions, which both have.
+
+`dig_text` gives text everywhere. SQLite's `->>` would otherwise hand back the
+value with its type, so a comparison that worked there would fail on the other
+two; a number is compared through a `cast` on all three:
+
+```ruby
+Post.where { :meta.dig_text(:n) == "5" }
+Post.where { cast(:meta.dig_text(:n), "integer") > 6 }   # 'signed' on MySQL
+```
+
+The type is the adapter's own name for it, here as everywhere `cast` is used.
+
+Strings and numbers are where the adapters agree. A JSON boolean comes back as
+`"1"` on SQLite, which turns `true` into SQL's `1` before the text cast, and
+as `"true"` on the other two; a JSON `null` is SQL `NULL` everywhere but
+MariaDB, which spells it `"null"`. A key that is not there is `NULL` on all
+three.
+
+Comparing `dig_text`'s value with anything but a string raises
+`ArgumentError` rather than being left to the adapters, which answer it three
+ways: `dig_text(:n) == 5` is true on SQLite, an error on PostgreSQL and true
+on MySQL, and `dig_text(:flag) == true` is true, an error and false. `cast`
+is what says which type was meant, and then all three agree.
+
+A JSON comparison — `dig`'s side, and `bury`'s and `except`'s — belongs to
+the JSON types: on PostgreSQL's `jsonb` and MySQL's `JSON` alike, numbers
+compare as numbers and documents structurally, key order and spelling aside,
+so a dug value compares with a Ruby one directly. SQLite and MariaDB have
+only the text of each, which is a different question, and raise
+`NotImplementedError` as the SQL is written. `in?` and `between?` are the
+two MySQL leaves out of its JSON comparisons, so there they are spelled as
+the comparisons they mean — the range as its bounds, the list as one
+equality per element, which names the dug value once per element the way
+SQLite's XOR names its operands twice:
+
+```ruby
+Post.where { :meta.dig(:stars) >= 10 }              # PostgreSQL and MySQL
+Post.where { :meta.dig(:author) == { "name" => "alice" } }
+Post.where { :meta.dig(:stars).in?([5, 10]) }
+Post.where { cast(:meta.dig_text(:stars), "integer") >= 10 }   # everywhere
+```
+
+A column, a function or another dug value on the right goes through untouched
+on every adapter. Arithmetic and the bit operators are refused outright on
+both sides — `dig_text(:n) + 1` is 6 on SQLite, an error on PostgreSQL and
+6.0 on MariaDB — and `cast` settles those too.
+
+`bury` sets what `dig` reads: the last argument is the value and the rest are
+the path to it. The document comes back changed rather than being written
+anywhere, so `update_all` is what makes it stick:
+
+```ruby
+Post.update_all { { meta: :meta.bury(:author, :name, "alice") } }
+# SET "meta" = jsonb_set("meta", '{author,name}', '"alice"')
+# ...          JSON_SET("meta", '$.author.name', 'alice')   elsewhere
+
+Post.update_all { { meta: :meta.bury(:tags, ["ruby", "sql"]) } }
+Post.update_all { { meta: :meta.bury(:copy, :meta.dig(:n)) } }
+```
+
+A whole document goes in as one — an object or an array rather than the string
+that spells it — which each adapter takes its own way round, and a boolean
+goes in as JSON too, which SQLite would otherwise write as its `1`. `bury` is
+not a Ruby method; it is the name Ruby considered for the other end of `dig`,
+and
+SQL has no one name to borrow here, since PostgreSQL says `jsonb_set` where
+the others say `JSON_SET`.
+
+`except` takes keys out again, and takes them as `Hash#except` does — keys of
+the document, however many, rather than a path, which is `bury`'s way of
+reaching further in. It gives back the document changed, so it chains with
+`bury` and goes where `bury` goes:
+
+```ruby
+Post.update_all { { meta: :meta.except(:draft) } }
+# SET "meta" = "meta" - CAST('{"draft"}' AS text[])
+# ...          JSON_REMOVE("meta", '$.draft')   elsewhere
+
+Post.update_all { { meta: :meta.bury(:author, :name, "alice").except(:tmp) } }
+```
+
+A key that is not there is not an error, as it is not to `Hash#except`. The
+cast is not decoration: `jsonb` has three subtractions — a key, an array of
+keys, an element by index — and an array literal written without a type is
+read as the first of them, so `"meta" - '{draft}'` takes out the key spelled
+`{draft}`, which is nothing, and says nothing about it.
+
+A key deeper in is reached through the chain: `dig` reads the part out,
+`except` takes the key from it, and `bury` puts it back:
+
+```ruby
+Post.update_all { { meta: :meta.bury(:author, :meta.dig(:author).except(:email)) } }
+```
+
+What `dig` gives is a document, so the JSON operations read it — the same
+question asked of a part of the document rather than of all of it:
+
+```ruby
+Post.where { :meta.dig(:author).key?(:email) }
+Post.where { :meta.dig(:author).dig_text(:name) == "alice" }
+Post.update_all { { meta: :meta.dig(:author).bury(:name, "alice") } }
+```
+
+Containment reads it too, on the adapters that have containment at all:
+
+```ruby
+Post.where { :meta.dig(:tags).contains?(["ruby"]) }
+```
+
+Asking the same of `dig_text` raises `ArgumentError`: what it gives is text,
+and reading text back as a document is where the adapters part company —
+SQLite parses it, MySQL takes it as written, and PostgreSQL has no such
+function for text at all.
+
+`contains?` has no equivalent on SQLite and raises `NotImplementedError`
+there — later than the rest, since the adapter is only known when the SQL is
+built. On PostgreSQL, `dig` and `dig_text` are all the `json` type carries;
+`key?`, `contains?`, `bury` and `except` want a `jsonb` column.
+
+A key that is not a plain name travels as itself rather than being refused:
+`dig(:'odd key')` becomes `'{odd key}'` or `$."odd key"`.
+
+`keys` gives the keys of the document, as `Hash#keys` does — a JSON array
+of them. Only the MySQL family has a function for it; the other two reach
+the same array through a subquery over their key-listing functions, guarded
+by type so that all four answer alike: the keys of anything that is not an
+object are `NULL` — rather than SQLite's array indices or PostgreSQL's
+error — and the keys of `{}` are `[]` rather than PostgreSQL's `NULL`:
+
+```ruby
+Post.select { :meta.keys.as(:fields) }
+Post.select { :meta.dig(:author).keys.as(:author_fields) }
+# JSON_KEYS("meta")                                              MySQL
+# CASE WHEN jsonb_typeof("meta") = 'object' THEN COALESCE((…))   PostgreSQL
+# CASE WHEN json_type("meta") = 'object' THEN (SELECT …)         SQLite
+```
+
+The order the keys come in is the adapters' own: the JSON types give their
+normalized order and the text ones the stored order — the same divide every
+JSON comparison here rides on.
+
+`json_array` and `json_object` build a document in the row — `json_array`
+from the values given, `json_object` from a Ruby hash. The names are the
+standard's, which SQLite and the MySQL family say as written; PostgreSQL is
+asked to build `jsonb`. A hash rather than SQL's alternating keys and
+values, because a bare symbol means a column in every block here: the keys
+are Ruby's and the values are expressions, so `title: :title` reads the
+column in under its own name with no rule to remember:
+
+```ruby
+Post.select { json_object(title: :title, stars: :meta.dig(:stars)).as(:summary) }
+# jsonb_build_object('title', "title", 'stars', "meta" #> '{stars}')   PostgreSQL
+# JSON_OBJECT('title', "title", 'stars', JSON_EXTRACT(…))              elsewhere
+
+Post.where { :meta.dig(:author) == json_object(name: :name) }
+```
+
+A Ruby value among the arguments goes in as its JSON self — a string or a
+number as themselves, `nil` as `null`, and a boolean or a whole document
+through the same route `bury` takes them, so SQLite's `true` is not its
+`1`. A key that is not a string or a symbol is refused, before the
+adapters answer a NULL key three ways. The empty calls stand —
+`json_array()` is `[]` and `json_object()` is `{}` on all four — and what
+comes back is JSON as `dig`'s is, so the operations and comparisons above
+read it.
+
+`json_arrayagg` and `json_objectagg` gather rows into one JSON document — a
+value from each row into an array, a key and a value into an object. The
+names are the SQL standard's, which the MySQL family says as written;
+PostgreSQL is asked the `jsonb` pair and SQLite its own:
+
+```ruby
+Post.group { :author_id }.select { json_arrayagg(:title).as(:titles) }
+# jsonb_agg("title")          PostgreSQL
+# json_group_array("title")   SQLite
+# JSON_ARRAYAGG("title")      MySQL
+
+Post.select { json_objectagg(:title, :meta.dig(:stars)).as(:stars) }
+
+Post.group { :author_id }.
+  select { json_arrayagg(json_object(title: :title, stars: :meta.dig(:stars))).as(:posts) }
+```
+
+What they give is JSON as `dig`'s is, so it compares the way a dug value
+does, and `filter` and `over` come along as with any aggregate — with two
+refusals where a respelling would change the meaning rather than the
+spelling. The MySQL family has no `FILTER`, and the `CASE` that stands in
+for it elsewhere would leave a JSON `null` in the document for every row it
+drops, so there `filter` raises `NotImplementedError`; MariaDB takes every
+other aggregate as a window function but not these two, so `over` raises
+there too.
+
+The documents agree across adapters, up to the edges of their JSON types.
+Over no rows at all SQLite answers `[]` and `{}` where the others answer
+`NULL`, as their aggregates do. A key aggregated twice keeps the last pair
+on the JSON types — `jsonb` and MySQL's — and every pair on the text ones,
+SQLite and MariaDB, and a `NULL` key is an error on the former pair and a
+dropped pair on the latter. And a bare JSON *column* is text to SQLite's
+`json_group_array`, so it lands as the string that spells the document
+rather than nesting as it does on the other three; a dug value nests
+everywhere, so `json_arrayagg(:meta.dig(:author))` is the portable way to
+collect part of a document.

data/docs/ordering.md

@@ -0,0 +1,55 @@
+# Aliases, ordering and collation
+
+## Aliases and ordering
+
+
+`.as` gives an expression a column alias, and `.asc` / `.desc` give an
+ordering its direction. The orderings take `.nulls_first` / `.nulls_last` as
+well. 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 }
+```
+
+Together:
+
+```ruby
+Author.
+  joins(:posts) { :posts[:author_id] == :authors[:id] }.
+  where { :posts[:published] == true }.
+  group { :authors[:id] }.
+  having { count(:posts[:id]) > 1 }.
+  order { count(:posts[:id]).desc }.
+  select {
+    [
+      upper(:authors[:name]).as(:author),
+      count(:posts[:id]).as(:post_count),
+      avg(:posts[:likes]).as(:avg_likes),
+    ]
+  }
+```
+
+## Collation
+
+
+`.collate` names a collation for a comparison or an ordering — how the
+database decides two strings are equal and which comes first — and gives back
+an expression, so the collation carries into either:
+
+```ruby
+Author.where { :name.collate(:nocase) == "alice" }
+# WHERE "authors"."name" COLLATE nocase = 'alice'
+
+Author.order { :name.collate(:nocase).asc }
+```
+
+The collation names are the database's own, so they are not portable — SQLite's
+`nocase`, PostgreSQL's `"C"`, MySQL's `utf8mb4_bin`. PostgreSQL folds an
+unquoted name to lower case, where its built-in names are upper, so it quotes
+the name for you.
+
+On the databases that take the name bare, it has to be a plain identifier: a
+hyphen would read as a subtraction, so a name with one is refused. PostgreSQL
+quotes the name, so a hyphen is safe there, and its ICU collations —
+`en-US-x-icu` and the rest — are spelled with them.

data/docs/time_zones.md

@@ -0,0 +1,30 @@
+# Time zones
+
+
+Active Record stores a datetime in UTC unless `ActiveRecord.default_timezone`
+says `:local`, and a value a block quotes follows it: a `Time` on the right of
+a comparison is converted the way Active Record converts one, so
+`where { :created_at > Time.current - 1.day }` is right whatever `Time.zone`
+is. What is not converted is what the database says the time is.
+
+`current_timestamp` and its relatives are the server's clock in the session's
+zone. Active Record sets PostgreSQL's session to UTC and SQLite's clock is UTC
+already, so on those two the clock and the stored values agree. MySQL's
+session keeps the server's own zone, so a server that sits in Tokyo answers
+`CURRENT_TIMESTAMP` nine hours off the values Active Record stored; set the
+session in `database.yml` — `variables: { time_zone: "+00:00" }` — or write
+`Time.current` in the block instead, which is right everywhere. SQL Server
+answers in its operating system's zone and Oracle in the client's, where
+`Time.current` is again the one to reach for. `current_date` is today in UTC,
+which in Tokyo is still yesterday until nine in the morning; `Date.current`
+says the day meant.
+
+`extract`, `date_trunc` and a `group` by day cut at UTC's midnight. A zone
+without daylight saving is a fixed offset away —
+`date_trunc("day", :created_at + 9.hours)` — and one with it needs the
+database's own `AT TIME ZONE`, through `sql`.
+
+A datetime computed in the query, `(:created_at + 1.hour).as(:later)`, has no
+column to take a type from, so it comes back as a `Time` in UTC — as text on
+SQLite — with no `Time.zone` applied; `in_time_zone` on the Ruby side does
+that.

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

@@ -91,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/expressions.rb

@@ -16,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
@@ -24,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} ---"
@@ -64,6 +71,17 @@ show("a tax through BigDecimal, exact on the wire",
   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.
@@ -89,12 +107,17 @@ rescue ArgumentError => e
 end
 
 # 2. Aggregates.  count takes :* for COUNT(*) and distinct: true for
-#    COUNT(DISTINCT ...); the rest are sum, avg, min and max.
+#    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] })
 
+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.
@@ -173,6 +196,13 @@ 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",
   LineItem.