activerecord-refined 0.6.1 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: affe44abbced76ea15b8c057f44292e5aefb0c8be7bc0012805278b08be7881c
-  data.tar.gz: 54b11073068080d169b005a4f2fdee825a8b03e0910459c5fef5555e24430edd
+  metadata.gz: aaf1859c70b9ca6e5c245343e664fffbd483d395266a4d442eaa0d5c4107595c
+  data.tar.gz: da1ddb190628a8a11ced1d105d0a73bf164892cf9e78dfd68db7fdf135047d95
 SHA512:
-  metadata.gz: 13103ed15da63fadedf60ec4f5f91ee0ba4c22440250aa9c7f48c9df2ccb0b72194225592ddf1dbca449d898fb33f5051fa30f906add9e533917c271b3b6283f
-  data.tar.gz: 97c9c10eeb67c3dbbbdd7e896e13eb4c49be50dd2312d92ee4289ab8a9c96d5159c06ea940f19a9871f33e877f71de8eb96c7d2d43399eb9097fd19505d4d35f
+  metadata.gz: 5b075b93194651859a7411d2465fec0c2d0a504eaf9da7d4d296ddea1cc91a366af68fea0b37cbea230e44da9e4bf480ecfd047571c1b49601b9bfa7c3dc2780
+  data.tar.gz: c35194020d37a97de9f5816b965f391a47c5e3d12ef7192bfd2c91ff16ea72689e122fc29daba3c6096aceac22dd7fbb535d562fe0c0ba2f3edbcbbb9904c22c

data/.github/workflows/sandbox.yml

@@ -128,7 +128,7 @@ jobs:
         run: ./bin/prepare-rb
 
       # Runs every example through the same WASI shim the page uses.  The
-      # larger stack is needed to compile ActiveRecord's relation.rb; see the
+      # larger stack is needed to compile Active Record's relation.rb; see the
       # note in sandbox/README.md.
       - name: Check the examples
         run: node --stack-size=4000 check-examples.mjs

data/README.md

