lowdata 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5902c4edccd0a49aec0a211a75c7dd3cbc277721155989ff0d4b9abbd84bb153
-  data.tar.gz: cdb2e97726f61229d527d099c62f550e6d35f7dd984359d5a8bc6e62c0826b8d
+  metadata.gz: 00edcbe16f363ff5571130711b163c2b7a30f269b063237d9513f0d0d65b1ac9
+  data.tar.gz: b76da81116417a88cb6d440acfcd676aee2f9f53726c8b079551e4ab6df5279f
 SHA512:
-  metadata.gz: 46deb79a98865325e79647f77a0f20a853146dfbcf6cede25a9e77433f8dc291f2ae09fe6d2d63d827b2a0e3e5f1c850d19c040f63cfad0b94b1c4515e93052b
-  data.tar.gz: 87560d6313de8eca179b1ac1e6526258ca1fd0d4dc64b1fe24a1c5adb99fbc408bad0e876b9f381001f7d8079f045c5bed9cb1c4adef2ba365cbd6edcc961a2e
+  metadata.gz: 76724feffd8a520b11e60bd387ebf1a3aa7543fc7bb962af8b4b5db4411f9099fa42cef7207c98592cf6687a393076b51f3ffad45b198e32b885f8636accac93
+  data.tar.gz: f555c5e21c68df568a8e02e511f9fd6ee8ced5ca9a97edc799eb95415e96fb56c38b2711eb161546fe7c00b775905c1418127b146caddb474a96c9ede039062b

data/lib/data_expression/source.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+class LowData
+  class DataExpression < ::Expressions::Expression
+    # A table with the columns to select, the columns renamed (`headline: :title`), the tables nested in its brackets and
+    # the filter on its rows. `bare` is a table without brackets, `Posts`, which selects every column. See ADR 0006.
+    Source = ::Data.define(:table, :columns, :renames, :nested, :filter, :bare) do
+      def initialize(table:, columns:, renames: {}, nested: [], filter: Filter.new, bare: false)
+        super
+      end
+    end
+
+    class Source
+      # A bare table, `Posts`, selects every column.
+      def every_column? = bare
+
+      # Empty brackets, `Posts[]`, select no columns.
+      def no_columns? = !bare && 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
+  end
+end

data/lib/data_expression.rb

@@ -27,30 +27,12 @@ class LowData
     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 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) do
       def nest? = type == :nest
     end
-    # Tables nested side by side in the table before them: `Posts[:title] + [Comments[:body], Likes[]]`.
+    # 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`.
@@ -67,6 +49,7 @@ class LowData
     SORT_MESSAGE = 'Sort by columns with Col[], e.g. Posts[:title] ^ Col[:views], not %<value>s'
     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_DATASET_MESSAGE if nested?
 
@@ -109,9 +92,10 @@ class LowData
     end
 
     def add_siblings(expressions)
+      expressions = expressions.map { |expression| TableReference.expression(expression) }
       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?
+      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
@@ -153,7 +137,9 @@ class LowData
         @node = Join.new(type:, left: @node, right: expression.node)
       end
 
+      # A bare table on the right, `Users[:username] + Posts`, joins as every column of the table.
       define_method(:"#{prefix}_value") do |value|
+        return send(:"#{prefix}_expression", value.to_expression) if value.is_a?(TableReference)
         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}"

data/lib/lowdata.rb

@@ -7,6 +7,7 @@ require 'sequel'
 require_relative 'version'
 require_relative 'errors'
 require_relative 'data_expression'
+require_relative 'data_expression/source'
 require_relative 'rows'
 require_relative 'col'
 require_relative 'order_compiler'
@@ -19,8 +20,9 @@ require_relative 'nesting_tree'
 require_relative 'nesting_path'
 require_relative 'query_compiler'
 require_relative 'writer'
-require_relative 'expression_writes'
+require_relative 'data_expression/writes'
 require_relative 'table_reference'
+require_relative 'table_reference/writes'
 
 class LowData
   class << self
