activerecord-refined 0.8.1 → 0.10.0

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.

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.