lowdata 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4c2e8629cffb84f30179cf393797a47d5cb05f7f03091a2b2cc122d8053593a4
-  data.tar.gz: 1468121aa2d7c393a167f890ad009da216191ed2da0d83371ce33e05f3cc4100
+  metadata.gz: 5902c4edccd0a49aec0a211a75c7dd3cbc277721155989ff0d4b9abbd84bb153
+  data.tar.gz: cdb2e97726f61229d527d099c62f550e6d35f7dd984359d5a8bc6e62c0826b8d
 SHA512:
-  metadata.gz: fabdfb8df5462fd1274a435bcc4a1230f58cafb17f0ebc6ec03a4652b81b86f61ef877d4237c121510325d0a72280a3de0afcf81490aea61facd1dc6336786c9
-  data.tar.gz: 9311a3e886512bf5eb297690db47fb78ff5f81c9d9c267ab1a5b9a289de94cc784909a4b8bf6104ab6841b56cd9c2e4be8f3a13f2bc14f296448389d3f03cc07
+  metadata.gz: 46deb79a98865325e79647f77a0f20a853146dfbcf6cede25a9e77433f8dc291f2ae09fe6d2d63d827b2a0e3e5f1c850d19c040f63cfad0b94b1c4515e93052b
+  data.tar.gz: 87560d6313de8eca179b1ac1e6526258ca1fd0d4dc64b1fe24a1c5adb99fbc408bad0e876b9f381001f7d8079f045c5bed9cb1c4adef2ba365cbd6edcc961a2e

data/config/rubocop.yml

@@ -0,0 +1,14 @@
+# Inherit in an app that writes with LowData, so RuboCop's autocorrect can't change or remove a write:
+#
+#   inherit_gem:
+#     lowdata: config/rubocop.yml
+#
+# See ADR 0007.
+
+# `Posts(slug: 'hello') <= row` on its own line looks unused, and `rubocop -A` deletes the `<= row`, removing the upsert.
+Lint/Void:
+  Enabled: false
+
+# `Tags <= row` looks like a comparison with the constant first, and `rubocop -A` reverses it to `row >= Tags`.
+Style/YodaCondition:
+  Enabled: false

data/lib/data_expression.rb

@@ -14,27 +14,45 @@ class LowData
   #   (Posts[:title] / 20)[2]            # LIMIT 20 OFFSET 40
   class DataExpression < ::Expressions::Expression
     # The filters in a table's round brackets: `Posts(published: true) { views > 100 }`. See FilterCompiler.
-    Filter = ::Data.define(:values, :conditions, :related) do
-      def initialize(values: {}, conditions: [], related: [])
+    # `foreign_keys` aren't filters: they name the foreign key a nested join links by, `Posts(:user_id)`. See NestedJoin.
+    Filter = ::Data.define(:values, :conditions, :related, :foreign_keys) do
+      def initialize(values: {}, conditions: [], related: [], foreign_keys: [])
         super
       end
 
       def merge(other)
-        with(values: values.merge(other.values), conditions: conditions + other.conditions, related: related + other.related)
+        with(values: values.merge(other.values), conditions: conditions + other.conditions, related: related + other.related,
+             foreign_keys: foreign_keys + other.foreign_keys)
       end
     end
     # A table in another table's round brackets, keeping rows with `count` related rows: `Users(Posts => 3..)`.
     Related = ::Data.define(:key, :source, :count)
-    # A table with the columns to select, the tables nested in its brackets and the filter on its rows.
-    Source = ::Data.define(:table, :columns, :nested, :filter) do
-      def initialize(table:, columns:, nested: [], filter: Filter.new)
+    # A table with the columns to select, the columns renamed (`headline: :title`), the tables nested in its brackets and
+    # the filter on its rows.
+    Source = ::Data.define(:table, :columns, :renames, :nested, :filter) do
+      def initialize(table:, columns:, renames: {}, nested: [], filter: Filter.new)
         super
       end
     end
