pglpg 0.1.0 → 0.3.0

data/lib/pglpg/model/relation.rb

@@ -0,0 +1,334 @@
+# frozen_string_literal: true
+
+module Pglpg
+  module Model
+    # A query over one model's elements as seen through a Context, built
+    # immutably from Model.in. It compiles to a Pglpg::Query, so the
+    # visibility policy, deterministic ordering, max_rows and the statement
+    # timeout all apply as they do there.
+    #
+    #   Person.in(ctx).where(rank: Pglpg.gte(2)).order(name: :desc).limit(20)
+    class Relation
+      include Enumerable
+
+      attr_reader :model, :context
+
+      def initialize(model, context, query = nil, filtered: false)
+        @model = model
+        @context = context
+        @query = query || model.pattern(context)
+        @filtered = filtered
+        @shaped = false
+        @preload = {}.freeze
+        freeze
+      end
+
+      # Structured conditions on the model's properties, as in Query#where.
+      def where(**props) = derive(@query.where(var => props))
+
+      # order(:name), order(name: :desc) or order(:rank, name: :desc). Ties are
+      # broken by element ids.
+      def order(*names, **spec) = derive(order_query(var, names, spec), shaped: true)
+
+      def limit(n) = derive(@query.limit(n), shaped: true)
+
+      def offset(n) = derive(@query.offset(n), shaped: true)
+
+      def to_a
+        records = rows
+        preload(records, @preload, model) unless @preload.empty?
+        records
+      end
+
+      # Preload symbols/strings and nested hashes (array values, including [],
+      # are allowed). Calls merge; static association/model validation runs
+      # now, before SQL: ArgumentError for invalid trees, ConfigurationError
+      # for missing target models. to_a/each/first preload; count, exists?,
+      # pluck and find do not. Batches above max_rows raise TooManyRows.
+      def with_associations(*spec)
+        tree = merge_tree(@preload, parse_tree(spec, []))
+        validate_tree(model, tree)
+        copy = clone(freeze: false)
+        copy.instance_variable_set(:@preload, tree)
+        copy.freeze
+      end
+
+      def each(&) = to_a.each(&)
+
+      def first(n = nil) = n.nil? ? limit(1).to_a.first : limit(n).to_a
+
+      def count = compiled.count
+
+      def exists? = compiled.exists?
+
+      # The visible element of the model's type behind +ref+ (a Ref or its
+      # String form). Raises RecordNotFound when it is missing or hidden.
+      # Conditions, ordering and pagination do not apply, so find works only
+      # on the unfiltered relation.
+      def find(ref)
+        raise ArgumentError, "find ignores conditions and pagination; use where(...).first" if @filtered
+
+        ref = model.graph.parse_ref(ref) if ref.is_a?(String)
+        model.graph.check_ref!(ref, model.kind)
+        element = context.find(ref)
+        raise RecordNotFound unless element && model.matches?(element)
+
+        model.instantiate(context, element)
+      end
+
+      # The first element matching +props+, or nil.
+      def find_by(**props) = where(**props).first
+
+      # The values of attributes (or :id, :ref) of each element, in order:
+      # one value per element for one name, an Array per element for
+      # several. Elements are chosen first and projected afterwards, so two
+      # elements with equal values give two values (ADR-0010 §5).
+      #   people.order(:name).pluck(:name)        # => ["Ann", "Bob"]
+      #   people.pluck(:id, :name)                # => [[1, "Ann"], [2, "Bob"]]
+      def pluck(*names)
+        names = pluck_names!(model, names)
+        raise ArgumentError, "pluck needs at least one name" if names.empty?
+
+        rows.map { |record| unwrap(project(record, names)) }
+      end
+
+      # A new record bound to the relation's context.
+      def new(**attributes) = model.build(context, attributes)
+
+      alias build new
+
+      # Builds and saves a record; returns it, saved or not (check
+      # persisted? or errors).
+      def create(writer: nil, **attributes)
+        context.writable!
+        new(**attributes).tap { _1.save(writer:) }
+      end
+
+      # As #create, but raises RecordInvalid when validation fails.
+      def create!(writer: nil, **attributes)
+        context.writable!
+        new(**attributes).tap { _1.save!(writer:) }
+      end
+
+      # The compiled Pglpg::Query, for debugging (to_sql, explain).
+      def to_query = compiled
+
+      def inspect = "#<#{self.class.name} #{model.name || model.base_class.name} #{compiled.to_sql.first}>"
+
+      private
+
+      def rows = compiled.to_a.map { |row| load_row(row) }
+
+      def parse_tree(spec, ancestors)
+        raise ArgumentError, "cyclic preload tree" if ancestors.include?(spec.object_id)
+        ancestors = ancestors + [spec.object_id]
+        result = {}
+        spec.each do |item|
+          case item
+          when Symbol, String
+            key = item.to_sym
+            result[key] ||= {}.freeze
+          when Hash
+            raise ArgumentError, "cyclic preload tree" if ancestors.include?(item.object_id)
+            item.each do |key, value|
+              raise ArgumentError, "invalid association name" unless key.is_a?(Symbol) || key.is_a?(String)
+              children = value.is_a?(Array) ? value : [value]
+              result[key.to_sym] = merge_tree(result[key.to_sym] || {}, parse_tree(children, ancestors + [item.object_id]))
+            end
+          else
+            raise ArgumentError, "invalid preload specification"
+          end
+        end
+        result.freeze
+      end
+
+      def merge_tree(a, b)
+        a.merge(b) { |_key, left, right| merge_tree(left, right) }.freeze
+      end
+
+      def target_model(owner_model, association)
+        owner_model.association_model(association)
+      end
+
+      def validate_tree(owner_model, tree)
+        tree.each do |name, children|
+          association = owner_model.respond_to?(:associations) && owner_model.associations[name]
+          raise ArgumentError, "#{owner_model} has no association #{name}" unless association
+          context.temporal_mode!([context.graph.type.edge_type!(association.edge_type)])
+          validate_tree(target_model(owner_model, association), children)
+        end
+      end
+
+      def preload(owners, tree, owner_model)
+        return if owners.empty?
+        tree.each do |name, children|
+          association = owner_model.associations.fetch(name)
+          target = target_model(owner_model, association)
+          query = context.match.node_refs(:owner, owners.map(&:ref))
+          query = query.public_send(association.direction, association.edge_type, :n,
+                                    association.label || target.schema_type.name, edge: :e)
+          begin
+            pairs = query.return(:owner, :n).distinct.to_a
+          rescue TooManyRows
+            raise TooManyRows, "#{owner_model}##{name}: more than #{Pglpg.configuration.max_rows} distinct owner-target pairs; page the owners"
+          end
+          targets = {}
+          grouped = Hash.new { |h, k| h[k] = [] }
+          pairs.each do |row|
+            element = row.fetch(:n)
+            record = targets[element.ref] ||= target.instantiate(context, element)
+            grouped[row.fetch(:owner).ref] << record
+          end
+          owners.each do |owner|
+            cache = owner.instance_variable_get(:@association_cache) || {}
+            cache[name] = grouped[owner.ref].freeze
+            owner.instance_variable_set(:@association_cache, cache)
+          end
+          preload(targets.values, children, target)
+        end
+      end
+
+      def var = model.query_var
+
+      # The query that runs.
+      def compiled = @query
+
+      def load_row(row) = model.instantiate(context, row.fetch(var))
+
+      PLUCK_IDENTITY = %i[id ref].freeze
+
+      # Checked before any query runs.
+      def pluck_names!(model, names)
+        names.map(&:to_sym).each do |name|
+          next if PLUCK_IDENTITY.include?(name) || model.attribute_names.include?(name.to_s)
+
+          raise ArgumentError, "#{model.name || model.schema_type.name} has no attribute #{name.inspect} to pluck"
+        end
+      end
+
+      def project(record, names) = names.map { record.public_send(_1) }
+
+      def unwrap(values) = values.size == 1 ? values.first : values
+
+      def order_query(var, names, spec)
+        q = names.reduce(@query) { |acc, name| acc.order(var => name) }
+        spec.empty? ? q : q.order(var => spec)
+      end
+
+      def derived_copy(copy) = copy
+
+      # A copy with +query+; +shaped+ records ordering or pagination.
+      def derive(query, shaped: @shaped)
+        copy = clone(freeze: false)
+        copy.instance_variable_set(:@query, query)
+        derived_copy(copy)
+        copy.instance_variable_set(:@filtered, true)
+        copy.instance_variable_set(:@shaped, shaped)
+        copy.freeze
+      end
+    end
+
+    # The targets of an association (ADR-0010 §5): one row per distinct
+    # visible target, deduplicated before ordering, pagination and counts.
+    # Edge conditions (rel_where) mean "at least one matching visible edge".
+    #
+    #   person.projects.rel_where(role: "lead").order(:title).limit(20)
+    #   person.projects.with_rel.each { |project, works_on| ... }
+    class AssociationRelation < Relation
+      def initialize(model, context, query, edge_model:, cached: nil)
+        @edge_model = edge_model
+        @cached = cached
+        super(model, context, query, filtered: true)
+      end
+
+      def first(n = nil)
+        return super unless @cached
+        return to_a.first if n.nil?
+
+        raise ArgumentError, "limit must be a positive Integer" unless n.is_a?(Integer) && n.positive?
+        max_rows = Pglpg.configuration.max_rows
+        raise ArgumentError, "limit exceeds max_rows (#{max_rows})" if n > max_rows
+        to_a.first(n).freeze
+      end
+
+      def count = @cached ? @cached.size : super
+      def exists? = @cached ? !@cached.empty? : super
+      # Structured conditions on the association's edge properties.
+      def rel_where(**props) = derive(@query.where(e: props))
+
+      # A target has no single edge value when several edges lead to it.
+      def rel_order(*, **)
+        raise ArgumentError, "a target query can't be ordered by an edge property; use with_rel.rel_order"
+      end
+
+      # One row per matching node–edge pair: [target, edge]. Its count,
+      # limit and offset count pairs. Only on a relation without order,
+      # limit or offset, so pagination always applies to the shape it was
+      # written for.
+      def with_rel
+        raise ArgumentError, "with_rel cannot discard pending preloads" unless @preload.empty?
+
+        raise ArgumentError, "call with_rel before order, limit or offset" if @shaped
+
+        BindingRelation.new(model, context, @query, edge_model: @edge_model)
+      end
+
+      # Enumerates with_rel: yields each target with its edge.
+      def each_with_rel(&) = with_rel.each(&)
+
+      # Creating targets or edges through an association is deferred (ADR-0010).
+      def new(**) = raise(ArgumentError, "associations can't build records yet; use Model.in(ctx).new")
+
+      alias build new
+      alias create new
+      alias create! new
+
+      private
+
+      def rows = @cached || super
+
+      def derived_copy(copy)
+        copy.instance_variable_set(:@cached, nil)
+        super
+      end
+
+      def compiled = @query.return(var).distinct
+    end
+
+    # The node–edge pairs of an association, from AssociationRelation#with_rel.
+    class BindingRelation < AssociationRelation
+      # order(...) orders by target properties; rel_order(...) by edge ones.
+      def rel_order(*names, **spec) = derive(order_query(:e, names, spec), shaped: true)
+
+      def with_associations(*) = raise(ArgumentError, "preloading binding relations is not supported")
+
+      def with_rel = self
+
+      # One entry per pair: the target's +names+, then the edge's +rel+ names.
+      #   ann.projects.with_rel.pluck(:title, rel: :role)  # => [["Apollo", "lead"], ...]
+      def pluck(*names, rel: [])
+        rel = Array(rel)
+        names = pluck_names!(model, names)
+        if rel.any?
+          @edge_model or raise ConfigurationError, "no model is registered for the association's edge type"
+          rel = pluck_names!(@edge_model, rel)
+        end
+        raise ArgumentError, "pluck needs at least one name" if names.empty? && rel.empty?
+
+        to_a.map { |target, edge| unwrap(project(target, names) + project(edge, rel)) }
+      end
+
+      def each_with_rel(&) = each(&)
+
+      private
+
+      def compiled = @query.return(var, :e)
+
+      def load_row(row)
+        edge_model = @edge_model or
+          raise ConfigurationError, "no model is registered for edge type #{row.fetch(:e).type}"
+        [model.instantiate(context, row.fetch(var)), edge_model.instantiate(context, row.fetch(:e))]
+      end
+    end
+  end
+end