@@ -3,7 +3,7 @@
 [![gem](https://img.shields.io/gem/v/activerecord-refined.svg)](https://rubygems.org/gems/activerecord-refined)
 [![test](https://github.com/shugo/activerecord-refined/actions/workflows/test.yml/badge.svg)](https://github.com/shugo/activerecord-refined/actions/workflows/test.yml)
 
-Adding clean and powerful query syntax on ActiveRecord using refinements.
+Adding clean and powerful query syntax on Active Record using refinements.
 
 ```ruby
 Author.
@@ -15,7 +15,7 @@ Author.
 ```
 
 **[Try it in your browser](https://shugo.github.io/activerecord-refined/)** —
-Ruby 4.1, ActiveRecord, SQLite and PostgreSQL run in the page, so the examples
+Ruby 4.1, Active Record, SQLite and PostgreSQL run in the page, so the examples
 build real SQL and return real rows without a `ruby-master` build of your own.
 
 ## History
@@ -43,7 +43,7 @@ works again without monkey-patching `Symbol` globally.
 ## Requirements
 
 * Ruby 4.1 or later (for `Proc#refined`; not released yet, so a `ruby-master` build is needed for now)
-* ActiveRecord 7.0 or later
+* Active Record 7.0 or later
 
 The [sandbox](https://shugo.github.io/activerecord-refined/) is there to skip
 that build: it carries its own Ruby 4.1. `sandbox/` in this repository is what
@@ -123,7 +123,7 @@ answers false there. `not_true?` is therefore "false or never set" and
 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 ActiveRecord's own
+subquery selects the relation's primary key, the same way Active Record's own
 `where(id: relation)` does:
 
 ```ruby
@@ -245,7 +245,7 @@ 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 ActiveRecord's own `where(period: from...to)` does for those column types:
+way Active Record's own `where(period: from...to)` does for those column types:
 
 ```ruby
 Reservation.where { :period == (from...to) }   # daterange = '[from,to)'
@@ -294,6 +294,27 @@ Employee.joins(:employees, as: :managers) { :managers[:id] == :employees[:manage
 #   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"
+```
+
 ### Keeping one row per group
 
 `distinct_on` is PostgreSQL's `DISTINCT ON`: the first row of each group the
@@ -318,7 +339,7 @@ Post.from(ranked, :posts).where { :rn == 1 }
 ```
 
 The subquery is named after the model's own table for the reason `from_cte`
-is: ActiveRecord goes on qualifying columns with that name, so `where` needs
+is: Active Record goes on qualifying columns with that name, so `where` needs
 to find it.
 
 ### Grouping several ways at once
@@ -345,16 +366,17 @@ the block raises `NotImplementedError` on both.
 
 ### Lateral joins
 
-`lateral: true` joins a relation rather than a table, and lets it see the row
-being joined to. That is what makes the top row of each group reachable in one
-query:
+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, as: :top, lateral: true).
+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"
@@ -372,7 +394,7 @@ writes it, so the SQL is written here instead.
 
 ### Common table expressions
 
-ActiveRecord's `with` and `with_recursive` need nothing from this gem: a CTE
+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.
 
@@ -403,8 +425,8 @@ the shape of a tree comes out of a flat table. The `0` is a value rather than
 SQL — see [`value`](#aggregates-functions-and-aliases) below for why a number
 can say `.as` directly.
 
-The alias on the last line is there for ActiveRecord's sake, not SQL's:
-written by hand that line would be `SELECT * FROM tree`. ActiveRecord goes on qualifying
+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:
 
@@ -511,7 +533,7 @@ Post.select { fn(:date_trunc, 'day', :created_at).as(:day) }
 ```
 
 Values are quoted by the adapter wherever they appear, as they are in
-ActiveRecord, and so is a column alias. That is what makes the name asked for
+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
@@ -626,7 +648,7 @@ 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 ActiveRecord reads a string in `select` as SQL,
+`concat(:name, '-x')` — but Active Record reads a string in `select` as SQL,
 so `value` is how you ask for the other meaning. It carries the predications
 and arithmetic with it, so a literal can be compared and combined like
 anything else. Numbers have a shorthand, since nothing else could be meant by
@@ -684,11 +706,14 @@ Author.select { sum(case_when { :age >= 60 }.then(1).else(0)).as(:seniors) }
 ### 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:
+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(:author, :name) == 'alice' }
-Post.select { :meta.dig(:tags, 0).as(:first_tag) }
+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') }
 ```
@@ -698,25 +723,41 @@ three:
 
 | | PostgreSQL | SQLite | MySQL |
 | --- | --- | --- | --- |
-| `dig(:a, :b)` | `#>> '{a,b}'` | `->> '$.a.b'` | `JSON_UNQUOTE(JSON_EXTRACT(…, '$.a.b'))` |
-| `dig_json(:a)` | `#> '{a}'` | `-> '$.a'` | `JSON_EXTRACT(…, '$.a')` |
+| `dig(:a)` | `#> '{a}'` | `-> '$.a'` | `JSON_EXTRACT(…, '$.a')` |
+| `dig_text(:a, :b)` | `#>> '{a,b}'` | `->> '$.a.b'` | `JSON_UNQUOTE(JSON_EXTRACT(…, '$.a.b'))` |
 | `key?(:a)` | `jsonb_exists(…, '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` 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:
+`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(:n) == '5' }
-Post.where { cast(:meta.dig(:n), 'integer') > 6 }   # 'signed' on MySQL
+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 a dug 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. `dig` is refused the other way
+about — the JSON for a string carries its quotes, so `dig(:name) == 'alice'`
+is false, an error and true — and `dig_text` is the one that gives the value.
+A column, a function or another dug value on the right goes through untouched;
+only a Ruby literal is refused.
+
 `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:
@@ -727,7 +768,7 @@ Post.update_all { { meta: :meta.bury(: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)) } }
+Post.update_all { { meta: :meta.bury(:copy, :meta.dig_text(:n)) } }
 ```
 
 A whole document goes in as one — an object or an array rather than the string
@@ -736,8 +777,46 @@ 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`.
 
-`dig_json` keeps the JSON, for a document to be dug into further or compared
-whole. `contains?` has no equivalent on SQLite and raises `NotImplementedError`
+`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.
+
+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, `contains?` and `key?` want a `jsonb` column; the
 `json` type carries neither operator.
@@ -783,7 +862,7 @@ Post.select { sum(:likes).over.order(:created_at).rows(0..).as(:remaining) }
 ```
 
 `range` says `RANGE` where `rows` says `ROWS`, and a window has one frame or
-none. Named windows — `WINDOW w AS (...)` — have no clause in ActiveRecord to
+none. Named windows — `WINDOW w AS (...)` — have no clause in Active Record to
 live in, so they are not here.
 
 ### Aliases and ordering
@@ -817,7 +896,7 @@ Author.
 
 ### Writing
 
-`update_all` reads its hash the way ActiveRecord does — `update_all(likes: :likes)`
+`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:
@@ -839,23 +918,23 @@ Tally.upsert_all(rows, unique_by: :page) { { hits: :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.
-ActiveRecord's own `on_duplicate:` takes SQL text and nothing else, so this is
+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.
-ActiveRecord type-casts each one on the way into the `VALUES` list, so an
+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.
 
 ## Performance
 
 `benchmark/query_building.rb` compares building the same queries through the
-block DSL and through ActiveRecord's other argument styles. Only query
+block DSL and through Active Record's other argument styles. Only query
 construction (through `to_sql`) is measured — every style produces the same
 SQL, so execution costs the same regardless.
 
-Queries built per second (ruby 4.1.0dev, ActiveRecord 8.1.3, one machine —
+Queries built per second (ruby 4.1.0dev, Active Record 8.1.3, one machine —
 treat the ratios, not the absolute numbers, as the result):
 
 | query | string | arel | block (this gem) | hash | relation and/or |
@@ -930,7 +1009,7 @@ and publishes it through RubyGems.org's trusted publishing, so no API key is
 stored anywhere.
 
 ```sh
-bump patch --tag # or bump {major,minor} etc.
+bundle exec bump patch --tag # or bump {major,minor} etc.
 git push --follow-tags
 ```
 

data/activerecord-refined.gemspec

@@ -8,8 +8,8 @@ Gem::Specification.new do |gem|
   gem.version       = Activerecord::Refined::VERSION
   gem.authors       = ["Shugo Maeda"]
   gem.email         = ["shugo@ruby-lang.org"]
-  gem.description   = 'Adding clean and powerful query syntax on AR using refinements'
-  gem.summary       = 'ActiveRecord + Ruby 4.1 Proc#refined'
+  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'
 
   # sandbox/ is a site, not part of the library: its Gemfile.lock and
@@ -28,4 +28,6 @@ Gem::Specification.new do |gem|
   gem.add_development_dependency 'sqlite3', ['>= 0']
   gem.add_development_dependency 'minitest', ['>= 0']
   gem.add_development_dependency 'rake', ['>= 0']
+  # What cuts a release: `bump patch --tag`, then push with --follow-tags.
+  gem.add_development_dependency 'bump', ['>= 0']
 end

data/benchmark/query_building.rb

@@ -1,5 +1,5 @@
 # Compares the cost of building the same queries through this gem's block
-# DSL and through ActiveRecord's other argument styles: hash conditions,
+# DSL and through Active Record's other argument styles: hash conditions,
 # string conditions, raw Arel, and relation and/or chains.  Only query
 # construction (through to_sql) is measured; every style produces the same
 # SQL, which the script prints first as a sanity check.

data/examples/complex_joins.rb

@@ -80,3 +80,33 @@ query4 =
 puts "--- 4. Self join through an alias ---"
 puts query4.to_sql
 puts
+
+# 5. The joins Active Record has no method for.  RIGHT OUTER keeps the rows of
+#    the table joined rather than the one selected from; FULL OUTER keeps
+#    both, which MySQL has no spelling for and this gem refuses there.
+query5 =
+  Author.
+    right_outer_joins(:posts) { :posts[:author_id] == :authors[:id] }.
+    select { [:authors[:name].as(:author), :posts[:title].as(:post)] }
+
+puts "--- 5. RIGHT OUTER JOIN ---"
+puts query5.to_sql
+puts
+
+# An association is what joins and left_outer_joins read out; these two want
+# the block that says how to join.
+begin
+  Author.right_outer_joins(:posts)
+rescue ArgumentError => e
+  puts '--- and it says so without one ---'
+  puts "  #{e.message}"
+  puts
+end
+
+# 6. CROSS JOIN: every row against every row, so there is no condition to
+#    give and no block to write it in.  `as` still names the table.
+puts '--- 6. CROSS JOIN ---'
+puts Author.cross_joins(:posts).to_sql
+puts Author.cross_joins(:authors, as: :others).
+  select { [:authors[:name].as(:a), :others[:name].as(:b)] }.to_sql
+puts

data/examples/ctes.rb

@@ -34,8 +34,8 @@ Product.create!(name: 'apple', category_id: groceries.id, price: 2)
 #    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
+#    That alias is Active Record's requirement rather than SQL's: by hand the
+#    last line would be `SELECT * FROM tree`.  Active Record 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.

data/examples/json.rb

@@ -30,29 +30,45 @@ def show(title, relation, 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)] }.
+# 1. Reading.  dig_text 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_text reads a value out of the document',
+  Document.select { [:name, :meta.dig_text(:author, :name).as(:author)] },
+  Document.select { [:name, :meta.dig_text(: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)] }.
+  Document.select { [:name, :meta.dig_text(:tags, 0).as(:first_tag)] },
+  Document.select { [:name, :meta.dig_text(: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)] }.
+show('dig_text in a condition',
+  Document.where { :meta.dig_text(:author, :country) == 'JP' },
+  Document.where { :meta.dig_text(:author, :country) == 'JP' }.pluck(:name))
+
+# A dug value is text, so a number goes through a cast.  Comparing it with
+# one instead is refused rather than left to the adapters, which answer that
+# three ways: true here, an error on PostgreSQL, true on MySQL.
+show('a number wants a cast',
+  Document.where { cast(:meta.dig_text(:views), 'integer') > 100 },
+  Document.where { cast(:meta.dig_text(:views), 'integer') > 100 }.pluck(:name))
+
+begin
+  Document.where { :meta.dig_text(:views) > 100 }
+rescue ArgumentError => e
+  puts '--- and without one it says so ---'
+  puts "  #{e.message}"
+  puts
+end
+
+# dig keeps the JSON, for a part of the document to be dug into further
+# or asked the JSON questions.  The quotes around the string are the sign of
+# it -- and the reason a Ruby value is refused on this side too.
+show('dig keeps the JSON',
+  Document.select { [:name, :meta.dig(:author).as(:author)] },
+  Document.select { [:name, :meta.dig(: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
@@ -92,3 +108,15 @@ rescue ArgumentError => e
   puts "  #{e.message}"
   puts
 end
+
+# 4. Taking keys out again, as Hash#except does: keys of the document rather
+#    than a path, however many of them, and a key that is not there is no
+#    error.  The document comes back changed, so it chains with bury.
+show('the expression except builds',
+  Document.select { [:name, :meta.except(:views, :draft).as(:trimmed)] })
+
+Document.where { :name == 'guide' }.
+  update_all { {meta: :meta.bury(:author, :country, 'JP').except(:tags, :views)} }
+puts '--- buried and excepted in one statement ---'
+puts "  #{Document.find_by(name: 'guide').meta.inspect}"
+puts

data/examples/postgresql.rb

@@ -153,7 +153,7 @@ show('rollup is the nested case of the same thing',
 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).
+lateral = Writer.left_outer_joins(top.lateral, as: :top).
   select { [:name, :top[:title].as(:top_article)] }
 show('the top article beside each writer',
   lateral,

data/examples/subqueries.rb

@@ -41,7 +41,7 @@ end
 
 # 1. in? takes a relation as a subquery.  With an explicit select list the
 #    subquery selects that column; without one it selects the primary key,
-#    the same way ActiveRecord's own where(id: relation) does.
+#    the same way Active Record's own where(id: relation) does.
 show('in? with a subquery',
   Author.where { :id.in?(Post.published.select(:author_id)) })
 

data/examples/windows.rb

@@ -88,7 +88,7 @@ end
 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
+# The subquery is named after the model's own table because Active Record 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 },

data/examples/writes.rb

@@ -27,7 +27,7 @@ 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.
+# the SQL is taken from the notification Active Record sends for each one.
 def write(title)
   statements = []
   subscriber = ActiveSupport::Notifications.subscribe('sql.active_record') do |*, payload|
@@ -41,7 +41,7 @@ def write(title)
   puts
 end
 
-# 1. update_all.  ActiveRecord reads its hash as literals -- update_all(hits:
+# 1. update_all.  Active Record 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.
@@ -70,14 +70,14 @@ 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
+# Without a block, upsert_all overwrites -- that is Active Record'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
+# insert_all has no block: Active Record 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'}])