+
+    class Source
+      # No columns or renames selects every column.
+      def every_column? = columns.empty? && renames.empty?
+
+      # The keys of each row, as asked for.
+      def names = columns + renames.keys
+
+      # The renamed columns, as `posts.title AS headline`.
+      def aliases = renames.map { |name, column| Sequel[table][column].as(name) }
+    end
     # A table nested in another table's brackets, under an optional key: `Reviews[:rating, author: Users[:username]]`.
     Nested = ::Data.define(:key, :node)
-    Join = ::Data.define(:type, :left, :right)
-    Inversion = ::Data.define(:table, :columns, :filter)
+    Join = ::Data.define(:type, :left, :right) do
+      def nest? = type == :nest
+    end
+    # Tables nested side by side in the table before them: `Posts[:title] + [Comments[:body], Likes[]]`.
+    Siblings = ::Data.define(:nodes)
+    Inversion = ::Data.define(:table, :columns, :renames, :filter)
     # A node sorted by `keys` (Col::Key) with `rows` (Rows) kept: `Posts[:title] ^ -Col[:views] * 10`.
     Ordered = ::Data.define(:node, :keys, :rows)
 
@@ -47,15 +65,18 @@ class LowData
     end
 
     SORT_MESSAGE = 'Sort by columns with Col[], e.g. Posts[:title] ^ Col[:views], not %<value>s'
-    NESTED_SQL_MESSAGE = '+ loads nested data with one query per table, so it has no single SQL query. Call to_a instead'
-
+    NESTED_DATASET_MESSAGE = 'Nested tables load with one query per table, so they have no single dataset. Call sql to see ' \
+                             'each query, or to_a to load them'
     def dataset(database: LowData.database)
-      raise Error, NESTED_SQL_MESSAGE if nested?
+      raise Error, NESTED_DATASET_MESSAGE if nested?
 
       QueryCompiler.new(database:).compile(node: @node)
     end
 
+    # Nested tables load with one query per table, so their SQL is each query, separated by semicolons.
     def sql(database: LowData.database)
+      return Nesting.new(database:).sql(node: @node).join(";\n") if nested?
+
       dataset(database:).sql
     end
 
@@ -78,7 +99,7 @@ class LowData
 
     def nested?
       node = @node.is_a?(Ordered) ? @node.node : @node
-      (node.is_a?(Join) && node.type == :nest) || (node.is_a?(Source) && node.nested.any?)
+      (node.is_a?(Join) && node.nest?) || (node.is_a?(Source) && node.nested.any?)
     end
 
     # Sorting again adds sort keys after the existing ones, and an expression keeps one limit, range or page size.
@@ -87,6 +108,14 @@ class LowData
       @node = ordered.with(keys: ordered.keys + keys, rows: Rows.merge(ordered.rows, rows))
     end
 
+    def add_siblings(expressions)
+      invalid = expressions.reject { |expression| expression.is_a?(DataExpression) }
+      raise ArgumentError, "Nest data expressions such as Comments[:body], not #{invalid.map(&:inspect).join(', ')}" if invalid.any?
+      raise ArgumentError, 'Nest at least one table, e.g. Posts[:title] + [Comments[:body], Likes[]]' if expressions.empty?
+
+      @node = Join.new(type: :nest, left: @node, right: Siblings.new(nodes: expressions.map(&:node)))
+    end
+
     def xor_value(value)
       raise ArgumentError, format(SORT_MESSAGE, value: value.inspect) unless value.is_a?(Col)
 
@@ -125,6 +154,8 @@ class LowData
       end
 
       define_method(:"#{prefix}_value") do |value|
+        return add_siblings(value) if prefix == :add && value.is_a?(Array)
+
         raise ArgumentError, "Join a data expression such as Posts[:title], not the value #{value.inspect}"
       end
 