@@ -72,8 +74,12 @@ class LowData
   # Round brackets after a table filter it: `Posts(published: true) { views > 100 }[:title]`. A capitalised name is a
   # table only when the database has that table, so typos still raise NoMethodError. `Table(...)` is always a table.
   def method_missing(name, *arguments, **keywords, &block)
-    raise ConfigError, ConfigError::MISSING_DATABASE if LowData.database.nil? && name.match?(/\A[A-Z]/)
-    return super unless table_method?(name:)
+    return super unless name.match?(/\A[A-Z]/)
+    raise ConfigError, ConfigError::MISSING_DATABASE if LowData.database.nil?
+
+    # Raised rather than left to super, which can report a NameError instead when looking up the tables runs a
+    # method_missing of its own, as Postgres' adapter does.
+    raise NoMethodError.new("undefined method '#{name}' for an instance of #{self.class}", name) unless table_method?(name:)
 
     self.class.const_missing(name).where(*arguments, **keywords, &block)
   end

data/lib/nesting.rb

@@ -58,14 +58,14 @@ class LowData
     end
 
     def load(node:)
-      root = NestingTree.new(schema: @schema).build(node:)
+      root = NestingTree.new(schema: @schema).root(node:)
       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)
+      queries(node: NestingTree.new(schema: @schema).root(node:)).map(&:sql)
     end
 
     private
@@ -92,7 +92,7 @@ class LowData
     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)
+      @queries.compile(node: node.join.node, links: [*parents.uniq, *links])
     end
 
     def link_column(node:)

data/lib/nesting_tree.rb

@@ -13,6 +13,14 @@ class LowData
       assemble(entry: entry(node:))
     end
 
+    # The tree whose first table is returned, so empty brackets, which select none of its columns, raise.
+    def root(node:)
+      root = build(node:)
+      raise ArgumentError, QueryCompiler.no_columns_message(table: root.source.table) if !root.join && root.source.no_columns?
+
+      root
+    end
+
     # An expression's node, waiting for the children NestingPath nests in it.
     def entry(node:)
       raise JoinError, QueryCompiler::INVERSION_JOIN_MESSAGE if node.is_a?(DataExpression::Inversion)

data/lib/order_compiler.rb

@@ -18,10 +18,12 @@ class LowData
       dataset.limit(rows.limit, rows.offset.zero? ? nil : rows.offset)
     end
 
+    # Rows without a value sort last in both directions, so `-Col[:views] * 10` is the 10 most viewed on every database.
+    # Postgres puts NULLs last ascending and first descending, and SQLite and MySQL the reverse.
     def order(keys:, tables:)
       keys.map do |key|
         column = Sequel[owner(column: key.column, tables:)][key.column]
-        key.descending ? column.desc : column
+        key.descending ? column.desc(nulls: :last) : column.asc(nulls: :last)
       end
     end
 

data/lib/query_compiler.rb

@@ -6,7 +6,8 @@ class LowData
     INVERSION_JOIN_MESSAGE = "Table[] can't be joined with other expressions"
     NESTING_JOIN_MESSAGE = 'Nested tables return nested data, so + and tables nested in brackets can\'t be combined with &, <, > ' \
                            'or <=>. Nest the join instead, e.g. Users[:username] + (Posts[:title] & Comments[:body])'
-    ORDERED_JOIN_MESSAGE = 'Sort and limit after joining, e.g. (Users[] < Posts[]) ^ Col[:username]. Ruby binds ^ tighter ' \
+    FULL_JOIN_MESSAGE = 'MySQL has no FULL JOIN, so <=> only runs on other databases. Use < or > for a left or right join'
+    ORDERED_JOIN_MESSAGE = 'Sort and limit after joining, e.g. (Users < Posts) ^ Col[:username]. Ruby binds ^ tighter ' \
                            'than <, > and <=>, and * and / tighter than every join, so add parentheses around the join'
 
     def initialize(database:)
@@ -18,26 +19,37 @@ class LowData
       @orders = OrderCompiler.new(schema: @schema)
     end
 
