activerecord-refined 0.9.0 → 0.10.0

data/activerecord-refined.gemspec

@@ -13,14 +13,12 @@ Gem::Specification.new do |gem|
   gem.description   = "Adding clean and powerful query syntax on Active Record using refinements"
   gem.summary       = "Write Active Record queries as Ruby expressions"
   gem.homepage      = "https://github.com/shugo/activerecord-refined"
+  gem.license       = "MIT"
+  gem.metadata      = {
+    "documentation_uri" => "https://rubydoc.info/gems/activerecord-refined",
+  }
 
-  # sandbox/ is a site, not part of the library: its Gemfile.lock and
-  # package-lock.json have no business in anyone's bundle.  CLAUDE.md and
-  # .claude/ are addressed to whoever is working on the repository, not to
-  # anyone using it.
-  gem.files         = `git ls-files`.split($/).grep_v(%r{^sandbox/|^CLAUDE\.md$|^\.claude/})
-  gem.executables   = gem.files.grep(%r{^bin/}).map { |f| File.basename(f) }
-  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.files         = `git ls-files -- lib docs examples README.md LICENSE.txt .yardopts activerecord-refined.gemspec`.split($/)
   gem.require_paths = ["lib"]
 
   # Proc#refined is available since Ruby 4.1. 4.1.0.dev is required to allow
@@ -44,4 +42,11 @@ Gem::Specification.new do |gem|
   gem.add_development_dependency "rubocop-performance", [">= 0"]
   gem.add_development_dependency "rubocop-rails", [">= 0"]
   gem.add_development_dependency "rubocop-md", [">= 0"]
+  # What renders the reference: `yard server --reload` serves it locally, and
+  # rubydoc.info renders the same .yardopts.  The plugin turns the README's
+  # relative links to docs/*.md -- which GitHub follows as they are -- into
+  # links to YARD's file pages; where it is not installed, rubydoc.info among
+  # them, YARD says so and leaves the links relative.
+  gem.add_development_dependency "yard", [">= 0"]
+  gem.add_development_dependency "yard-markdown-relative-links", [">= 0"]
 end

data/docs/conditions.md