data/lib/expression_writes.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+class LowData
+  class DataExpression < ::Expressions::Expression
+    # Writes through a table in square brackets, which choose the columns returned. See Writer:
+    #   Posts[:id, :created_at] << { title: 'Hello' }      # Inserts, returning the new row's id and created_at.
+    #   Posts(slug: 'hello')[:id] <= { title: 'Hello' }    # Upserts, returning the row's id.
+    module Writes
+      # It runs straight away and returns the rows, so it overrides the expressions gem's `<=`, which builds a copy.
+      def <=(rows)
+        Writer.new(database: LowData.database).upsert(source: write_source(operator: '<='), rows:)
+      end
+
+      def delete
+        raise ArgumentError, 'Square brackets choose columns, and a delete removes whole rows. Delete from the table, e.g. ' \
+                             'Posts(id: 1).delete'
+      end
+
+      private
+
+      # Writes go to one table.
+      def write_source(operator:)
+        return @node if @node.is_a?(Source) && @node.nested.empty?
+
+        raise ArgumentError, "#{operator} writes to one table, e.g. Posts[:id] #{operator} { title: 'Hello' }, not to joined, " \
+                             'nested or sorted tables'
+      end
+
+      # The expressions gem's `<<` calls this on the expression itself and returns what it returns, the inserted rows.
+      def append_value(rows)
+        Writer.new(database: LowData.database).insert(source: write_source(operator: '<<'), rows:)
+      end
+
+      def append_expression(_expression)
+        raise ArgumentError, WriteChecks::EXPRESSION_MESSAGES.fetch('<<')
+      end
+
+      def append_type(type_)
+        raise ArgumentError, "<< inserts rows, e.g. Posts << { title: 'Hello' }, not the type #{type_}"
+      end
+    end
+
+    include Writes
+  end
+end

data/lib/filter_compiler.rb

@@ -9,15 +9,27 @@ class LowData
   class FilterCompiler
     def initialize(database:, schema:)
       @database = database
+      @schema = schema
       @links = NestingTree.new(schema:)
     end
 
     def apply(dataset:, source:)
+      check_foreign_keys!(source:)
       conditions(source:).reduce(dataset) { |filtered, condition| filtered.where(condition) }
     end
 
     private
 
+    # A symbol in round brackets names a foreign key for NestedJoin, so it must be one of the table's.
+    def check_foreign_keys!(source:)
+      foreign_keys = @schema.foreign_keys(table: source.table).flat_map { |foreign_key| foreign_key[:columns] }
+      invalid = (source.filter.foreign_keys - foreign_keys).first
+      return unless invalid
+
+      raise ArgumentError, "#{source.table} has no #{invalid} foreign key. A symbol in round brackets names the foreign key " \
+                           'a nested join links by, e.g. Posts(:user_id). Filters are keywords, e.g. Posts(published: true)'
+    end
+
     def conditions(source:)
       table = source.table
       filter = source.filter

data/lib/inversion.rb

@@ -7,30 +7,61 @@ class LowData
       @schema = schema
     end
 
-    # Returns the join tree and the columns to select, in the order they were asked for.
+    # Returns the join tree and the columns to select, in the order they were asked for, then the renamed columns.
     def resolve(node:)
-      owners = node.columns.to_h { |column| [column, owner(table: node.table, column:)] }
-      base = DataExpression::Source.new(table: node.table, columns: [], filter: node.filter)
+      owned = node.columns.map { |column| [owner(table: node.table, column:), column, nil] } +
+              node.renames.map { |name, column| [renamed_owner(table: node.table, name:, column:), column, name] }
+      selections = owned.map { |table, column, name| name ? Sequel[table][column].as(name) : Sequel[table][column] }
 
-      tree = (owners.values.uniq - [node.table]).reduce(base) do |left, table|
-        DataExpression::Join.new(type: :left, left:, right: DataExpression::Source.new(table:, columns: []))
-      end
-
-      [tree, owners.map { |column, table| Sequel[table][column] }]
+      [tree(node:, tables: owned.map(&:first)), selections]
     end
 
     private
 
     def owner(table:, column:)