data/lib/pglpg/model.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "pglpg"
+require "active_model"
+
+module Pglpg
+  # The optional model layer (ADR-0010): ActiveModel classes backed by graph
+  # node and edge types, read through a Context.
+  #
+  #   require "pglpg/model"
+  #
+  #   class Person < Pglpg::Model::Node
+  #     graph Kg, type: :Person
+  #   end
+  #
+  #   people = Person.in(Kg.for(viewer: current_viewer))
+  #   people.where(rank: Pglpg.gte(2)).order(name: :desc).limit(20).to_a
+  #   people.find(ref)
+  module Model
+    # A lookup found no visible element of the model's type. A hidden
+    # element and a missing one look the same.
+    class RecordNotFound < Error
+      def initialize(msg = "record not found")
+        super
+      end
+    end
+
+    @registries = ObjectSpace::WeakKeyMap.new
+    @lock = Mutex.new
+
+    class << self
+      # Registers +klass+ as the model of +type_name+ in +graph+. A class
+      # with the same name replaces an earlier one (code reloading); any
+      # other second model for the same type is a ConfigurationError.
+      def register(graph, kind, type_name, klass)
+        @lock.synchronize do
+          registry = (@registries[graph] ||= {})
+          existing = registry[[kind, type_name]]
+          if existing && !existing.equal?(klass) && (existing.name.nil? || existing.name != klass.name)
+            raise ConfigurationError, "#{type_name} in graph #{graph.name} already has a model (#{existing.inspect})"
+          end
+
+          registry[[kind, type_name]] = klass
+        end
+      end
+
+      # The model registered for +type_name+ in +graph+, or nil.
+      def lookup(graph, kind, type_name)
+        @lock.synchronize { @registries[graph]&.[]([kind, type_name]) }
+      end
+    end
+  end
+end
+
+require_relative "model/base"
+require_relative "model/node"
+require_relative "model/edge"
+require_relative "model/relation"