@@ -0,0 +1,206 @@
+# Conditions
+
+
+```ruby
+Author.where { :age >= 18 }
+Author.where { :name.like?("A%") }          # LIKE
+Author.where { :age.in?(20..40) }           # BETWEEN
+Author.where { :age.between?(20, 40) }      # BETWEEN
+Author.where { :age.in?(18..) }             # >= 18
+Author.where { :country.in?(%w[JP US]) }    # IN
+Author.where { :country.null? }             # IS NULL
+```
+
+`!` negates any of these. Where SQL has a negative of its own, so does the
+block, which is the same rows written the way they would be written by hand:
+
+```ruby
+Author.where { :country.not_null? }             # IS NOT NULL
+Author.where { :country.not_in?(%w[JP US]) }    # NOT IN
+Author.where { :age.not_between?(20, 40) }      # not between 20 and 40
+Author.where { :name.not_like?("A%") }          # NOT LIKE
+Author.where { :name.not_ilike?("a%") }         # NOT ILIKE / NOT LIKE
+
+Author.where { !:name.start_with?("A") }        # NOT (name LIKE 'A%')
+```
+
+Nothing turns on the choice: `NOT (country IS NULL)` and `country IS NOT NULL`
+select the same rows, NULLs included. `not_between?` is the one whose SQL
+looks unlike its name — Arel writes it as the two comparisons, `age < 20 OR
+age > 40`, which is again the same rows.
+
+A number compares as itself, the way a bound `?` does: `:age >= 99.5` says
+`>= 99.5`, where `where(age: 99.5..)` casts to the column's type and says
+`>= 99`, letting an age of 99 through a bound it does not satisfy. Everything
+that is not an `Integer`, `Float` or `BigDecimal` keeps the column's own
+serialization — an enum's name, a time's zone, a custom type's scaling — so a
+custom type that scales a number, money kept in cents, is the one place the
+number has to be written as the column stores it.
+
+A boolean column has `true?` and `false?`, which become SQL's `IS TRUE` and
+`IS FALSE`, and the two negations to go with them:
+
+```ruby
+Post.where { :published.true? }         # IS TRUE
+Post.where { :published.not_true? }     # IS NOT TRUE
+Post.where { :published.false? }        # IS FALSE
+Post.where { :published.not_false? }    # IS NOT FALSE
+```
+
+`published = TRUE` selects the same rows as `published IS TRUE`, so the
+difference is in the negation: `published = TRUE` is itself NULL for a row
+where the column is, and a NULL predicate selects nothing, while `IS TRUE`
+answers false there. `not_true?` is therefore "false or never set" and
+`!(:published == true)` only "false". Every adapter spells all four the same
+way and answers them alike.
+
+`in?` also takes a relation as a subquery. Without an explicit select list the
+subquery selects the relation's primary key, the same way Active Record's own
+`where(id: relation)` does:
+
+```ruby
+Author.where { :id.in?(Post.published.select(:author_id)) }
+# "authors"."id" IN (SELECT "posts"."author_id" FROM "posts" WHERE ...)
+```
+
+A relation on the right of a comparison is a scalar subquery. It has to select
+one value, so unlike `in?` there is no default select list and one is
+required:
+
+```ruby
+Author.where { :age >= Author.select { avg(:age) } }
+# "authors"."age" >= (SELECT AVG("authors"."age") FROM "authors")
+```
+
+`any` and `all` quantify that comparison instead, which is what lifts the
+one-row rule: `> any` asks whether the subquery holds a smaller value anywhere,
+`>= all` whether it holds a larger one nowhere.
+
+```ruby
+Author.where { :age > any(Author.where(country: "JP").select(:age)) }
+# "authors"."age" > ANY(SELECT "authors"."age" FROM "authors" WHERE ...)
+
+Author.where { :age >= all(Author.select(:age)) }
+# "authors"."age" >= ALL(SELECT "authors"."age" FROM "authors")
+```
+
+The select list follows `in?`'s rule rather than the scalar one: without an
+explicit select the subquery selects the primary key. `== any` is what `IN`
+says and `!= all` what `NOT IN` says, so what the quantifiers add is the four
+comparisons `IN` has no spelling for. SQLite has neither quantifier, and says
+so with `NotImplementedError` rather than leaving its parser to.
+
+`exists?` takes a relation and becomes `EXISTS (SELECT ...)`. Correlate the
+subquery with the outer table through qualified columns — its `where` block
+goes through the DSL like any other:
+
+```ruby
+Author.where { exists?(Post.where { :posts[:author_id] == :authors[:id] }) }
+# EXISTS (SELECT "posts".* FROM "posts" WHERE "posts"."author_id" = "authors"."id")
+
+Author.where { !exists?(Post.where { :posts[:author_id] == :authors[:id] }) }
+# NOT (EXISTS (...))
+```
+
+`like?` is case-sensitive `LIKE` on every adapter, including PostgreSQL, where
+Arel would otherwise reach for `ILIKE`. `ilike?` is the one that asks for
+`ILIKE`; off PostgreSQL it is plain `LIKE`, which those adapters already match
+case-insensitively under their default collations. `casecmp?` is
+case-insensitive equality, folded on both sides rather than left to the
+collation, so it means the same thing everywhere:
+
+```ruby
+Author.where { :name.ilike?("ma%") }        # ILIKE 'ma%' / LIKE 'ma%'
+Author.where { :name.casecmp?("Alice") }     # LOWER(name) = LOWER('Alice')
+```
+
+`not_distinct_from?` and `distinct_from?` compare with NULL treated as a
+value, rather than as the unknown that makes `=` and `<>` neither true nor
+false. PostgreSQL spells this `IS [NOT] DISTINCT FROM`, SQLite `IS` / `IS NOT`
+and MySQL `<=>`, and the rows that come back are the same on all three:
+
+```ruby
+Author.where { :country.not_distinct_from?(params[:country]) }  # matches NULL to nil
+Author.where { :country.distinct_from?("JP") }                  # keeps the NULL rows
+```
+
+`start_with?`, `end_with?` and `include?` are shortcuts for the usual `like?`
+patterns. Unlike `like?`, they treat their argument as a literal string, so `%`
+and `_` in it are escaped rather than matched as wildcards:
+
+```ruby
+Author.where { :name.start_with?("A") }     # LIKE 'A%'
+Author.where { :name.end_with?("son") }     # LIKE '%son'
+Author.where { :name.include?("test") }     # LIKE '%test%'
+```
+
+Like their String namesakes, `start_with?` and `end_with?` take any number of
+literals; matching any one of them is enough:
+
+```ruby
+Author.where { :name.start_with?("A", "B") }
+# (name LIKE 'A%' OR name LIKE 'B%')
+```
+
+`member?`, `superset?`, `subset?` and `intersect?` compare against a
+PostgreSQL array column, each carrying the meaning of its Ruby namesake:
+`member?` is Enumerable's element test (which String does not have — that is
+what separates it from `include?`), `superset?` and `subset?` are Set's
+whole-array containment, and `intersect?` is Array's "any element in common":
+
+```ruby
+Article.where { :tags.member?("ruby") }            # tags @> '{ruby}'
+Article.where { :scores.member?(80) }              # scores @> '{80}'
+Article.where { :tags.superset?(%w[ruby rails]) }  # tags @> '{ruby,rails}'
+Article.where { :tags.subset?(%w[ruby rails go]) } # tags <@ '{ruby,rails,go}'
+Article.where { :tags.intersect?(%w[ruby go]) }    # tags && '{ruby,go}'
+```
+
+Like its namesake, `member?` takes one element — `[1, 2].member?([1])` is
+false in Ruby, so an Array argument raises rather than quietly meaning
+something `Array#member?` does not. Requiring every element is `superset?`.
+
+`=~` and `!~` match a regular expression: `REGEXP` and `NOT REGEXP` on MySQL,
+`~` and `!~` on PostgreSQL. SQLite has no regexp operator of its own, so it
+raises there.
+
+```ruby
+Author.where { :name =~ "^A" }              # REGEXP / ~
+Author.where { :name !~ "^A" }              # NOT REGEXP / !~
+Author.where { :name =~ /son$/ }            # a Regexp literal works too
+```
+
+Only a literal's source crosses over; the database has its own dialect and no
+equivalent of Ruby's flags. Dropping one would silently change what the query
+matches, so `/son$/i` raises instead — pass the pattern as a string if the
+database can express what you mean.
+
+`==` always means SQL `=`, and passes its value through untouched. A Range or an
+Array therefore compares against a PostgreSQL range or array column, the same
+way Active Record's own `where(period: from...to)` does for those column types:
+
+```ruby
+Reservation.where { :period == (from...to) }   # daterange = '[from,to)'
+Article.where { :tags == %w[ruby rails] }      # text[] = '{ruby,rails}'
+```
+
+`!=` is SQL `!=` under the same rules, value passed through untouched.
+
+For the same reason `== nil` and `!= nil` raise `ArgumentError`: `= NULL` is
+never true in SQL, so a NULL test has to be spelled as one. Use `null?`:
+
+```ruby
+Author.where { :country.null? }             # country IS NULL
+Author.where { !:country.null? }            # NOT (country IS NULL)
+```
+
+Combine predicates with `&`, `|` and `!`. Ruby's operator precedence makes the
+parentheses around each comparison necessary, though the `?` methods above need
+none:
+
+```ruby
+Author.where { (:age >= 18) & ((:country == "JP") | (:country == "US")) }
+Author.where { !(:age.in?(0..17) | :country.null?) }
+Author.where { !:country.in?(%w[JP US]) }   # NOT (country IN ('JP', 'US'))
+Author.where { !:name.like?("%test%") }     # NOT (name LIKE '%test%')
+```

