pglpg 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dcdce167b8e343909f06e710fdb65a1833a5cfa3649c85a475050c830a463a0d
-  data.tar.gz: f7725ba5bd6255af98a77875b766ac0e7d3a180f4af7ced79b50446998fbda6d
+  metadata.gz: 0d0ce8830ee927b0b6f98d9a8601ce9f86bb3bea4570de038f6274f9f1008884
+  data.tar.gz: d0ba5b1cf855c1e9324bbbae62dd204248c34344944a2848a721af581b58580e
 SHA512:
-  metadata.gz: e536165dfa69606c33d7c15c4dd77c68878a3be01b6f8b7b097e4effd3597d26a6b65e2dd1c87d2ce5247c588980bebb779af6e674d4e29d84f3efcf05187b22
-  data.tar.gz: 7c6fbe3e465c7134ae05ec5601e61f941462687f60f1dd91242641b1ab22446e44d0f9836c3db4cb2ca6c330f0136ead5cd8c23c305eac300ff9d15374aa645a
+  metadata.gz: 8b6b63b7e1b93393c333a2a250c6b6eb854f164a81768df72ca2ea421a46ca0860e35922e1fdc8484bd517a910de3c3b680e499e75b060a91aa949250fa1308f
+  data.tar.gz: 68b0ccc4e5d4237da44578d87fe010b322baf53ec0feeefbd83a6393d0744f1f1b395b17994b00259ebe851872686db57762234385ec2e52e62b4b92027967a6

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.5.0 (2026-11-05)
+
+### Added
+
+- `Context#neighborhood` returns typed visible nodes with minimum depths and
+  the eligible edges between them in one PostgreSQL statement and snapshot.
+  The seed counts toward the node budget. Independent node and edge overflow
+  probes give exact truncation flags, including at a zero edge budget. Mixed
+  directed and symmetric types use the neighborhood direction rules.
+
+- The shared visibility suite in `Pglpg::Testing` now observes neighborhood
+  nodes, edges, order and both truncation flags when comparing results before
+  and after hidden data is added.
+
 ## 0.4.0 (2026-11-04)
 
 ### Added

data/README.md

@@ -8,22 +8,27 @@ ordinary tables, written inside your own transactions. Every query applies
 your visibility policy to every node and edge on every hop, so hidden records
 never act as bridges and never show up in counts or limits.
 