-      return table if @schema.columns(table:).include?(column)
-
-      owners = @schema.related_tables(table:).select { |related| @schema.columns(table: related).include?(column) }
+      owners = owners(table:, column:)
       raise JoinError, "No table related to #{table} has a #{column} column" if owners.empty?
       raise JoinError, ambiguous_message(table:, column:, owners:) if owners.length > 1
 
       owners.first
     end
 
+    def owners(table:, column:)
+      return [table] if @schema.columns(table:).include?(column)
+
+      @schema.related_tables(table:).select { |related| @schema.columns(table: related).include?(column) }
+    end
+
+    # The owner of a renamed column, which mustn't also have a column with the new name.
+    def renamed_owner(table:, name:, column:)
+      if owners(table:, column:).empty? && owners(table:, column: name).any?
+        raise ArgumentError, "No table related to #{table} has a #{column} column. To rename #{name}, write #{column}: :#{name}"
+      end
+
+      owner(table:, column:).tap { |owner| @schema.check_renames!(table: owner, renames: { name => column }) }
+    end
+
+    # The repository's table left joined to each other table that owns a column. Joins link to the table before them,
+    # so each table names the foreign keys that link it to the repository's table, on whichever side they are.
+    def tree(node:, tables:)
+      owners = tables.uniq - [node.table]
+      base_keys = owners.flat_map { |table| link_columns(from: node.table, to: table) }
+      base = DataExpression::Source.new(table: node.table, columns: [], filter: node.filter.merge(named(base_keys)))
+
+      owners.reduce(base) do |left, table|
+        right = DataExpression::Source.new(table:, columns: [], filter: named(link_columns(from: table, to: node.table)))
+        DataExpression::Join.new(type: :left, left:, right:)
+      end
+    end
+
+    def link_columns(from:, to:)
+      @schema.links(from:, to:).flat_map { |link| link[:columns] }
+    end
+
+    def named(foreign_keys)
+      DataExpression::Filter.new(foreign_keys:)
+    end
+
     def ambiguous_message(table:, column:, owners:)
       "#{owners.join(' and ')} both have a #{column} column and are related to #{table}. " \
         "Join explicitly instead, e.g. #{LowData.constant_name(table)}[] < #{LowData.constant_name(owners.first)}[:#{column}]"

data/lib/lowdata.rb

@@ -13,9 +13,13 @@ require_relative 'order_compiler'
 require_relative 'filter_compiler'
 require_relative 'schema'
 require_relative 'inversion'
+require_relative 'nested_join'
 require_relative 'nesting'
 require_relative 'nesting_tree'
+require_relative 'nesting_path'
 require_relative 'query_compiler'
+require_relative 'writer'
+require_relative 'expression_writes'
 require_relative 'table_reference'
 
 class LowData