data/lib/pglpg/query.rb

@@ -17,7 +17,7 @@ module Pglpg
   class Query
     include Enumerable
 
-    NodePattern = Data.define(:var, :label, :ref_id)
+    NodePattern = Data.define(:var, :label, :ref_id, :ref_ids)
     EdgePattern = Data.define(:var, :type, :direction, :from_var, :to_var, :named)
     State = Data.define(:nodes, :edges, :conditions, :returns, :orders, :limit, :offset, :distinct, :last_var)
 
@@ -39,16 +39,31 @@ module Pglpg
       var = new_var!(var)
       label = check_label!(label)
       context.graph.check_ref!(ref, :node) if ref
-      q = with(nodes: { var => NodePattern.new(var:, label:, ref_id: ref&.id) }.freeze, last_var: var)
+      q = with(nodes: { var => NodePattern.new(var:, label:, ref_id: ref&.id, ref_ids: nil) }.freeze, last_var: var)
       props.empty? ? q : q.where(var => props)
     end
 
+    # Internal batched start. A pattern has either ref_id or ref_ids, never both.
+    def node_refs(var, refs)
+      raise ArgumentError, "a pattern has one start node" unless @state.nodes.empty?
+
+      var = new_var!(var)
+      refs.each { context.graph.check_ref!(_1, :node) }
+      pattern = NodePattern.new(var:, label: nil, ref_id: nil, ref_ids: refs.map(&:id).freeze)
+      with(nodes: { var => pattern }.freeze, last_var: var)
+    end
+
     # Follows an outgoing edge of +type+ from +from+ (default: the last node).
     def out(type, var, label = nil, edge: nil, from: nil, **props) = hop(:out, type, var, label, edge, from, props)
 
     # Follows an incoming edge of +type+ into +from+ (default: the last node).
     def in(type, var, label = nil, edge: nil, from: nil, **props) = hop(:in, type, var, label, edge, from, props)
 