-Status: **0.4.0 release candidate**, with a read-only text MATCH parser.
-The latest published version is 0.3.0. The design and its decisions live in the
+Status: **0.5.0** release candidate, with bounded neighborhoods that return
+nodes and edges from one snapshot with exact truncation flags. The design and its decisions live in the
 [pglpg.md](https://knowen.md/nodes/36325) knowledge base. Requires Ruby ≥ 4.0,
 ActiveRecord ≥ 8.1 and PostgreSQL ≥ 18: the versions CI tests.
 
 ## Install
 
 ```ruby
-gem "pglpg", "~> 0.3.0"
+gem "pglpg", "~> 0.5.0"
 ```
 
 Before 1.0, minor releases may break compatibility. Read the
 [0.3.0 upgrade notes](CHANGELOG.md) and the migration steps below before
 upgrading from 0.2. Applications still on 0.1 must also apply the 0.2 notes.
 
-After 0.4.0 is published, use `gem "pglpg", "~> 0.4.0"`.
+## Upgrade from 0.4
+
+Bounded neighborhoods are additive and require no schema migration. Existing
+reachability and MATCH queries keep their behavior. Applications using the shared
+visibility suite should rerun it: it now also observes neighborhood nodes, edges,
+ordering and both truncation flags.
 
 ## Upgrade from 0.3
 
@@ -230,6 +235,37 @@ isolation level. `deadline` is in seconds and can only shorten the configured
 `statement_timeout`; with no timeout configured it applies alone. Running out
 of time raises `Pglpg::QueryTimeout` and leaves your transaction usable.
 
+## Bounded neighborhoods (0.5)
+
+```ruby
+r = g.neighborhood(from: ann, via: %i[KNOWS FRIEND], direction: :both,
+                   max_depth: 2, max_nodes: 50, max_edges: 100, deadline: 2.0)
+r.nodes.map { |node, depth| [node.ref, depth] }
+r.edges.map { |edge| [edge.ref, edge.source, edge.target] }
+r.nodes_truncated?
+r.edges_truncated?
+```
+
+The result contains typed `Pglpg::Node` values with their minimum depths and
+typed `Pglpg::Edge` values, from one statement and snapshot. The seed appears
+at depth zero and counts toward `max_nodes`. Nodes are ordered by depth then
+ID, and edges by ID. Visibility and the context's date rules apply before
+selection and overflow probes.
+
+`via` filters both traversal and the edges returned between selected nodes.
+Directed types follow `:out`, `:in`, or either direction with `:both`;
+symmetric types follow both directions with any option. Mixed lists are
+allowed. Traversal direction selects nodes. The result includes eligible
+stored edges between those nodes regardless of direction, preserving their
+stored source and target.
+
+The two flags report exact overflow independently. `edges_truncated?` is
+true only when another eligible edge exists between returned nodes; edges
+touching an omitted node cannot affect it. An exactly full cap gives false.
+`max_nodes` is 1 through `max_rows`, `max_edges` is 0 through `max_rows`,
+and `max_depth` is at least 1. A zero edge cap still probes for an eligible
+edge. See the [API contract](https://knowen.md/nodes/36329) for the full rules.
+
 ## Models and eager loading
 
 `require "pglpg/model"` adds optional ActiveModel records bound to a graph and

data/lib/pglpg/context.rb

@@ -76,6 +76,11 @@ module Pglpg
       Reachable.new(self, from:, via:, direction:, max_depth:, max_nodes:, deadline:).call
     end
 
+    # A bounded visible induced subgraph, including the seed, in one snapshot.
+    def neighborhood(from:, via:, max_depth:, max_nodes:, max_edges:, direction: :out, deadline: nil)
+      NeighborhoodQuery.new(self, from:, via:, max_depth:, max_nodes:, max_edges:, direction:, deadline:).call
+    end
+
     def insert_node(type, properties: {}, attrs: {}) = writer.insert_node(type, properties:, attrs:)
 
     def update_node(ref, properties: {}, attrs: {}) = writer.update_node(ref, properties:, attrs:)

data/lib/pglpg/neighborhood.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Pglpg
+  Neighborhood = Data.define(:nodes, :edges, :nodes_truncated, :edges_truncated) do
+    def nodes_truncated? = nodes_truncated
+    def edges_truncated? = edges_truncated
+  end
+
+  # Reuses Reachable's bounded BFS, then selects the induced edges before
+  # hydrating either result. Probe nodes are excluded from the selected set.
+  class NeighborhoodQuery < Reachable
+    def initialize(context, max_edges:, **options)
+      unless max_edges.is_a?(Integer) && max_edges.between?(0, Pglpg.configuration.max_rows)
+        raise ArgumentError, "max_edges must be an Integer from 0 to max_rows"
+      end
+
+      @max_edges = max_edges
+      super(context, **options)
+    end
+
+    def call
+      row = @context.read(compile, timeout: @timeout).fetch(0)
+      nodes = JSON.parse(row.fetch("nodes")).map { |data, depth| [@graph.build_node(data), depth].freeze }
+      edges = JSON.parse(row.fetch("edges")).map { @graph.build_edge(_1) }
+      Neighborhood.new(nodes: nodes.freeze, edges: edges.freeze,
+                       nodes_truncated: row.fetch("nodes_truncated"), edges_truncated: row.fetch("edges_truncated"))
+    end
+
+    def compile
+      sql = Sql.new(@graph.connection)
+      append_bfs(sql)
+      sql << ", candidates AS MATERIALIZED (SELECT b.depth, u.id, u.ord FROM bfs AS b"
+      sql << " CROSS JOIN LATERAL unnest(b.frontier) WITH ORDINALITY AS u(id, ord))"
+      sql << ", selected AS MATERIALIZED (SELECT id, depth FROM candidates ORDER BY depth, ord LIMIT "
+      sql.bind(@max_nodes, "bigint") << ")"
+      sql << ", selected_rows AS MATERIALIZED (SELECT n.* FROM selected AS s JOIN "
+      sql << @context.table_sql(@graph.nodes_table) << " AS n ON n.id = s.id AND "
+      @context.append_node_visible(sql, "n")
+      sql << ")"
+      append_edges(sql)
+      sql << " SELECT COALESCE((SELECT jsonb_agg(jsonb_build_array(to_jsonb(n), s.depth) ORDER BY s.depth, s.id)"
+      sql << " FROM selected AS s JOIN selected_rows AS n ON n.id = s.id), '[]') AS nodes,"
+      sql << " COALESCE((SELECT jsonb_agg(to_jsonb(e) ORDER BY e.id) FROM"
+      sql << " (SELECT * FROM edge_probe ORDER BY id LIMIT "
+      sql.bind(@max_edges, "bigint") << ") AS e), '[]') AS edges,"
+      sql << " (SELECT count(*) FROM candidates) > "
+      sql.bind(@max_nodes, "bigint") << " AS nodes_truncated,"
+      sql << " (SELECT count(*) FROM edge_probe) > "
+      sql.bind(@max_edges, "bigint") << " AS edges_truncated"
+    end
+
+    private
+
+    def neighbor_budget = @max_nodes - 1
+
+    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).name }.uniq
+      raise ArgumentError, "via needs at least one edge type" if types.empty?
+
+      types.freeze
+    end
+
+    def append_steps(sql)
+      outgoing = @types.select { @direction != :in || @graph.type.edge_type!(_1).symmetric? }
+      incoming = @types.select { @direction != :out || @graph.type.edge_type!(_1).symmetric? }
+      steps = [[outgoing, "source_id", "target_id"], [incoming, "target_id", "source_id"]]
+      steps.reject { |types, _, _| types.empty? }.each_with_index do |(types, near, far), index|
+        sql << " UNION ALL " if index.positive?
+        append_step(sql, "e#{index}", near, far, types)
+      end
+    end
+
+    def append_edges(sql)
+      nodes = "selected_rows"
+      sql << ", edge_probe AS MATERIALIZED (SELECT e.* FROM " << @context.table_sql(@graph.edges_table) << " AS e"
+      sql << " JOIN selected AS s ON s.id = e.source_id JOIN selected AS t ON t.id = e.target_id"
+      sql << " JOIN " << nodes << " AS sn ON sn.id = s.id AND "
+      @context.append_node_visible(sql, "sn")
+      sql << " JOIN " << nodes << " AS tn ON tn.id = t.id AND "
+      @context.append_node_visible(sql, "tn")
+      sql << " WHERE 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) })
+      sql << " ORDER BY e.id LIMIT "
+      sql.bind(@max_edges + 1, "bigint") << ")"
+    end
+  end
+end