data/lib/nested_join.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+class LowData
+  # A join in a nesting tree, loaded with one query by QueryCompiler. It nests as flat rows, and tables nest under each
+  # of its rows, through its table written next to the +: its first table after a +, and its last table before one.
+  #   Users[:username] + (Posts[:title] & Comments[:body]) # => [{ username: 'alice', posts: [{ title: 'Hello', body: 'Nice' }] }]
+  #   (Users[:username] & Posts[:title]) + Comments[:body] # => [{ username: 'alice', title: 'Hello', comments: [{ body: 'Nice' }] }]
+  #
+  # A foreign key named in round brackets links through another of its tables:
+  #   Users[:username] + (Posts[:title] & Likes(:user_id)[:id]) # Links through likes.user_id.
+  NestedJoin = ::Data.define(:node, :tables, :table, :foreign_keys)
+
+  class NestedJoin
+    def self.build(node:)
+      sources = sources_in(node:)
+      foreign_keys = sources.to_h { |source| [source.table, source.filter.foreign_keys] }
+      new(node:, tables: sources.map(&:table), table: nil, foreign_keys:)
+    end
+
+    # A join holds only tables joined with &, <, > or <=>, as QueryCompiler requires.
+    def self.sources_in(node:)
+      raise JoinError, QueryCompiler::INVERSION_JOIN_MESSAGE if node.is_a?(DataExpression::Inversion)
+      raise JoinError, QueryCompiler::ORDERED_JOIN_MESSAGE if node.is_a?(DataExpression::Ordered)
+      return [node] if node.is_a?(DataExpression::Source)
+      raise JoinError, QueryCompiler::NESTING_JOIN_MESSAGE if node.nest?
+
+      sources_in(node: node.left) + sources_in(node: node.right)
+    end
+
+    # Returns the join with its table, and the key and Link that nest it under `parent`. Only the "many" side can nest a
+    # join, because joined rows can repeat the table's rows.
+    def link(parent:, key:, tree:, schema:, foreign_keys:)
+      table = linked_table(others: [parent], schema:, foreign_keys:, nested: true)
+      key, link = tree.link_to(parent:, child: table, key:)
+      raise JoinError, one_side_message(parent:, table:) unless link.many
+
+      [with(table:), key, link]
+    end
+
+    # The table the join links to `others` through: the one written next to the +, unless a foreign key named in round
+    # brackets links another. `foreign_keys` are the named foreign keys of `others`, by table. `nested` is true when the
+    # join nests in `others`, so the + is before its first table, and false when `others` nest in it, after its last.
+    def linked_table(others:, schema:, foreign_keys:, nested: false)
+      named = named(others:, schema:, foreign_keys: self.foreign_keys.merge(foreign_keys))
+      table = named.first || (nested ? tables.first : tables.last)
+      return table if others.any? { |other| schema.linked?(table, other) }
+
+      raise JoinError, unlinked_message(table:, others:, schema:)
+    end
+
+    private
+
+    # The join's tables whose foreign key to `others`, on either side, is named in round brackets.
+    def named(others:, schema:, foreign_keys:)
+      tables.select do |table|
+        others.any? do |other|
+          columns = (schema.links(from: table, to: other) + schema.links(from: other, to: table)).flat_map { |link| link[:columns] }
+          (columns & (foreign_keys.fetch(table, []) + foreign_keys.fetch(other, []))).any?
+        end
+      end
+    end
+
+    # Suggests naming the foreign key of another of the join's tables that links, on the table that has it.
+    def unlinked_message(table:, others:, schema:)
+      names = others.join(', ')
+      choices = (tables - [table]).product(others).flat_map do |linked, other|
+        [[linked, other], [other, linked]].flat_map do |from, to|
+          schema.links(from:, to:).map { |link| "#{LowData.constant_name(from)}(:#{link[:columns].first})" }
+        end
+      end
+      message = "No foreign key links #{table} to #{names}, and a join links through its table written next to the +"
+      return message if choices.empty?
+
+      "#{message}. Write the table that links next to the +, or name its foreign key: #{choices.sort.join(' or ')}"
+    end
+
+    def one_side_message(parent:, table:)
+      "#{parent} points to #{table}, so a join with #{table} can't nest in #{parent}, because its rows can repeat " \
+        "#{table}. Nest #{table} in brackets instead"
+    end
+  end
+end

data/lib/nesting.rb

@@ -5,18 +5,47 @@ class LowData
   #   Posts[:title, Users[:username]]  # => [{ title: 'Hello', user: { username: 'alice' } }]
   #   Users[:username] + Posts[:title] # => [{ username: 'alice', posts: [{ title: 'Hello' }] }]
   # In a + chain the first table is the subject, and each other operand nests under the table its foreign key links it to.
+  # A join nests as flat rows, loaded with one query, and tables can nest under each of its rows: see NestedJoin.
   class Nesting
     # A table in the nesting tree. `link` connects it to its parent node: `parent_column` on the parent's rows matches
     # `child_column` on this table's rows, and `many` nests the matches as an array rather than one object.
-    # `keys` and `rows` sort and limit the table's rows, per parent when it's nested.
+    # `keys` and `rows` sort and limit the table's rows, per parent when it's nested. `source` is a table or a NestedJoin.
     Node = ::Data.define(:source, :key, :link, :children, :keys, :rows) do
       def initialize(source:, key:, link:, children:, keys: [], rows: nil)
         super
       end
     end