+    # Follows an edge of a symmetric +type+ from +from+ (default: the last
+    # node), whichever end it is stored at: GQL's ~[ ]~ (ADR-0008). Each edge
+    # binds once per orientation that fits, so a self-loop binds once.
+    def both(type, var, label = nil, edge: nil, from: nil, **props) = hop(:both, type, var, label, edge, from, props)
+
     # Structured conditions per variable: where(j: { headcount: Pglpg.gt(0) }).
     def where(by_var)
       conditions = @state.conditions.transform_values(&:dup)
@@ -156,6 +171,12 @@ module Pglpg
       raise ArgumentError, "start the pattern with node" if @state.nodes.empty?
 
       edge_type = context.graph.type.edge_type!(type)
+      if edge_type.symmetric? && direction != :both
+        raise ArgumentError, "#{edge_type.name} is symmetric; use both"
+      elsif !edge_type.symmetric? && direction == :both
+        raise ArgumentError, "#{edge_type.name} is directed; use out or in"
+      end
+
       from = (from || @state.last_var).to_sym
       raise ArgumentError, "#{from} is not a node variable" unless @state.nodes.key?(from)
 
@@ -168,7 +189,7 @@ module Pglpg
         end
       else
         new_var!(var)
-        nodes = nodes.merge(var => NodePattern.new(var:, label:, ref_id: nil)).freeze
+        nodes = nodes.merge(var => NodePattern.new(var:, label:, ref_id: nil, ref_ids: nil)).freeze
       end
 
       # Checked against the node map including this hop's new node.