data/lib/pglpg/reachability.rb

@@ -43,6 +43,16 @@ module Pglpg
 
     def compile
       sql = Sql.new(@graph.connection)
+      append_bfs(sql)
+      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 neighbor_budget = @max_nodes
+
+    def append_bfs(sql)
       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 = "
@@ -55,18 +65,14 @@ module Pglpg
       @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"
+      sql.bind(neighbor_budget, "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"
+      sql.bind(neighbor_budget, "int") << ")"
     end
 
-    private
-
     def max_rows = Pglpg.configuration.max_rows
 
     # The far ends of visible edges leaving the frontier, as column "far". A
@@ -83,12 +89,12 @@ module Pglpg
       end
     end
 
-    def append_step(sql, e, near, far)
+    def append_step(sql, e, near, far, types = @types)
       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 "
+      sql.bind_text_array(types) << ") AND "
       @context.append_edge_visible(sql, e)
-      @context.append_temporal(sql, e, @types.map { @graph.type.edge_type!(_1) })
+      @context.append_temporal(sql, e, types.map { @graph.type.edge_type!(_1) })
     end
 
     def edge_types!(via, direction)

data/lib/pglpg/testing.rb

@@ -67,6 +67,14 @@ module Pglpg
           [r.nodes.map { |node, depth| [node.id, depth] }, r.complete, r.stopped_at_depth]
         end
       end
+      out[:neighborhoods] = refs.select(&:node?).map do |ref|
+        [0, 1, budget].uniq.map do |edge_budget|
+          r = ctx.neighborhood(from: ref, via: %i[WORKS_ON BASED_AT KNOWS FRIEND], direction: :both,
+                               max_depth: 3, max_nodes: budget, max_edges: edge_budget)
+          [r.nodes.map { |node, depth| [element_data(node), depth] },
+           r.edges.map { element_data(_1) }, r.nodes_truncated?, r.edges_truncated?]
+        end
+      end
       out[:last_by_name] = element_data(m.().node(:p, :Person).order(p: { name: :desc }).first&.fetch(:p))
       out[:find] = refs.map { element_data(ctx.find(_1)) }
       out[:find_node] = %w[P1 P2 P3 H1].map { element_data(ctx.find_node(:Person, namespace: _1 == "H1" ? "hidden" : "visible", uid: _1)) }

data/lib/pglpg/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Pglpg
-  VERSION = "0.4.0"
+  VERSION = "0.5.0"
 end

data/lib/pglpg.rb

@@ -25,6 +25,7 @@ require_relative "pglpg/writer"
 require_relative "pglpg/query"
 require_relative "pglpg/match_parser"
 require_relative "pglpg/reachability"
+require_relative "pglpg/neighborhood"
 
 # Labeled property graphs stored in plain PostgreSQL tables.
 module Pglpg

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pglpg
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Anton Fefilov
@@ -60,6 +60,7 @@ files:
 - lib/pglpg/model/edge.rb
 - lib/pglpg/model/node.rb
 - lib/pglpg/model/relation.rb
+- lib/pglpg/neighborhood.rb
 - lib/pglpg/query.rb
 - lib/pglpg/reachability.rb
 - lib/pglpg/ref.rb