-    Link = ::Data.define(:parent_column, :child_column, :many)
+
+    class Node
+      def join
+        source if source.is_a?(NestedJoin)
+      end
+
+      def tables
+        join ? join.tables : [source.table]
+      end
+
+      # The foreign keys named in round brackets, by table: `Posts(:user_id)`.
+      def foreign_keys
+        join ? join.foreign_keys : { source.table => source.filter.foreign_keys }
+      end
+    end
+    # `parent_table` is set when the parent is a join, whose rows hold `parent_column` under `parent_key`.
+    Link = ::Data.define(:parent_column, :child_column, :many, :parent_table) do
+      def initialize(parent_column:, child_column:, many:, parent_table: nil)
+        super
+      end
+
+      def parent_key
+        parent_table ? :"lowdata_#{parent_table}_#{parent_column}" : parent_column
+      end
+    end
 
     ROW_NUMBER = :lowdata_row_number
+    # Stands in for the parent values a nested table's query is filtered by, which aren't known until the parents load.
+    PARENT_VALUES = Sequel.lit('(...)')
+    # A nested join's link value, selected under its own name so it can't clash with the joined columns.
+    LINK = :lowdata_link
 
     def initialize(database:)
       raise ConfigError, ConfigError::MISSING_DATABASE if database.nil?
@@ -25,34 +54,60 @@ class LowData
       @schema = Schema.new(database:)
       @filters = FilterCompiler.new(database:, schema: @schema)
       @orders = OrderCompiler.new(schema: @schema)
+      @queries = QueryCompiler.new(database:)
     end
 
     def load(node:)
       root = NestingTree.new(schema: @schema).build(node:)
-      shape(node: root, rows: fetch(node: root))
+      shape(node: root, rows: dataset(node: root).all)
+    end
+
+    # The SQL of each query `load` runs, parents first, without running them. A nested table's query shows the parent
+    # values it's filtered by as `IN (...)`.
+    def sql(node:)
+      queries(node: NestingTree.new(schema: @schema).build(node:)).map(&:sql)
     end
 
     private
 
-    def fetch(node:, filter: nil)
-      dataset = @filters.apply(dataset: @database[node.source.table].select(*select_columns(node:)), source: node.source)
-      dataset = dataset.where(filter) if filter
-      return per_parent(node:, dataset:) if filter && node.rows
+    def queries(node:, values: nil)
+      [dataset(node:, values:), *node.children.flat_map { |child| queries(node: child, values: PARENT_VALUES) }]
+    end
+
+    # A node's rows, or when it's nested, its rows linked to the parents' `values`.
+    def dataset(node:, values: nil)
+      dataset = node.join ? join_dataset(node:) : table_dataset(node:)
+      dataset = dataset.where(Sequel::SQL::BooleanExpression.new(:IN, link_column(node:), values)) if values
+      return per_parent(node:, dataset:) if values && node.rows
+
+      @orders.apply(dataset:, keys: node.keys, rows: node.rows, tables: node.tables)
+    end
+
+    def table_dataset(node:)
+      @schema.check_renames!(table: node.source.table, renames: node.source.renames)
+      @filters.apply(dataset: @database[node.source.table].select(*select_columns(node:)), source: node.source)
+    end
+
+    # A join's rows, with the columns its parent and children link by selected under LINK and each Link#parent_key.
+    def join_dataset(node:)
+      parents = node.children.map { |child| Sequel[child.link.parent_table][child.link.parent_column].as(child.link.parent_key) }
+      links = node.link ? [link_column(node:).as(LINK)] : []
+      @queries.compile(node: node.join.node).select_append(*parents.uniq, *links)
+    end
 