@@ -225,6 +246,7 @@ module Pglpg
         raise ArgumentError, "with distinct, order only by returned variables (not #{stray.join(", ")})"
       end
 
+      context.temporal_mode!(@state.edges.map { context.graph.type.edge_type!(_1.type) })
       names = aliases
       sql = Sql.new(context.graph.connection)
       inner = kind != :rows
@@ -282,12 +304,26 @@ module Pglpg
 
       @state.edges.each_with_index do |edge, i|
         e = names.fetch(edge.var)
-        near, far = edge.direction == :out ? %w[source_id target_id] : %w[target_id source_id]
-        sql << " JOIN " << edges_table << " AS " << e << " ON " << e << "." << near << " = " << names.fetch(edge.from_var)
-        sql << ".id AND " << e << ".type = "
+        x = "#{names.fetch(edge.from_var)}.id"
+        sql << " JOIN " << edges_table << " AS " << e << " ON "
+        case edge.direction
+        when :out
+          sql << e << ".source_id = " << x
+          far = "#{e}.target_id"
+        when :in
+          sql << e << ".target_id = " << x
+          far = "#{e}.source_id"
+        else
+          # Either stored column; the far end is the other one. A self-loop
+          # matches both conditions but is still one row.
+          sql << "(" << e << ".source_id = " << x << " OR " << e << ".target_id = " << x << ")"
+          far = "(CASE WHEN #{e}.source_id = #{x} THEN #{e}.target_id ELSE #{e}.source_id END)"
+        end
+        sql << " AND " << e << ".type = "
         sql.bind(edge.type.to_s, "text")
         sql << " AND "
         context.append_edge_visible(sql, e)
+        context.append_temporal(sql, e, [context.graph.type.edge_type!(edge.type)])
         conditions_sql(sql, edge.var, e)
         # Different edges (the GQL default match mode).
         @state.edges.first(i).each do |other|
@@ -295,10 +331,10 @@ module Pglpg
         end
 
         if bound.include?(edge.to_var)
-          sql << " AND " << e << "." << far << " = " << names.fetch(edge.to_var) << ".id"
+          sql << " AND " << far << " = " << names.fetch(edge.to_var) << ".id"
         else
           n = names.fetch(edge.to_var)
-          sql << " JOIN " << nodes_table << " AS " << n << " ON " << n << ".id = " << e << "." << far << " AND "
+          sql << " JOIN " << nodes_table << " AS " << n << " ON " << n << ".id = " << far << " AND "
           node_conditions(sql, @state.nodes.fetch(edge.to_var), n)
           bound << edge.to_var
         end
@@ -319,6 +355,11 @@ module Pglpg
         sql << " AND " << n << ".id = "
         sql.bind(node.ref_id, "bigint")
       end
+      if node.ref_ids
+        sql << " AND " << n << ".id = ANY("
+        sql.bind_text_array(node.ref_ids.map(&:to_s))
+        sql << "::bigint[])"
+      end
       conditions_sql(sql, node.var, n)
     end
 
