diamond-orm 0.1.0

data/lib/diamond/compiler/dql.rb

@@ -0,0 +1,390 @@
+module Diamond
+  module Compiler
+    module DQL
+      JOIN_TYPE_MAP = {
+        inner: 'INNER JOIN',
+        left:  'LEFT OUTER JOIN',
+        right: 'RIGHT OUTER JOIN',
+        full:  'FULL OUTER JOIN'
+      }.freeze
+
+      def self.compile(table, ast, params = [])
+        # a top-level union renders on its own path: the two sides
+        # compile recursively, params concatenate in order. terminal —
+        # any companion clauses mean someone chained after a union.
+        if (union_node = ast.find { |n| n.is_a?(AST::Union) })
+          if ast.size != 1
+            raise ArgumentError, "union() terminates the chain — chaining after a union isn't supported"
+          end
+          return compile_union(union_node, params)
+        end
+
+        # one loop over ast instead of ~8 selects. bucket everything, render after.
+        with_clauses = []
+        projection   = nil
+        joins        = []
+        wheres       = []
+        from_node    = nil
+        order_specs  = []
+        limit_node   = nil
+        offset_node  = nil
+        group_by_node = nil
+        having_node  = nil
+        distinct     = false
+        ast.each do |n|
+          case n
+          when AST::With       then with_clauses << n
+          when AST::Projection then projection ||= n
+          when AST::Join       then joins << n
+          when AST::Where      then wheres << n
+          when AST::From       then from_node ||= n
+          when AST::Order      then order_specs.concat(n.specs)
+          when AST::Limit      then limit_node = n
+          when AST::Offset     then offset_node = n
+          when AST::GroupBy    then group_by_node = n
+          when AST::Having     then having_node = n
+          when AST::Distinct   then distinct = true
+          end
+        end
+
+        from_target = from_node ? from_node.name : table.name
+        Diamond.validate_ident!(from_target, "FROM target")
+
+        # if any join is eager, we need aliased columns + a transform spec
+        # so the result rows can be deduplicated and nested.
+        has_eager = joins.any?(&:eager)
+        if has_eager
+          return compile_eager(table, from_target, projection, joins, wheres, order_specs,
+                               with_clauses, limit_node, offset_node,
+                               group_by_node, having_node, distinct, params)
+        end
+
+        with_sql    = render_with(with_clauses, params)
+        select_sql  = render_projection(projection, params)
+        from_sql    = "FROM #{from_target}"
+        joins_sql   = joins.map { |j| render_join(j, from_target) }.join(' ')
+        where_sql   = wheres.empty? ? '' : ' WHERE ' + wheres.map { |w| translate_node(w.condition, params) }.join(' AND ')
+        group_sql   = group_by_node ? " GROUP BY #{group_by_node.columns.map { |c| column_sql(c) }.join(', ')}" : ''
+        having_sql  = having_node ? ' HAVING ' + translate_node(having_node.condition, params) : ''
+
+        # specs already merged up top. one ORDER BY out.
+        order_sql   = order_specs.empty? ? '' : ' ORDER BY ' + order_specs.map { |col, dir| "#{column_sql(col)} #{dir.to_s.upcase}" }.join(', ')
+
+        # last Limit/Offset node wins. values go in raw, not bound -
+        # _build_limit/_build_offset already checked Integer >= 0, and
+        # old sqlite builds choke on (or misplan) bound LIMIT ?.
+        limit_sql   = limit_node ? " LIMIT #{limit_node.value}" : ''
+
+        offset_sql  = offset_node ? " OFFSET #{offset_node.value}" : ''
+
+        distinct_sql = distinct ? 'DISTINCT ' : ''
+        sql = "#{with_sql} SELECT #{distinct_sql}#{select_sql} #{from_sql}#{joins_sql.empty? ? '' : ' ' + joins_sql}#{where_sql}#{group_sql}#{having_sql}#{order_sql}#{limit_sql}#{offset_sql}"
+        sql = sql.strip
+        [sql, params, nil]
+      end
+
+      # `(left) UNION ALL (right)`. sides compile through the normal
+      # path so nesting works; each side's params append in order.
+      def self.compile_union(node, params)
+        [node.left, node.right].each do |side|
+          if side.ast.any? { |n| n.is_a?(AST::Join) && n.eager }
+            raise ArgumentError, "union() over eager loads isn't supported"
+          end
+        end
+        lsql, _ = Diamond::Compiler::Base.compile(node.left.table, node.left.ast, params)
+        rsql, _ = Diamond::Compiler::Base.compile(node.right.table, node.right.ast, params)
+        ["#{lsql} UNION ALL #{rsql}", params, nil]
+      end
+
+      # eager-loading path: build a SELECT with aliased columns (table.col AS
+      # "table.col") so the Extralite::Transform can disambiguate which table
+      # a column belongs to, then return the transform spec alongside SQL.
+      def self.compile_eager(table, from_target, projection, joins, wheres, order_specs, with_clauses, limit_node, offset_node, group_by_node, having_node, distinct, params)
+        # 1. column list: parent cols (with optional projection) + aliased
+        #    columns from each eager join
+        parent_cols = if projection
+                        projection.columns.map { |c| member_column(c) }.compact
+                      else
+                        table.schema[:columns]
+                      end
+
+        select_parts = []
+        # parent: bare column names. Extralite returns them as keys like
+        # "id", "name", etc. The transform spec keys must match these.
+        parent_cols.each do |col|
+          select_parts << "#{from_target}.#{col}"
+        end
+        # children: alias each column as "table.col" so the transform can
+        # tell parent columns from child columns with the same name (e.g.
+        # both tables have an "id" column).
+        joins.each do |j|
+          next unless j.eager
+          child_table = j.table_name
+          child_schema = Diamond.engine.schema_cache[child_table]
+          child_schema[:columns].each do |col|
+            select_parts << "#{child_table}.#{col} AS \"#{child_table}.#{col}\""
+          end
+        end
+        select_sql = select_parts.join(', ')
+
+        # 2. JOIN clauses. eager joins get rewritten to LEFT OUTER JOIN so
+        #    parents without children still appear.
+        render_join_eager = ->(j) {
+          sql_type = (j.eager ? 'LEFT OUTER JOIN' : JOIN_TYPE_MAP[j.type])
+          Diamond.validate_ident!(j.table_name, "join table")
+          on_clauses = render_on_clauses(j.on, from_target, j.table_name)
+          "#{sql_type} #{j.table_name} ON #{on_clauses.join(' AND ')}"
+        }
+        joins_sql = joins.map { |j| render_join_eager.call(j) }.join(' ')
+
+        # 3. WHERE, GROUP BY, HAVING, ORDER BY, LIMIT, OFFSET. when the query
+        #    is eager, qualify bare column names in WHERE/HAVING with the
+        #    parent table name so they don't collide with child table columns.
+        where_sql = if wheres.empty?
+                      ''
+                    else
+                      prefix = "#{from_target}."
+                      ' WHERE ' + wheres.map { |w| translate_where_qualified(w.condition, params, prefix) }.join(' AND ')
+                    end
+        group_sql = group_by_node ? " GROUP BY #{group_by_node.columns.map { |c| column_sql(c, "#{from_target}.") }.join(', ')}" : ''
+        having_sql = having_node ? ' HAVING ' + translate_where_qualified(having_node.condition, params, "#{from_target}.") : ''
+        order_sql  = order_specs.empty? ? '' : ' ORDER BY ' + order_specs.map { |col, dir| "#{column_sql(col, "#{from_target}.")} #{dir.to_s.upcase}" }.join(', ')
+        limit_sql  = limit_node ? " LIMIT #{limit_node.value}" : ''
+        offset_sql = offset_node ? " OFFSET #{offset_node.value}" : ''
+
+        with_sql = render_with(with_clauses, params)
+        distinct_sql = distinct ? 'DISTINCT ' : ''
+        sql = "#{with_sql} SELECT #{distinct_sql}#{select_sql} FROM #{from_target}#{joins_sql.empty? ? '' : ' ' + joins_sql}#{where_sql}#{group_sql}#{having_sql}#{order_sql}#{limit_sql}#{offset_sql}".strip
+
+        # 4. build the transform spec
+        transform = build_transform(from_target, table, parent_cols, joins)
+
+        [sql, params, transform]
+      end
+
+      # AST column -> underlying column name (only Column nodes; ignore
+      # Function/WindowFunction in eager mode for now).
+      def self.member_column(node)
+        case node
+        when AST::Column then node.name
+        end
+      end
+
+      def self.build_transform(from_target, table, parent_cols, joins)
+        # build a hash describing the expected row layout. The Extralite
+        # transform expects the spec wrapped in { columns: { ... } } and
+        # uses each spec key as the lookup key against the result set's
+        # column name. We alias child columns as "table.col" so the
+        # transform can disambiguate when parent and child share column
+        # names like "id".
+        eager_joins = joins.select(&:eager)
+        columns_spec = {}
+
+        parent_cols.each do |col|
+          type = type_for_column(from_target, col)
+          columns_spec[col.to_s] = { type: type }
+        end
+
+        eager_joins.each do |j|
+          child_table = j.table_name
+          child_schema = Diamond.engine.schema_cache[child_table]
+          child_columns = {}
+          child_schema[:columns].each do |col|
+            type = type_for_column(child_table, col)
+            child_columns["#{child_table}.#{col}"] = { type: type }
+          end
+          # mark primary key for dedup
+          pk = child_schema[:primary_key]
+          child_columns["#{child_table}.#{pk}"][:identity] = true if pk
+
+          # use :as alias as struct member name if provided, else table name
+          member_key = (j.as || child_table).to_s
+
+          if j.single
+            # single object (to-one): Hash with type: :relation (not Array)
+            columns_spec[member_key] = {
+              type: :relation,
+              columns: child_columns
+            }
+          else
+            # collection (to-many): Array of Hash
+            columns_spec[member_key] = [{
+              type: :relation,
+              columns: child_columns
+            }]
+          end
+        end
+
+        # parent primary key for dedup at the parent level
+        pk = table.schema[:primary_key]
+        columns_spec[pk.to_s][:identity] = true if pk
+
+        { columns: columns_spec }
+      end
+
+      def self.type_for_column(table, column)
+        # map sqlite type strings (INTEGER, TEXT, REAL) to extralite
+        # transform types. default to text for unknown types.
+        type_str = Diamond.engine.schema_cache[table][:types][column]
+        case type_str
+        when 'INTEGER' then :integer
+        when 'REAL'    then :float
+        else :text
+        end
+      end
+
+      # Kept for the eager path; now a thin wrapper around translate_node
+      # with the parent-table prefix so unqualified Column references don't
+      # collide with child-table columns.
+      def self.translate_where_qualified(node, params, prefix)
+        translate_node(node, params, prefix: prefix)
+      end
+
+      def self.render_with(with_nodes, params)
+        return '' if with_nodes.empty?
+        pieces = with_nodes.map { |w| render_single_with(w, params) }
+        'WITH ' + pieces.join(', ')
+      end
+
+      def self.render_single_with(node, params)
+        rec = node.recursive ? 'RECURSIVE ' : ''
+        sub_sql = render_with_query(node.query, params)
+        "#{rec}#{node.name} AS (#{sub_sql})"
+      end
+
+      def self.render_with_query(query, params)
+        if query.is_a?(AST::Union)
+          left_sql  = render_with_query(query.left, params)
+          right_sql = render_with_query(query.right, params)
+          "#{left_sql} #{query.operator} #{right_sql}"
+        else
+          sub_sql, _ = Diamond::Compiler::Base.compile(query.table, query.ast, params)
+          sub_sql
+        end
+      end
+
+      def self.render_projection(node, params)
+        return '*' if node.nil?
+        node.columns.map { |c| translate_node(c, params) }.join(', ')
+      end
+
+      # order/group entries are bare Symbols or qualified Columns.
+      # qualified columns render with their own table; bare ones take
+      # the caller's prefix (parent table in eager mode, none otherwise).
+      def self.column_sql(col, prefix = '')
+        col.is_a?(AST::Column) && col.table ? "#{col.table}.#{col.name}" : "#{prefix}#{col}"
+      end
+
+      def self.render_join(node, current_table)
+        Diamond.validate_ident!(node.table_name, "join table")
+        sql_type = JOIN_TYPE_MAP[node.type] || raise(ArgumentError, "Unknown join type: #{node.type}")
+        on_clauses = render_on_clauses(node.on, current_table, node.table_name)
+        "#{sql_type} #{node.table_name} ON #{on_clauses.join(' AND ')}"
+      end
+
+      # Convention for the `on` hash (consumed from `_resolve_join_keys`
+      # and explicit `join(table, on:)` calls): `{ <joined_local> =>
+      # <current_ref> }`. Emit `<joined>.<local> = <current>.<ref>`.
+      # The schema-membership check below is a guard, not a side-decider
+      # — it catches a typo in `on:` early instead of letting SQLite
+      # raise an obscure "no such column" error at run time.
+      def self.render_on_clauses(on_hash, current_table, joined_table)
+        schema_cache = Diamond.engine.schema_cache
+        current_schema = schema_cache[current_table]
+        joined_schema  = schema_cache[joined_table]
+        on_hash.map do |local, ref|
+          if current_schema && joined_schema
+            current_cols = current_schema[:columns]
+            joined_cols  = joined_schema[:columns]
+            unless joined_cols.include?(local.to_sym)
+              raise ArgumentError,
+                    "JOIN ON column '#{local}' not found on #{joined_table}; " \
+                    "pass `on:` with a column that exists on the joined table"
+            end
+            unless current_cols.include?(ref.to_sym)
+              raise ArgumentError,
+                    "JOIN ON column '#{ref}' not found on #{current_table}; " \
+                    "pass `on:` with a column that exists on the current table"
+            end
+          end
+          "#{joined_table}.#{local} = #{current_table}.#{ref}"
+        end
+      end
+
+      def self.translate_node(node, params, prefix: '')
+        hook = Operators.call(node, params)
+        return hook if hook
+        case node
+        when Symbol
+          node.to_s
+        when AST::Column
+          # already qualified (`tags.tag`) wins over the eager prefix.
+          node.table ? "#{node.table}.#{node.name}" : "#{prefix}#{node.name}"
+        when AST::Literal
+          params << node.value
+          '?'
+        when AST::Subquery
+          sub_sql, _ = Diamond::Compiler::Base.compile(node.query.table, node.query.ast, params)
+          "(#{sub_sql})"
+        when AST::Not
+          "NOT (#{translate_node(node.condition, params, prefix: prefix)})"
+        when AST::IsNull
+          "#{translate_node(node.column, params, prefix: prefix)} IS NULL"
+        when AST::IsNotNull
+          "#{translate_node(node.column, params, prefix: prefix)} IS NOT NULL"
+        when AST::Between
+          col_sql = translate_node(node.column, params, prefix: prefix)
+          low_sql = translate_node(node.low, params, prefix: prefix)
+          high_sql = translate_node(node.high, params, prefix: prefix)
+          "#{col_sql} BETWEEN #{low_sql} AND #{high_sql}"
+        when AST::Function
+          args_str = node.args.map { |a| translate_node(a, params, prefix: prefix) }.join(', ')
+          "#{node.name}(#{args_str})"
+        when AST::WindowFunction
+          args_str = node.args.map { |a| translate_node(a, params, prefix: prefix) }.join(', ')
+          func_str = "#{node.func_name}(#{args_str})"
+          parts = []
+          parts << "PARTITION BY #{node.partition_by.join(', ')}" unless node.partition_by.empty?
+          parts << "ORDER BY #{node.order_by.join(', ')}" unless node.order_by.empty?
+          if parts.empty?
+            func_str
+          else
+            "#{func_str} OVER (#{parts.join(' ')})"
+          end
+        when AST::BinaryOp
+          left  = translate_node(node.left, params, prefix: prefix)
+          right = translate_node(node.right, params, prefix: prefix)
+          if [:AND, :OR].include?(node.operator)
+            "(#{left} #{node.operator} #{right})"
+          else
+            "#{left} #{node.operator} #{right}"
+          end
+        when AST::In, AST::NotIn
+          # subquery form: `col IN (SELECT ...)`
+          if node.right.is_a?(AST::Subquery)
+            left_sql  = translate_node(node.left, params, prefix: prefix)
+            right_sql = translate_node(node.right, params, prefix: prefix)
+            kw = node.is_a?(AST::NotIn) ? 'NOT IN' : 'IN'
+            return "#{left_sql} #{kw} #{right_sql}"
+          end
+          # no `IN ()` in sql, so empty means `1=0`, empty NOT IN means `1=1`.
+          if node.right.empty?
+            return node.is_a?(AST::NotIn) ? '1=1' : '1=0'
+          end
+          # Elements may be expressions, not just Literals. no `?` then.
+          element_sqls = node.right.map { |r| translate_node(r, params, prefix: prefix) }
+          kw = node.is_a?(AST::NotIn) ? 'NOT IN' : 'IN'
+          left_sql = translate_node(node.left, [], prefix: prefix)
+          # sqlite caps bound vars per statement, so slice big lists into
+          # 500s. IN groups get OR, NOT IN groups get AND (de morgan).
+          groups = element_sqls.each_slice(500).map { |g| "#{left_sql} #{kw} (#{g.join(', ')})" }
+          return groups.first if groups.size == 1
+          joiner = node.is_a?(AST::NotIn) ? ' AND ' : ' OR '
+          "(#{groups.join(joiner)})"
+        else
+          raise "Unknown AST Node: #{node.class}"
+        end
+      end
+    end
+  end
+end

data/lib/diamond/compiler/registry.rb

@@ -0,0 +1,45 @@
+module Diamond
+  module Compiler
+    # Registry consulted at the front of DQL.translate_node. Operators declare
+    # which AST nodes they handle via .handles?, then render to SQL fragments.
+    # The render method is expected to mutate the params array (matches the
+    # convention used by the built-in case statement).
+    #
+    # Per-Ractor: each Ractor owns its own handler list, stored on the
+    # Ractor's local storage. The module holds only the frozen list of
+    # built-ins (which is shareable).
+    module Operators
+      STORAGE_KEY = Diamond::RACTOR_KEYS[:compiler_ops]
+
+      # method, not a constant: this file loads before the Like operator
+      # is defined, so it must resolve lazily. called once per Ractor
+      # (handlers memoizes), so the per-call allocation is irrelevant.
+      def self.builtins
+        [Diamond::Operators::Like].freeze
+      end
+
+      def self.handlers
+        Ractor.current[STORAGE_KEY] ||= builtins.dup
+      end
+
+      def self.register(operator)
+        list = handlers
+        list << operator unless list.include?(operator)
+        nil
+      end
+
+      def self.clear!
+        Ractor.current[STORAGE_KEY] = builtins.dup
+      end
+
+      def self.call(node, params)
+        handlers.sort_by { |h| -h.priority }.each do |h|
+          if h.handles?(node)
+            return h.render(node, params)
+          end
+        end
+        nil
+      end
+    end
+  end
+end

data/lib/diamond/cursor.rb

@@ -0,0 +1,52 @@
+module Diamond
+  # streams rows out of a prepared Extralite statement, one frozen struct at a time.
+  #
+  # statement gets closed by `ensure` when iteration completes (or breaks, or
+  # raises), plus a GC finalizer for cursors dropped on the floor. the
+  # finalizer is built by ::make_finalizer so it never closes over the cursor
+  # itself. rows arrive as arrays (positions match the SELECT order), avoiding
+  # hash allocation per row.
+  class Cursor
+    include Enumerable
+
+    def self.make_finalizer(stmt)
+      ->(_id) {
+        begin
+          stmt.close unless stmt.closed?
+        rescue StandardError
+          # best effort - finalizers must not raise
+        end
+      }
+    end
+
+    def initialize(table, stmt, projected_columns)
+      @table = table
+      @stmt = stmt
+      @projected_columns = projected_columns
+      # Pre-resolve the struct class once: per-row work stays at
+      # splat + new + freeze (see StructFactory.bulk path).
+      @factory = Diamond::StructFactory.factory_for(table, projected_columns)
+
+      ObjectSpace.define_finalizer(self, self.class.make_finalizer(@stmt))
+    end
+
+    def each(&block)
+      return enum_for(:each) unless block
+      begin
+        @stmt.each do |row|
+          if row.is_a?(Hash)
+            yield Diamond::StructFactory.create(@table, row, @projected_columns)
+          else
+            yield Diamond::StructFactory.build(@factory, row)
+          end
+        end
+      ensure
+        begin
+          @stmt.close unless @stmt.closed?
+        rescue StandardError
+          # ensure must not raise
+        end
+      end
+    end
+  end
+end

data/lib/diamond/domains/cte.rb

@@ -0,0 +1,25 @@
+module Diamond
+  module Domains
+    module CTE
+      def with(cte_hash, &block)
+        raise ArgumentError, "Diamond.with requires a block" unless block_given?
+
+        cte_nodes = cte_hash.map { |alias_name, query| AST::With.new(alias_name, query) }
+
+        proxy = Object.new
+        proxy.define_singleton_method(:from) do |alias_name|
+          QueryObject.new(NullTable.new(alias_name), [AST::From.new(alias_name)])
+        end
+
+        main_query = yield(proxy)
+        QueryObject.new(main_query.table, cte_nodes + main_query.ast)
+      end
+
+      def with_recursive(name, base_query, recursive_query)
+        union_node = AST::Union.new(base_query, recursive_query)
+        dummy_table = NullTable.new(name)
+        QueryObject.new(dummy_table, [AST::With.new(name, union_node, recursive: true)])
+      end
+    end
+  end
+end

data/lib/diamond/domains/ddl.rb

@@ -0,0 +1,11 @@
+module Diamond
+  module Domains
+    module DDL
+      def _build_relation(name, &block)
+        raise ArgumentError, "define_relation requires a block" unless block
+        columns = Diamond::Parser.parse_ddl(block)
+        AST::DefineRelation.new(name, columns)
+      end
+    end
+  end
+end

data/lib/diamond/domains/dml.rb

@@ -0,0 +1,106 @@
+module Diamond
+  module Domains
+    module DML
+      # returning: :id (single Symbol) returns a scalar for single-row
+      # create. returning: [:id, :name] (Array) returns an Array of
+      # structs (even for create's 1-row case, for consistency with
+      # update/delete). Empty returning returns the created row.
+      def _build_create(hash, returning: [])
+        single = returning.is_a?(Symbol) || returning.is_a?(String)
+        cols = Array(returning)
+        ast = AST::Insert.new(hash)
+        result = Diamond::Compiler::DML.compile_insert(_current_table, ast, returning: cols)
+        if cols.empty?
+          _current_table.find(result).first
+        elsif single
+          result.first[cols.first.to_sym]
+        else
+          # Array form: always return Array of Structs for consistency
+          # with multi-row DML (update/delete).
+          result.map { |row| Diamond::StructFactory.create_from_returning(_current_table, row, cols) }
+        end
+      end
+
+      def _build_update(returning: [], &block)
+        raise ArgumentError, "update requires a block" unless block_given?
+        single = returning.is_a?(Symbol) || returning.is_a?(String)
+        cols = Array(returning)
+        hash = Diamond::Parser.parse_update(block, _schema_for_dsl)
+        wheres = _where_nodes
+        result = Diamond::Compiler::DML.compile_update(_current_table, hash, wheres, returning: cols)
+        if cols.empty?
+          result  # row count
+        elsif single
+          col = cols.first.to_sym
+          result.map { |row| row[col] }
+        else
+          result.map { |row| Diamond::StructFactory.create_from_returning(_current_table, row, cols) }
+        end
+      end
+
+      def _build_delete(returning: [])
+        single = returning.is_a?(Symbol) || returning.is_a?(String)
+        cols = Array(returning)
+        wheres = _where_nodes
+        result = Diamond::Compiler::DML.compile_delete(_current_table, wheres, returning: cols)
+        if cols.empty?
+          result  # row count
+        elsif single
+          col = cols.first.to_sym
+          result.map { |row| row[col] }
+        else
+          result.map { |row| Diamond::StructFactory.create_from_returning(_current_table, row, cols) }
+        end
+      end
+
+      # Phase 7: bulk insert. Records is an Enumerable of Hashes. Returns
+      # the number of rows inserted. Single SQL statement + C-level loop
+      # = dramatically faster than N individual inserts.
+      #
+      # Note: does not support `returning:` — batch_execute (Extralite's
+      # C-level bulk path) doesn't expose RETURNING rows. Use individual
+      # .create() calls with returning if you need the inserted values.
+      def batch_create(records)
+        records = Array(records)
+        return 0 if records.empty?
+        first = records.first
+        cols = first.keys
+        placeholders = "(#{(['?'] * cols.size).join(', ')})"
+        sql = "INSERT INTO #{_current_table.name} (#{cols.join(', ')}) VALUES #{placeholders}"
+        Diamond.engine.db.batch_execute(sql, records.map { |r| r.values })
+      end
+
+      alias insert_all batch_create
+
+      # Phase 7: bulk update with optional RETURNING. Reuses the WHERE
+      # nodes already on the chain; applies the set_hash; returns the row
+      # count, a flat array of values (single Symbol returning), or an
+      # array of structs (Array returning).
+      def batch_update(set_hash, returning: [])
+        single = returning.is_a?(Symbol) || returning.is_a?(String)
+        cols = Array(returning)
+        wheres = _where_nodes
+        result = Diamond::Compiler::DML.compile_update(_current_table, set_hash, wheres, returning: cols)
+        if cols.empty?
+          result
+        elsif single
+          col = cols.first.to_sym
+          result.map { |row| row[col] }
+        else
+          result.map { |row| Diamond::StructFactory.create_from_returning(_current_table, row, cols) }
+        end
+      end
+
+      private
+
+      def _current_table
+        is_a?(Diamond::Table) ? self : @table
+      end
+
+      def _where_nodes
+        return [] unless self.is_a?(Diamond::QueryObject)
+        @ast.select { |n| n.is_a?(AST::Where) }
+      end
+    end
+  end
+end