-    def compile(node:)
-      return compile_ordered(node:) if node.is_a?(DataExpression::Ordered)
+    # `links` are columns a nested join selects to link its rows, as well as the columns asked for. See Nesting.
+    def compile(node:, links: [])
+      return compile_ordered(node:, links:) if node.is_a?(DataExpression::Ordered)
 
-      compile_unordered(node:, sources: [])
+      compile_unordered(node:, sources: [], links:)
+    end
+
+    # Empty brackets select no columns, so a query of only those has nothing to return.
+    def self.no_columns_message(table:)
+      name = LowData.constant_name(table)
+      "Empty brackets select no columns, so #{name}[] returns nothing. Write #{name} for every column, or name them, " \
+        "e.g. #{name}[:id]"
     end
 
     private
 
     # Sort keys and rows apply to the whole query, so each sort column can belong to any joined table.
-    def compile_ordered(node:)
+    def compile_ordered(node:, links:)
       sources = []
-      dataset = compile_unordered(node: node.node, sources:)
+      dataset = compile_unordered(node: node.node, sources:, links:)
       @orders.apply(dataset:, keys: node.keys, rows: node.rows, tables: sources.map(&:table))
     end
 
-    def compile_unordered(node:, sources:)
+    def compile_unordered(node:, sources:, links:)
       return compile_inversion(node:, sources:) if node.is_a?(DataExpression::Inversion)
 
       dataset = filter(dataset: build(node:, sources:), sources:)
-      dataset.select(*sources.flat_map { |source| selections(source:) })
+      selections = sources.flat_map { |source| selections(source:) } + links
+      raise ArgumentError, QueryCompiler.no_columns_message(table: sources.first.table) if selections.empty?
+
+      dataset.select(*selections)
     end
 
     def compile_inversion(node:, sources:)
@@ -57,14 +69,18 @@ class LowData
     end
 
     def join_dataset(dataset:, type:, right:, sources:)
+      check_join!(type:, right:, sources:)
+      conditions = join_conditions(left: sources, right:)
+      sources << right
+      dataset.join_table(type, right.table, conditions)
+    end
+
+    def check_join!(type:, right:, sources:)
       raise JoinError, INVERSION_JOIN_MESSAGE if right.is_a?(DataExpression::Inversion)
       raise JoinError, ORDERED_JOIN_MESSAGE if right.is_a?(DataExpression::Ordered)
       raise JoinError, NESTING_JOIN_MESSAGE if right.nested.any?
       raise JoinError, "Can't join #{right.table} to itself" if sources.any? { |source| source.table == right.table }
-
-      conditions = join_conditions(left: sources, right:)
-      sources << right
-      dataset.join_table(type, right.table, conditions)
+      raise JoinError, FULL_JOIN_MESSAGE if type == :full && @database.database_type == :mysql
     end
 
     def nesting?(node:)
@@ -83,6 +99,7 @@ class LowData
       sources.reduce(dataset) { |filtered, source| @filters.apply(dataset: filtered, source:) }
     end
 
+    # A bare table selects every column, and empty brackets select none.
     def selections(source:)
       return [Sequel[source.table].*] if source.every_column?
 
@@ -116,8 +133,8 @@ class LowData
     end
 
     def nested_join_message
-      'Ruby evaluated a join on the right first, e.g. `Users[] < Posts[] & Comments[]` runs `Posts[] & Comments[]` first ' \
-        'because & binds tighter than <. Add parentheses to join from the left: `(Users[] < Posts[]) & Comments[]`'
+      'Ruby evaluated a join on the right first, e.g. `Users < Posts & Comments` runs `Posts & Comments` first ' \
+        'because & binds tighter than <. Add parentheses to join from the left: `(Users < Posts) & Comments`'
     end
   end
 end

data/lib/rows.rb

@@ -2,9 +2,9 @@
 
 class LowData
   # Which sorted rows to keep. Rows count from 0, as in Ruby:
-  #   Posts[] * 10                 # LIMIT 10
-  #   (Posts[] / 20)[2]            # LIMIT 20 OFFSET 40, the third page of 20
-  #   Posts[] ^ Col[:id][20...40]  # LIMIT 20 OFFSET 20
+  #   Posts * 10                   # LIMIT 10
+  #   (Posts / 20)[2]              # LIMIT 20 OFFSET 40, the third page of 20
+  #   Posts ^ Col[:id][20...40]    # LIMIT 20 OFFSET 20
   # Pages have a `page_size` until a page is picked, and a `limit` and `offset` after.
   Rows = ::Data.define(:offset, :limit, :page_size) do
     def self.limit(count)

data/lib/schema.rb

@@ -28,7 +28,8 @@ class LowData
         foreign_keys(table: other).any? { |foreign_key| foreign_key[:table] == table }
       end
 
-      (outgoing + incoming).uniq - [table]
+      # Sorted, because databases list their tables in different orders, and error messages name the first.
+      ((outgoing + incoming).uniq - [table]).sort
     end
 
     # Foreign keys on the `from` table that reference the `to` table, as join conditions. `named` keeps only the foreign

data/lib/table_reference/writes.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+class LowData
+  class TableReference
+    # Writes run straight away. See Writer:
+    #   Posts << { title: 'Hello' }                 # Inserts, returning the new row's primary key.
+    #   Posts(slug: 'hello') <= { title: 'Hello' }  # Upserts, matching on the round brackets.
+    #   Posts(id: 1)[:title] = 'New'                # Updates the rows chosen by the round brackets.
+    #   Posts(id: 1).delete                         # Deletes them, returning how many.
+    module Writes
+      def <<(rows)
+        writer.insert(source: write_source, rows:)
+      end
+
+      def <=(rows)
+        writer.upsert(source: write_source, rows:)
+      end
+
+      # Ruby makes an assignment return its right-hand side, so `Posts(id: 1)[:title] = 'New'` returns 'New'.
+      def []=(*columns, value)
+        writer.update(source: write_source, values: assignments(columns:, value:))
+      end
+
+      def delete
+        writer.delete(source: write_source)
+      end
+
+      private
+
+      def writer
+        Writer.new(database: LowData.database)
+      end
+
+      def write_source
+        raise ArgumentError, "~#{LowData.constant_name(table)} filters by related rows, so it can't be written to" if negated
+
+        source
+      end
+
+      # The columns in square brackets and the value assigned to them:
+      #   Posts(id: 1)[:title] = 'New'                  # One column takes a value.
+      #   Posts(id: 1)[:title, :body] = ['New', '...']  # Several columns take an array of as many values.
+      #   Posts(id: 1)[] = { title: 'New' }             # Empty brackets take a hash of columns and values.
+      def assignments(columns:, value:)
+        check_columns!(columns:)
+        return assigned_hash(value:) if columns.empty?
+        return { columns.first => assigned_value(value:) } if columns.one?
+        return columns.zip(value).to_h if value.is_a?(Array) && value.length == columns.length
+
+        raise ArgumentError, "#{columns.length} columns take #{columns.length} values, e.g. Posts(id: 1)[:title, :body] = ['New', '...']"
+      end
+
+      # Sequel would write a hash into one column as a condition, storing 0 or 1, so a hash for one column raises.
+      def assigned_value(value:)
+        return value unless value.is_a?(Hash)
+
+        raise ArgumentError, 'One column takes one value, not a hash. To set the columns in a hash, use empty brackets, e.g. ' \
+                             "Posts(id: 1)[] = { title: 'New' }"
+      end
+
+      def assigned_hash(value:)
+        return value if value.is_a?(Hash) && value.any?
+
+        raise ArgumentError, "Empty brackets take a hash of columns and values, e.g. Posts(id: 1)[] = { title: 'New' }"
+      end
+    end
+
+    include Writes
+  end
+end

data/lib/table_reference.rb

@@ -1,11 +1,18 @@
 # frozen_string_literal: true
 
 class LowData