-      @orders.apply(dataset:, keys: node.keys, rows: node.rows, tables: [node.source.table]).all
+    def link_column(node:)
+      node.join ? Sequel[node.source.table][node.link.child_column] : node.link.child_column
     end
 
     # Keeps each parent's rows, e.g. each user's 3 most viewed posts, by numbering the rows within each parent.
     def per_parent(node:, dataset:)
       numbered = dataset.select_append(row_number(node:).as(ROW_NUMBER))
       @database.from(numbered).where(ROW_NUMBER => row_numbers(rows: node.rows)).order(ROW_NUMBER)
-               .all.map { |row| row.except(ROW_NUMBER) }
     end
 
     def row_number(node:)
-      table = node.source.table
-      order = @orders.order(keys: node.keys, tables: [table])
-      Sequel.function(:row_number).over(partition: Sequel[table][node.link.child_column], order: order.empty? ? nil : order)
+      order = @orders.order(keys: node.keys, tables: node.tables)
+      Sequel.function(:row_number).over(partition: Sequel[node.source.table][node.link.child_column], order: order.empty? ? nil : order)
     end
 
     # Row numbers start at 1, and rows count from 0.
@@ -64,10 +119,11 @@ class LowData
 
     # The columns asked for, plus the columns each link needs.
     def select_columns(node:)
-      return [Sequel[node.source.table].*] if node.source.columns.empty?
+      source = node.source
+      return [Sequel[source.table].*] if source.every_column?
 
       link_columns = [node.link&.child_column, *node.children.map { |child| child.link.parent_column }].compact
-      (node.source.columns + link_columns).uniq
+      (source.columns + link_columns).uniq + source.aliases
     end
 
     # Turns fetched rows into output hashes: the columns asked for, plus each child nested under its key.
@@ -75,25 +131,32 @@ class LowData
       nested = node.children.to_h { |child| [child, nested_rows(child:, rows:)] }
 
       rows.map do |row|
-        output = node.source.columns.empty? ? row.dup : row.slice(*node.source.columns)
+        output = columns(node:, row:)
         node.children.each { |child| output[child.key] = matches(child:, row:, nested: nested[child]) }
         output
       end
     end
 
+    def columns(node:, row:)
+      return row.except(LINK, ROW_NUMBER, *node.children.map { |child| child.link.parent_key }) if node.join
+
+      node.source.every_column? ? row.except(ROW_NUMBER) : row.slice(*node.source.names)
+    end
+
     def matches(child:, row:, nested:)
-      matches = nested.fetch(row[child.link.parent_column], [])
+      matches = nested.fetch(row[child.link.parent_key], [])
       child.link.many ? matches : matches.first
     end
 
     # Fetches a child's rows for all parent rows in one query, grouped by the value that links them.
     def nested_rows(child:, rows:)
-      values = rows.map { |row| row[child.link.parent_column] }.compact.uniq
+      values = rows.map { |row| row[child.link.parent_key] }.compact.uniq
       return {} if values.empty?
 
-      child_rows = fetch(node: child, filter: { child.link.child_column => values })
+      child_rows = dataset(node: child, values:).all
+      link_column = child.join ? LINK : child.link.child_column
       child_rows.zip(shape(node: child, rows: child_rows))
-                .group_by { |row, _output| row[child.link.child_column] }
+                .group_by { |row, _output| row[link_column] }
                 .transform_values { |pairs| pairs.map(&:last) }
     end
   end