data/docs/ctes.md

@@ -0,0 +1,65 @@
+# Common table expressions
+
+
+Active Record's `with` and `with_recursive` need nothing from this gem: a CTE
+is joined by name like any other table, so its `ON` clause is a block, where
+Rails' own documentation reaches for a string join.
+
+`from_cte` takes the CTE's name and selects it under the model's own table
+name, so the model's columns resolve:
+
+```ruby
+Node.with_recursive(
+  tree: [
+    Node.where { :id == root.id }.
+      select { [:id, :name, :parent_id, 0.as(:depth)] },
+    Node.joins(:tree) { :nodes[:parent_id] == :tree[:id] }.
+      select { [:id, :name, :parent_id, (:tree[:depth] + 1).as(:depth)] },
+  ]
+).from_cte(:tree)
+# WITH RECURSIVE "tree" AS (
+#   SELECT "nodes"."id", "nodes"."name", "nodes"."parent_id", 0 AS depth
+#     FROM "nodes" WHERE "nodes"."id" = 1
+#   UNION ALL
+#   SELECT "nodes"."id", "nodes"."name", "nodes"."parent_id",
+#          ("tree"."depth" + 1) AS depth
+#     FROM "nodes" INNER JOIN "tree" ON "nodes"."parent_id" = "tree"."id"
+# ) SELECT "nodes".* FROM "tree" AS "nodes"
+```
+
+The anchor starts the count and the recursive member adds one, which is how
+the shape of a tree comes out of a flat table. The `0` is a value rather than
+SQL — see [`value`](functions.md) for why a number can say `.as` directly.
+
+The alias on the last line is there for Active Record's sake, not SQL's:
+written by hand that line would be `SELECT * FROM tree`. Active Record goes on qualifying
+columns with the model's table name, so without the alias that name is not in
+the query and anything qualifying a column fails:
+
+```ruby
+Node.with_recursive(tree: [...]).from(:tree).where(name: 'root')
+# PG::UndefinedTable: missing FROM-clause entry for table "nodes"
+```
+
+Since the model's name is the only one that works, `from_cte` takes it from
+the model rather than asking. It also checks that the name is one `with`
+declares, so a typo is an `ArgumentError` here rather than a query against a
+table nobody has — checked when the SQL is built, so the CTE may be declared
+later in the chain or by a scope merged into it.
+
+`from(:tree, as: :nodes)` is the same thing spelled out, without the check,
+and is what to reach for when the name wanted is not the model's.
+
+What makes this worth spelling out is how selectively it breaks. `count`,
+`order` and `select` never qualify, so they work without the alias on every
+adapter; it is `where` and `find_by` that stop. A query can therefore look
+right until the day a condition is added to it.
+
+A non-recursive CTE joins the same way:
+
+```ruby
+Node.with(roots: Node.where { :parent_id.null? }).
+  joins(:roots) { :roots[:id] == :nodes[:parent_id] }
+```
+
+`examples/ctes.rb` walks a category tree with these.