-  # A table named by a constant, such as `Users`, waiting for its columns: `Users[:username]`.
+  # A table named by a constant, such as `Users`. Square brackets choose its columns, `Users[:username]`, and on its own
+  # it's every column. See ADR 0006.
   # An inverted reference is `Table`, standing in for the repository's table and any table related to it.
   # A reference can carry filters from round brackets, `Posts(published: true)`, and be negated with `~Posts`.
   class TableReference
     FILTER_KEYWORD_MESSAGE = 'Filters go in round brackets, e.g. Posts(published: true)[:title], not %<keywords>s'
+    BARE_TABLE_MESSAGE = 'Table joins the tables that own the columns it selects, so name them, e.g. Table[:title, :username]. ' \
+                         "For every column of the repository's table, name the table, e.g. Posts"
+    OPERATORS = %i[+ & < > <=> ^ * /].freeze
+
+    # A bare table on its own is every column, as a data expression: `Users[:username] + Posts`.
+    def self.expression(value) = value.is_a?(TableReference) ? value.to_expression : value
 
     attr_reader :table, :filter, :negated
 
@@ -17,14 +24,16 @@ class LowData
     end
 
     # Each argument's type decides its meaning:
-    #   Posts[:title]                              # A symbol is a column. No columns selects every column.
-    #   Users[:username, Posts[:title]]            # A data expression is a nested table.
+    #   Posts[:title]                              # A symbol is a column. Empty brackets select no columns.
+    #   Users[:username, Posts[:title]]            # A data expression is a nested table, and a bare table nests
+    #   Users[:username, Posts]                    # every column.
     #   Reviews[:rating, author: Users[:username]] # A keyword with a data expression names a nested table.
     #   Posts[:id, headline: :title]               # A keyword with a symbol renames a column.
     def [](*arguments, **keywords)
-      raise ArgumentError, "~#{LowData.constant_name(table)} filters by related rows, so it can't select columns" if negated
+      check_negated!
       return inverted(arguments:, keywords:) if @inverted
 
+      arguments = arguments.map { |argument| TableReference.expression(argument) }
       expressions, columns = arguments.partition { |argument| argument.is_a?(DataExpression) }
       check_columns!(columns:)
       named, renames = named(keywords:, columns:)
@@ -60,65 +69,37 @@ class LowData
       with(negated: !negated)
     end
 
-    # Writes run straight away. See Writer:
-    #   Posts << { title: 'Hello' }                 # Inserts, returning the new row's primary key.
-    #   Posts(slug: 'hello') <= { title: 'Hello' }  # Upserts, matching on the round brackets.
-    #   Posts(id: 1)[:title] = 'New'                # Updates the rows chosen by the round brackets.
-    #   Posts(id: 1).delete                         # Deletes them, returning how many.
-    def <<(rows)
-      writer.insert(source: write_source, rows:)
-    end
+    # A bare table reads and joins as every column of the table:
+    #   Posts                          # SELECT posts.* FROM posts
+    #   Users[:username] + Posts       # Each user with every column of their posts.
+    #   Posts ^ -Col[:views] * 10      # The 10 most viewed posts.
+    def to_expression
+      raise ArgumentError, BARE_TABLE_MESSAGE if @inverted
 
-    def <=(rows)
-      writer.upsert(source: write_source, rows:)
+      check_negated!
+      DataExpression.new(node: source)
     end
 
-    # Ruby makes an assignment return its right-hand side, so `Posts(id: 1)[:title] = 'New'` returns 'New'.
-    def []=(*columns, value)
-      writer.update(source: write_source, values: assignments(columns:, value:))
+    OPERATORS.each do |operator|
+      define_method(operator) { |other| to_expression.public_send(operator, other) }
     end
 
-    def delete
-      writer.delete(source: write_source)
+    %i[to_a sql dataset].each do |name|
+      define_method(name) { |**options| to_expression.public_send(name, **options) }
     end
 
     def source
-      DataExpression::Source.new(table:, columns: [], filter:)
+      DataExpression::Source.new(table:, columns: [], filter:, bare: true)
     end
 
     private
 