@@ -328,12 +369,20 @@ module Pglpg
         sql << " AND "
         case cond.op
         when :eq
-          if key && key.property == prop.name
-            # Matches the key's partial unique index.
-            sql << a << ".labels @> ARRAY["
-            sql.literal(key.declared_on) << "]::text[] AND (" << a << ".properties ->> "
+          if key && key.properties.include?(prop.name)
+            # Match every component of the same partial index used by the
+            # uniqueness arbiter, including jsonb numeric/boolean equality.
+            if @state.nodes.key?(var)
+              sql << a << ".labels @> ARRAY["
+              sql.literal(key.declared_on) << "]::text[]"
+            else
+              sql << a << ".type = "
+              sql.literal(key.declared_on)
+            end
+            sql << " AND (" << a << ".properties " << (key.json_component?(prop.name) ? "-> " : "->> ")
             sql.literal(prop.name) << ") = "
-            sql.bind(prop.encode(cond.value), "text")
+            encoded = prop.encode(cond.value)
+            key.json_component?(prop.name) ? sql.bind_json(encoded) : sql.bind(encoded, "text")
             next
           end
           sql << a << ".properties @> "
@@ -356,8 +405,12 @@ module Pglpg
     end
 
     def key_of(var)
-      label = @state.nodes[var]&.label
-      label && context.graph.type.node_type!(label).key
+      if (node = @state.nodes[var])
+        node.label && context.graph.type.node_type!(node.label).key
+      else
+        edge = @state.edges.find { _1.var == var }
+        edge && context.graph.type.edge_type!(edge.type).key
+      end
     end
 
     # Validates values up front, so errors surface where the query is built.