data/docs/expressions.md

@@ -0,0 +1,125 @@
+# Expressions
+
+
+`+`, `-`, `*` and `/` build arithmetic. Ruby puts them above the comparison
+operators, so an expression groups the way it reads:
+
+```ruby
+Item.where { :price * :quantity > 1000 }
+Item.select { sum(:price * :quantity).as(:total) }
+```
+
+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 — and
+`BigDecimal` is a number here, being what a decimal column's values are,
+quoted as the exact decimal on either side. A `Rational` is refused: no
+decimal spells `1/3r` exactly, and `to_d` is what says the decimal meant.
+
+```ruby
+Item.select { greatest(20 - :quantity, 0).as(:shortfall) }
+Item.where { BigDecimal("1.08") * :price > 500 }
+```
+
+`&`, `|`, `^`, `~`, `<<` and `>>` are SQL's bitwise operators. Between
+conditions `&` and `|` are AND and OR, and that is where they are defined,
+which leaves them free to mean here what SQL means by them:
+
+```ruby
+Post.where { :flags & 4 > 0 }
+# WHERE ("posts"."flags" & 4) > 0
+
+Post.select { (:flags | 4).as(:flags) }
+Post.select { (~:flags).as(:inverted) }
+```
+
+Each parenthesises itself, which is what keeps Ruby's grouping: PostgreSQL
+gives `&` and `|` the same precedence and reads `a | b & c` from the left,
+where Ruby reads the `&` first.
+
+A boolean column is refused rather than taken for the one bit it is stored as.
+MySQL and SQLite would quietly answer as `AND` would, PostgreSQL has no such
+operator at all, and one block meaning two things is worse than an
+`ArgumentError` saying that `true?` is what makes a boolean column a
+condition. A condition as an operand is refused for the same reason.
+
+XOR is the one the three do not share, and the one where guessing costs most:
+MySQL spells it `^`, which is exponentiation to PostgreSQL, and PostgreSQL
+spells it `#`, which is where a comment starts on MySQL — either way a wrong
+answer rather than an error. Each adapter gets its own, and SQLite, which has
+no XOR at all, gets the two operations it is made of, `(a | b) - (a & b)`.
+That names each operand twice, so keep them cheap.
+
+`bit_and`, `bit_or` and `bit_xor` are the aggregates of the first three, and
+`bit_count` counts the bits that are set. SQLite has none of the four.
+PostgreSQL counts the bits of a bit string rather than of a number, so the
+argument is cast there, to `bit(64)` because that is what makes a negative
+count as it does on MySQL:
+
+```ruby
+Post.group { :author_id }.select { bit_or(:flags).as(:flags) }
+# SELECT BIT_OR("posts"."flags") AS "flags" ... GROUP BY "posts"."author_id"
+
+Post.select { bit_count(:flags).as(:bits) }
+# MySQL:      BIT_COUNT("posts"."flags")
+# PostgreSQL: BIT_COUNT(CAST("posts"."flags" AS bit(64)))
+```
+
+`bit_xor` arrived in PostgreSQL 14. `~` is where the three disagree about the
+answer rather than the question: MySQL reads it back as the unsigned 64-bit
+number, the others as a negative one, and the bits are the same either way.
+
+One place asks for a value to be said out loud: the top of a select list.
+Everywhere else a bare literal is already a value — `where { :age > 18 }`,
+`concat(:name, '-x')` — but a bare string at the top of the list would be SQL
+to Active Record and a value everywhere else in the block, so it is refused
+rather than read either way: `sql` says the SQL, `value` the value. `value`
+carries the predications and arithmetic with it, so a literal can be compared
+and combined like anything else, and numbers and strings have a shorthand,
+since a literal that has been sent `as` has already said it is a value:
+
+```ruby
+Node.select { [:id, value(0).as(:depth)] }
+# SELECT "nodes"."id", 0 AS depth FROM "nodes"
+
+Node.select { [:id, 0.as(:depth)] }         # the same thing
+
+Post.select { [:title, "draft".as(:state)] }
+# SELECT "posts"."title", 'draft' AS state FROM "posts"
+```
+
+What the shorthand does not cover, `value` still spells: `value(true)`,
+`value(nil)`, or a literal that goes on to be compared rather than selected.
+
+`CASE` is grammar rather than a function, and has two shapes. With an operand, each `when` is
+something to compare it against; without one, each `when` carries a condition
+of its own. `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:
+
+```ruby
+Author.select { :country.when("JP").then("Japan").else("elsewhere").as(:where) }
+# CASE "country" WHEN 'JP' THEN 'Japan' ELSE 'elsewhere' END AS where
+
+Author.select { case_when { :age >= 60 }.then("senior").else("adult").as(:band) }
+# CASE WHEN "age" >= 60 THEN 'senior' ELSE 'adult' END AS band
+
+Author.select { self.case(mod(:age, 10)).when(0).then("round").else("not").as(:v) }
+```
+
+A `when` takes a value or a block, and so do `then` and `else`; the block is
+there to read like the blocks around it, since an argument works just as well
+— `:age >= 60` has already become an expression by the time it is passed.
+Leaving the `else` off is SQL's own default, which is NULL. `when` and `then`
+come in pairs, and one without the other is an `ArgumentError` rather than
+something that reaches the database:
+
+```ruby
+Author.select {
+  case_when { :age < 18 }.then("minor").
+    when { :age >= 60 }.then("senior").
+    else("adult").as(:band)
+}
+
+Author.select { sum(case_when { :age >= 60 }.then(1).else(0)).as(:seniors) }
+# SUM(CASE WHEN "age" >= 60 THEN 1 ELSE 0 END) AS seniors
+```

data/docs/functions.md

@@ -0,0 +1,219 @@
+# Aggregates and functions
+
+
+`count`, `sum`, `avg`, `min` and `max` are available as methods, as are the
+bit aggregates and the scalar functions below, with `fn` for anything else. Return an array to select
+or order by multiple expressions.
+
+`filter` takes the aggregate over the rows a condition holds for, as a value
+or a block:
+
+```ruby
+Author.select { count(:*).filter { :age < 50 }.as(:young) }
+# COUNT(*) FILTER (WHERE "age" < 50) AS "young"
+
+Author.select {
+  [count(:*).as(:all), sum(:age).filter { :country == "JP" }.as(:jp_years)]
+}
+```
+
+MySQL has no `FILTER` clause, and gets the case that means the same thing —
+`COUNT(CASE WHEN "age" < 50 THEN 1 END)`. An aggregate passes over a NULL, so
+a row the condition misses is a row it does not see, and the number that comes
+back is the same on all three.
+
+Pass `:*` to `count` for `COUNT(*)`, and `distinct: true` for
+`COUNT(DISTINCT ...)`. `sum` and `avg` take `distinct: true` as well, for the
+aggregate over each value once; `min` and `max` would give the same with or
+without it, so they take no such thing:
+
+```ruby
+Author.group { :country }.having { count(:*) > 1 }
+# SELECT "authors".* FROM "authors" GROUP BY "authors"."country" HAVING COUNT(*) > 1
+
+Post.select { count(:author_id, distinct: true) }   # COUNT(DISTINCT "author_id")
+Post.select { sum(:likes, distinct: true) }         # SUM(DISTINCT "likes")
+```
+
+`string_agg` joins the strings of a group into one, a separator between —
+`,` unless another is given — and `.order` says the order they are joined
+in. Each database has it under a name of its own, with the `ORDER BY` in a
+place of its own:
+
+```ruby
+Post.group { :author_id }.select { string_agg(:title, ", ").order(:title).as(:titles) }
+# STRING_AGG("title", ', ' ORDER BY "title")                  PostgreSQL
+# group_concat("title", ', ' ORDER BY "title")                SQLite
+# GROUP_CONCAT("title" ORDER BY "title" SEPARATOR ', ')       MySQL
+# STRING_AGG("title", ', ') WITHIN GROUP (ORDER BY "title")   SQL Server
+# LISTAGG("title", ', ') WITHIN GROUP (ORDER BY "title")      Oracle
+```
+
+`filter` and `over` come along as with any aggregate, `over` where the
+database takes it — the MySQL family and SQL Server do not, and raise.
+Oracle's insists on an order and is given the values' own when none is asked
+for. What is joined is text: PostgreSQL's `STRING_AGG` takes nothing else, so
+a column the model does not declare a string is cast there, where the others
+convert for themselves. MySQL cuts the result at `group_concat_max_len`, 1024
+bytes unless the session says otherwise, and the `ORDER BY` inside SQLite's
+call needs SQLite 3.44.
+
+The scalar functions are real methods rather than anything caught dynamically,
+so a misspelling is a `NoMethodError` where you wrote it, and a name Ruby also
+answers to — `rand` — means the SQL one inside a block:
+
+```
+abs  acos  asin  atan  atan2  bit_and  bit_count  bit_or  bit_xor  cast
+ceil  char_length  coalesce  concat
+cos  current_date  current_time  current_timestamp  date_trunc  degrees
+exp  extract  floor  format  greatest  least  length  ln  localtime
+localtimestamp  log  log10  log2  lower  ltrim  mod  now  nullif  pi
+power  radians  rand  replace  round  rtrim  sign  sin  sqrt  substr  tan
+trim  trunc  upper
+```
+
+Most are spelled the same everywhere. Where they are not, the method names one
+meaning and each adapter gets its own spelling: `char_length`, `greatest` and
+`least` become `LENGTH`, `MAX` and `MIN` on SQLite, and `rand` is `RAND` on
+MySQL and `RANDOM` elsewhere, and `trunc` is `TRUNCATE` on MySQL, which
+insists on the second argument the others default to zero — SQLite's takes
+only the one. Where an adapter has no equivalent — `date_trunc` outside
+PostgreSQL, `now` and the `local*` pair on SQLite, `log2` on PostgreSQL,
+whose spelling is `log(2, x)`, the four `bit_*` on SQLite — the block raises
+`NotImplementedError` rather than leaving the database to reject the SQL.
+
+`format` is printf formatting, and raises on MySQL, where a function of the
+same name does something else entirely: it puts separators in a number, and
+reads a printf template as the number zero rather than complaining. `fn` still
+reaches it, spelled as the different thing it is:
+
+```ruby
+Post.select { fn(:format, :amount, 2) }   # MySQL's, on purpose
+```
+
+`fn` reaches functions without a method of their own. Its name is emitted as
+written, so a case-sensitive one can be spelled exactly:
+
+```ruby
+Post.select { fn(:date_trunc, "day", :created_at).as(:day) }
+# SELECT date_trunc('day', "posts"."created_at") AS day
+```
+
+`op` is the same escape hatch for operators — PostgreSQL alone has dozens
+with no method here, `<@` and `&&` and the geometric ones among them. The
+operator is emitted as written and, like `fn`'s names, whether the adapter
+has it is your assertion; it is checked against the characters PostgreSQL
+allows an operator, so a letter, a space or a quote is refused rather than
+written into the SQL. Both sides take what `fn`'s arguments take — a
+column, an expression, a value quoted by the adapter — and a value is
+spelled in the adapter's own syntax, `to_json` saying a document, `'{a,b}'`
+an array; a Ruby Hash or Array is refused rather than guessed at. The
+result is parenthesized, its precedence being unknown, and so is an
+expression on either side, so a dug value cannot be re-grouped out from
+under it:
+
+```ruby
+Post.where { op("&&", :tags, "{ruby,sql}") }
+# WHERE ("posts"."tags" && '{ruby,sql}')
+
+Post.where { op("<@", :meta.dig(:author), { name: "alice" }.to_json) }
+# WHERE (("meta" #> '{author}') <@ '{"name":"alice"}')
+```
+
+`sql` is the last resort, for what neither `fn` nor `op` can spell: the
+statement goes out as written. It is the one way a string means SQL inside a
+block — everywhere else a string is a value — so writing SQL is always asked
+for by name, and an interpolation has a spelling that is not it: `?` and
+`:name` placeholders take values quoted by the adapter, through
+`sanitize_sql_array`. A `?` is rewritten only when there are positional binds
+to put in it, so PostgreSQL's `?` operators can share a statement with named
+binds, or with none. The result carries the predications and arithmetic, and
+is parenthesized where it stands inside a larger expression — its precedence
+is whatever was written — but comes out bare at the top of a select list,
+where parentheses would refuse an alias written into the string:
+
+```ruby
+Post.where { sql("length(title) > ?", 10) }
+# WHERE (length(title) > 10)
+
+Post.where { sql("score + ?", 10) * 2 >= 60 }
+# WHERE (score + 10) * 2 >= 60
+
+Post.select { sql("count(*) FILTER (WHERE score > 0) AS positive") }
+```
+
+Values are quoted by the adapter wherever they appear, as they are in
+Active Record, and so is a column alias. That is what makes the name asked for
+the name that comes back: unquoted, PostgreSQL folds a capital away where the
+other two keep it, so one block would mean two things. It also leaves nothing
+to refuse — a name that would have been SQL becomes an identifier with a
+strange name instead:
+
+```ruby
+Author.select { count(:*).as(:postCount) }       # AS "postCount" everywhere
+Author.select { count(:*).as(:'total sales') }   # AS "total sales"
+```
+
+`quote: false` asks for the name as written, for a schema that wants the
+folding. Nothing quotes it then, so a name that is not plain is refused:
+
+```ruby
+Author.select { count(:*).as(:post_count, quote: false) }   # AS post_count
+Author.select { count(:*).as(:'total sales', quote: false) }  # ArgumentError
+```
+
+`fn`'s function name is the one that cannot be quoted: quoting stops
+PostgreSQL folding it, and `"UPPER"(x)` is a function that does not exist.
+That one, `cast`'s type and `extract`'s field are neither values nor
+identifiers, so they have to be plain names and anything else raises
+`ArgumentError` rather than reaching the query.
+
+`current_date`, `current_time`, `current_timestamp`, `localtime` and
+`localtimestamp` come out without parentheses, as the grammar has them —
+written as calls, PostgreSQL and SQLite would reject them. What does go into
+parentheses is an optional precision — `current_timestamp(3)` — which
+`current_date` never takes and SQLite never accepts. `current_timestamp` is
+the portable spelling of what `now` means, and reaches SQLite where `now`
+does not — and SQL Server, which has none of the other four:
+
+```ruby
+Post.where { :published_at <= current_timestamp }
+# SELECT "posts".* FROM "posts" WHERE "posts"."published_at" <= CURRENT_TIMESTAMP
+```
+
+`extract` and `cast` are grammar as well: the field and the type go where no
+value could. The field has to be a plain name, and the type has to look like
+a type — a plain name, at most parenthesized with lengths, so the adapters'
+own spellings like `double precision` or `decimal(10,2)` pass; anything else
+raises `ArgumentError`. The type is the adapter's own name for the type, and
+whether it exists is the database's to say. SQLite spells everything
+`extract` does as `strftime` formats, which no renaming carries, so `extract`
+raises there:
+
+```ruby
+Post.where { extract(:year, :created_at) == 2026 }
+# SELECT "posts".* FROM "posts" WHERE EXTRACT(YEAR FROM "posts"."created_at") = 2026
+
+Post.select { cast(:price, "decimal(10,2)").as(:price) }
+# SELECT CAST("posts"."price" AS decimal(10,2)) AS price
+```
+
+A duration moves a date. Active Support's `7.days` and the rest go on the
+right of `+` or `-`, and the move comes out the way the adapter spells it — an
+`INTERVAL` literal on PostgreSQL and MySQL, `DATEADD` on SQL Server,
+`datetime(x, '-7 day')` on SQLite:
+
+```ruby
+Post.where { :created_at > current_timestamp - 7.days }
+# WHERE "posts"."created_at" > (CURRENT_TIMESTAMP - INTERVAL '7' DAY)
+
+Post.select { (:published_on + 1.month).as(:review_on) }
+```
+
+A duration of several parts, `1.month + 2.days`, is applied a part at a time
+in the order Active Support keeps them, and a week is seven days, which is
+what SQLite and Oracle have of one. Each part has to be a whole number, since
+it is written into the SQL as one: `1.5.days` raises `ArgumentError`. SQLite
+has no date type, so there a column the model declares a date is moved by
+`date()` and stays a date; everything else goes through `datetime()` and comes
+back with a time of day.