-    def with(filter: @filter, negated: @negated)
-      self.class.new(table:, inverted: @inverted, filter:, negated:)
-    end
-
-    def writer
-      Writer.new(database: LowData.database)
-    end
-
-    def write_source
-      raise ArgumentError, "~#{LowData.constant_name(table)} filters by related rows, so it can't be written to" if negated
-
-      source
-    end
-
-    # The columns in square brackets and the value assigned to them:
-    #   Posts(id: 1)[:title] = 'New'                  # One column takes a value.
-    #   Posts(id: 1)[:title, :body] = ['New', '...']  # Several columns take an array of as many values.
-    #   Posts(id: 1)[] = { title: 'New' }             # Empty brackets take a hash of columns and values.
-    def assignments(columns:, value:)
-      check_columns!(columns:)
-      return assigned_hash(value:) if columns.empty?
-      return { columns.first => value } if columns.one?
-      return columns.zip(value).to_h if value.is_a?(Array) && value.length == columns.length
-
-      raise ArgumentError, "#{columns.length} columns take #{columns.length} values, e.g. Posts(id: 1)[:title, :body] = ['New', '...']"
+    def check_negated!
+      raise ArgumentError, "~#{LowData.constant_name(table)} filters by related rows, so it can't select columns" if negated
     end
 
-    def assigned_hash(value:)
-      return value if value.is_a?(Hash) && value.any?
-
-      raise ArgumentError, "Empty brackets take a hash of columns and values, e.g. Posts(id: 1)[] = { title: 'New' }"
+    def with(filter: @filter, negated: @negated)
+      self.class.new(table:, inverted: @inverted, filter:, negated:)
     end
 
     def related(key:, reference:, count: nil)
@@ -132,6 +113,7 @@ class LowData
 
     # Returns the named nested tables and the renamed columns.
     def named(keywords:, columns:)
+      keywords = keywords.transform_values { |value| TableReference.expression(value) }
       named, others = keywords.partition { |_key, value| value.is_a?(DataExpression) }
       renames, filters = others.partition { |_key, value| value.is_a?(Symbol) }
       raise ArgumentError, format(FILTER_KEYWORD_MESSAGE, keywords: filters.to_h) if filters.any?
@@ -150,6 +132,8 @@ class LowData
     end
 
     def inverted(arguments:, keywords:)
+      raise ArgumentError, BARE_TABLE_MESSAGE if arguments.empty? && keywords.empty?
+
       check_columns!(columns: arguments)
       raise ArgumentError, 'Table[] takes column names only, and renames such as headline: :title' unless keywords.values.all?(Symbol)
 

data/lib/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class LowData
-  VERSION = '0.2.0'
+  VERSION = '0.3.0'
 end

data/lib/write_checks.rb

@@ -50,6 +50,19 @@ class LowData
       raise ArgumentError, "Choose the #{source.table} to #{action} with round brackets, e.g. #{example}"
     end
 
+    # MySQL's ON DUPLICATE KEY UPDATE matches any unique key, so the upsert must match on one, and the row mustn't set
+    # every column of another, which could match a different row. An auto-increment id left out of the row can't match.
+    def check_mysql_keys!(table:, keys:, row:, target:)
+      matched, others = keys.partition { |key| key.sort == target.sort }
+      raise Error, "MySQL upserts match on a unique key, and #{target.join(', ')} isn't one of #{table}'s" if matched.empty?
+
+      clashing = others.find { |key| key.none? { |column| row[column].nil? } }
+      return unless clashing
+
+      raise Error, "MySQL matches an upsert on any unique key, and the row also sets #{clashing.join(', ')}, which could match " \
+                   "another #{table} row. Leave #{clashing.join(', ')} out of the row, or match on it"
+    end
+
     # Checked before the write, so a typo doesn't write a row and then fail to return it.
     def check_returned!(source:, columns:)
       missing = (source.columns + source.renames.values) - columns

data/lib/writer.rb

@@ -23,6 +23,8 @@ class LowData
     def insert(source:, rows:)
       check_rows!(rows:, operator: '<<')
       check_insert_filter!(filter: source.filter)
+      check_returned!(source:, columns: @schema.columns(table: source.table))
+      return insert_all(source:, rows:) if source.no_columns? && rows.is_a?(Array) && rows.map(&:keys).uniq.one?
 
       each_row(rows:) { |row| insert_row(source:, row:) }
     end