data/lib/pglpg/reachability.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module Pglpg
+  # The result of Context#reachable: visible nodes with their minimum depth,
+  # ordered by depth, then id. +complete+ is false when more visible nodes
+  # are reachable within max_depth than were returned; +stopped_at_depth+ is
+  # then the depth of the last returned node, and nil otherwise.
+  Reachability = Data.define(:nodes, :complete, :stopped_at_depth) do
+    def complete? = complete
+  end
+
+  # Compiles and runs Context#reachable as one recursive CTE whose rows are
+  # whole BFS levels (ADR-0009). Each level excludes visited nodes and is
+  # capped at remaining + 1, which is 1 when the result is exactly full: that
+  # one row is the probe that decides completeness.
+  class Reachable
+    DIRECTIONS = %i[out in both].freeze
+
+    def initialize(context, from:, via:, direction:, max_depth:, max_nodes:, deadline:)
+      @context = context
+      @graph = context.graph
+      @from = @graph.check_ref!(from, :node)
+      @types = edge_types!(via, direction)
+      @context.temporal_mode!(@types.map { @graph.type.edge_type!(_1) })
+      @direction = direction
+      @max_depth = positive_integer!(max_depth, "max_depth")
+      @max_nodes = positive_integer!(max_nodes, "max_nodes")
+      raise ArgumentError, "max_nodes exceeds max_rows (#{max_rows})" if @max_nodes > max_rows
+
+      @timeout = timeout_ms(deadline)
+      freeze
+    end
+
+    def call
+      rows = @context.read(compile, timeout: @timeout).map { [@graph.ref(:node, _1["id"].to_i), _1["depth"].to_i].freeze }
+      if rows.size > @max_nodes
+        nodes = rows.first(@max_nodes)
+        Reachability.new(nodes: nodes.freeze, complete: false, stopped_at_depth: nodes.last[1])
+      else
+        Reachability.new(nodes: rows.freeze, complete: true, stopped_at_depth: nil)
+      end
+    end
+
+    def compile
+      sql = Sql.new(@graph.connection)
+      nodes = @context.table_sql(@graph.nodes_table)
+      sql << "WITH RECURSIVE bfs(depth, frontier, visited) AS ("
+      sql << "SELECT 0, ARRAY[s.id], ARRAY[s.id] FROM " << nodes << " AS s WHERE s.id = "
+      sql.bind(@from.id, "bigint") << " AND "
+      @context.append_node_visible(sql, "s")
+      sql << " UNION ALL SELECT b.depth + 1, nxt.ids, b.visited || nxt.ids FROM bfs AS b"
+      sql << " CROSS JOIN LATERAL (SELECT ARRAY(SELECT DISTINCT n.id FROM ("
+      append_steps(sql)
+      sql << ") AS x JOIN " << nodes << " AS n ON n.id = x.far AND "
+      @context.append_node_visible(sql, "n")
+      sql << " WHERE n.id <> ALL(b.visited) ORDER BY n.id LIMIT "
+      # remaining + 1, where remaining = max_nodes - (cardinality(visited) - 1)
+      sql.bind(@max_nodes, "int") << " - cardinality(b.visited) + 2) AS ids"
+      # Without OFFSET 0 the subquery is inlined into both references to
+      # nxt.ids and each level is computed twice.
+      sql << " OFFSET 0) AS nxt WHERE b.depth < "
+      sql.bind(@max_depth, "int") << " AND cardinality(b.frontier) > 0 AND cardinality(b.visited) - 1 <= "
+      sql.bind(@max_nodes, "int") << ")"
+      sql << " SELECT b.depth, u.id FROM bfs AS b CROSS JOIN LATERAL unnest(b.frontier) WITH ORDINALITY AS u(id, ord)"
+      sql << " WHERE b.depth > 0 ORDER BY b.depth, u.ord"
+    end
+
+    private
+
+    def max_rows = Pglpg.configuration.max_rows
+
+    # The far ends of visible edges leaving the frontier, as column "far". A
+    # symmetric type is followed from both stored columns, as two branches
+    # that each use a traversal index.
+    def append_steps(sql)
+      case @direction
+      when :out then append_step(sql, "e0", "source_id", "target_id")
+      when :in then append_step(sql, "e0", "target_id", "source_id")
+      else
+        append_step(sql, "e0", "source_id", "target_id")
+        sql << " UNION ALL "
+        append_step(sql, "e1", "target_id", "source_id")
+      end
+    end
+
+    def append_step(sql, e, near, far)
+      sql << "SELECT " << e << "." << far << " AS far FROM " << @context.table_sql(@graph.edges_table) << " AS " << e
+      sql << " WHERE " << e << "." << near << " = ANY(b.frontier) AND " << e << ".type = ANY("
+      sql.bind_text_array(@types) << ") AND "
+      @context.append_edge_visible(sql, e)
+      @context.append_temporal(sql, e, @types.map { @graph.type.edge_type!(_1) })
+    end
+
+    def edge_types!(via, direction)
+      raise ArgumentError, "direction must be :out, :in or :both" unless DIRECTIONS.include?(direction)
+
+      types = (via.is_a?(Array) ? via : [via]).map { @graph.type.edge_type!(_1) }.uniq
+      raise ArgumentError, "via needs at least one edge type" if types.empty?
+
+      types.each do |t|
+        if t.symmetric? && direction != :both
+          raise ArgumentError, "#{t.name} is symmetric; use direction: :both"
+        elsif !t.symmetric? && direction == :both
+          raise ArgumentError, "#{t.name} is directed; use direction: :out or :in"
+        end
+      end
+      types.map(&:name).freeze
+    end
+
+    def positive_integer!(value, name)
+      raise ArgumentError, "#{name} must be a positive Integer" unless value.is_a?(Integer) && value.positive?
+
+      value
+    end
+
+    # The statement timeout in milliseconds, or nil to leave the session's.
+    # A configured timeout caps the deadline; nil or 0 configures no cap.
+    def timeout_ms(deadline)
+      configured = Pglpg.configuration.statement_timeout
+      cap = Integer(configured) if configured && Integer(configured).positive?
+      return cap if deadline.nil?
+
+      unless deadline.is_a?(Numeric) && deadline.real? && deadline.finite? && deadline.positive?
+        raise ArgumentError, "deadline must be a positive number of seconds"
+      end
+
+      # Rounded up, so a positive deadline never becomes 0 (no timeout). The
+      # round(6) drops float noise such as 0.3 * 1000 = 300.00000000000006.
+      ms = [(deadline * 1000).round(6).ceil, 1].max
+      cap ? [cap, ms].min : ms
+    end
+  end
+end