data/lib/nesting_path.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+class LowData
+  # Lays out a + chain for NestingTree. Each operand nests in the operand before it, and an array nests its expressions
+  # side by side in the table before it, ending the chain:
+  #   Users + Posts + Comments                # comments in posts, in users
+  #   Users + [Posts + Comments, Likes]       # posts with their comments, and likes, in users
+  #   Users + Posts + Likes(:user_id)         # a named foreign key reaches back: likes in users, beside posts
+  # Foreign keys only link adjacent tables, so a foreign key between other tables can't change or break the chain.
+  class NestingPath
+    ARRAY_END_MESSAGE = 'An array ends a + chain, because it nests several tables. Put the rest of the chain in the ' \
+                        'array, e.g. Users + [Posts + Comments, Orders]'
+
+    # A node waiting for its children to be linked, and the entries from it down to the end of its chain.
+    Entry = Struct.new(:node, :children, :tail, :closed) do
+      def self.for(node) = new(node, [], nil, false)
+
+      def path = self[:tail] || [self]
+
+      def tables = node.tables
+    end
+
+    def initialize(schema:, tree:)
+      @schema = schema
+      @tree = tree
+    end
+
+    # A + chain is left deep, and + is associative, so a parenthesised chain's operands join the path.
+    def self.segments(node:)
+      return [node] unless node.is_a?(DataExpression::Join) && node.nest?
+
+      segments(node: node.left) + segments(node: node.right)
+    end
+
+    # Returns the first segment's entry, with every other segment nested under it.
+    def chain(segments:)
+      root = @tree.entry(node: segments.first)
+      path = segments.drop(1).reduce(root.path) { |entries, segment| attach(path: entries, segment:) }
+      root.tap { |entry| entry.tail = path }
+    end
+
+    private
+
+    # Nests a segment and returns the path to the end of the chain.
+    def attach(path:, segment:)
+      raise JoinError, ARRAY_END_MESSAGE if path.last.closed
+      return siblings(path:, nodes: segment.nodes) if segment.is_a?(DataExpression::Siblings)
+
+      child = @tree.entry(node: segment)
+      parent = parent(path:, child:)
+      parent.children << child
+      path[0..path.index { |entry| entry.equal?(parent) }] + child.path
+    end
+
+    def siblings(path:, nodes:)
+      nodes.each { |node| path.last.children << @tree.entry(node:) }
+      path.last.closed = true
+      path
+    end
+
+    # The tables before the last, nearest first.
+    def earlier(path:) = path[0...-1].reverse
+
+    # The table before, unless a foreign key named in the child's round brackets points to an earlier one.
+    def parent(path:, child:)
+      targets = named_targets(child:)
+      tables = targets.map(&:last)
+      return linked!(path:, child:) if tables.empty? || (path.last.tables & tables).any?
+
+      earlier(path:).find { |entry| (entry.tables & tables).any? } ||
+        raise(JoinError, "#{targets.first.first} points to #{tables.first}, which isn't earlier in this + chain")
+    end
+
+    # Each foreign key named in the child's round brackets, as `table.column` and the table it points to. A key between
+    # a join's own tables links the join, not the chain, so it's left out.
+    def named_targets(child:)
+      child.node.foreign_keys.flat_map do |table, columns|
+        keys = @schema.foreign_keys(table:).select { |key| (key[:columns] & columns).any? && !child.tables.include?(key[:table]) }
+        keys.map { |key| ["#{table}.#{key[:columns].first}", key[:table]] }
+      end
+    end
+
+    # The table before, when a foreign key links the two. Otherwise it suggests nesting the child in an earlier table.
+    def linked!(path:, child:)
+      parent = path.last
+      raise JoinError, "Can't nest #{parent.tables.join(', ')} in itself" if parent.tables == child.tables
+      return parent if linked?(child, parent)
+
+      earlier = earlier(path:).find { |entry| linked?(child, entry) }
+      raise JoinError, unlinked_message(child: child.tables.first, parent: parent.tables.last, earlier: earlier&.tables&.last)
+    end
+
+    def linked?(entry, other)
+      entry.tables.product(other.tables).any? { |table, other_table| @schema.linked?(table, other_table) }
+    end
+
+    # Suggests an array, or naming the foreign key that reaches back to the earlier table.
+    def unlinked_message(child:, parent:, earlier:)
+      message = "No foreign key links #{child} to #{parent}"
+      return message unless earlier
+
+      names = [earlier, parent, child].map { |table| LowData.constant_name(table) }
+      key = @schema.links(from: child, to: earlier).first
+      "#{message}. To nest #{child} in #{earlier}, beside #{parent}, write #{names[0]} + [#{names[1]}, #{names[2]}]" +
+        (key ? " or name its foreign key: #{names[2]}(:#{key[:columns].first})" : '')
+    end
+  end
+end