@@ -31,6 +33,7 @@ class LowData
     def upsert(source:, rows:)
       check_rows!(rows:, operator: '<=')
       check_upsert_filter!(filter: source.filter)
+      check_returned!(source:, columns: @schema.columns(table: source.table))
 
       each_row(rows:) { |row| upsert_row(source:, row: source.filter.values.merge(row)) }
     end
@@ -56,9 +59,17 @@ class LowData
       @database.transaction { rows.map(&) }
     end
 
+    # Empty brackets return nothing, so rows with the same columns go in one INSERT, as nothing needs matching back to
+    # them. Otherwise rows insert one by one, because RETURNING doesn't promise the inserted order, and a multi-row
+    # INSERT takes its columns from the first row, so a column missing from it would be dropped.
+    def insert_all(source:, rows:)
+      @database[source.table].multi_insert(rows)
+      rows.map { {} }
+    end
+
     def insert_row(source:, row:)
       dataset = @database[source.table]
-      return dataset.returning(*returned(source:)).insert(row).first if dataset.supports_returning?(:insert)
+      return dataset.returning(*returned(source:)).insert(row).first if returning?(dataset:, source:)
 
       id = dataset.insert(row)
       read_back(source:, keys: inserted_keys(table: source.table, row:, id:))
@@ -72,18 +83,14 @@ class LowData
       raise Error, "LowData can't upsert on #{@database.database_type}" unless dataset.respond_to?(:insert_conflict)
 
       dataset = dataset.insert_conflict(target:, update: updates(row:, target:))
-      return dataset.returning(*returned(source:)).insert(row).first if dataset.supports_returning?(:insert)
+      return dataset.returning(*returned(source:)).insert(row).first if returning?(dataset:, source:)
 
       dataset.insert(row)
       read_back(source:, keys: row.slice(*target))
     end
 
-    # MySQL's ON DUPLICATE KEY UPDATE matches any unique key, so the named columns must be the table's only one.
     def mysql_upsert(source:, row:, target:)
-      unless unique_keys(table: source.table).map(&:sort) == [target.sort]
-        raise Error, "MySQL matches an upsert on any unique key, so #{target.join(', ')} must be #{source.table}'s only unique key"
-      end
-
+      check_mysql_keys!(table: source.table, keys: unique_keys(table: source.table), row:, target:)
       @database[source.table].on_duplicate_key_update(*updates(row:, target:).keys).insert(row)
       read_back(source:, keys: row.slice(*target))
     end
@@ -115,15 +122,20 @@ class LowData
     def returned(source:)
       return @schema.primary_key(table: source.table) if source.every_column?
 
-      check_returned!(source:, columns: @schema.columns(table: source.table))
       source.columns + source.renames.map { |name, column| Sequel.as(column, name) }
     end
 
-    # Databases without RETURNING read the row back by its keys.
+    # Empty brackets return no columns, and databases without RETURNING read the row back by its keys.
     def read_back(source:, keys:)
+      return {} if source.no_columns?
+
       @database[source.table].where(keys).select(*returned(source:)).first
     end
 
+    def returning?(dataset:, source:)
+      dataset.supports_returning?(:insert) && !source.no_columns?
+    end
+
     def inserted_keys(table:, row:, id:)
       primary_key = @schema.primary_key(table:)
       return row if primary_key.empty?

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lowdata
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - maedi
@@ -61,8 +61,9 @@ files:
 - config/rubocop.yml
 - lib/col.rb
 - lib/data_expression.rb
+- lib/data_expression/source.rb
+- lib/data_expression/writes.rb
 - lib/errors.rb
-- lib/expression_writes.rb
 - lib/filter_compiler.rb
 - lib/inversion.rb
 - lib/lowdata.rb
@@ -75,6 +76,7 @@ files:
 - lib/rows.rb
 - lib/schema.rb
 - lib/table_reference.rb
+- lib/table_reference/writes.rb
 - lib/version.rb
 - lib/write_checks.rb
 - lib/writer.rb