From 734301fe656ea8764ddadd744aa8748551352e09 Mon Sep 17 00:00:00 2001 From: venkat1701 Date: Sun, 25 Oct 2026 19:38:59 +0530 Subject: [PATCH 1/3] fix(hora): expand shared nested edges once per path and meter every row EXPAND kept one visited set for the whole traversal, so a hyperedge reached through a second parent was reported as CYCLE. It now tracks the hyperedges on the current path only, so CYCLE means a real cycle. Following every path can repeat a shared hyperedge, so every emitted row and every descent now takes one unit of the row budget, and the traversal stops with one BUDGET_EXHAUSTED row at the first refusal. Before, only descents were counted and rows were unbounded. --- .../src/main/java/io/hstore/db/hora/Hora.java | 34 +++++++----- .../test/java/io/hstore/db/DatabaseTest.java | 53 +++++++++++++++++++ docs/database/hora.md | 11 ++-- 3 files changed, 82 insertions(+), 16 deletions(-) diff --git a/database/src/main/java/io/hstore/db/hora/Hora.java b/database/src/main/java/io/hstore/db/hora/Hora.java index 7b1e4394..cabd7fc0 100644 --- a/database/src/main/java/io/hstore/db/hora/Hora.java +++ b/database/src/main/java/io/hstore/db/hora/Hora.java @@ -308,27 +308,37 @@ public Stream expand(long atom, int depth, Budget budget) { return out.stream(); } - private void expand(long atom, int depth, Set visited, List path, Budget.Meter meter, List out) { - if (depth == 0 || !meter.tryConsume(1)) { + private boolean expand(long atom, int depth, Set ancestors, List path, Budget.Meter meter, List out) { + if (!meter.tryConsume(1)) { out.add(new Expansion(List.copyOf(path), atom, Expansion.Status.BUDGET_EXHAUSTED)); - return; + return false; } - if (!visited.add(atom)) { + if (depth == 0) { + out.add(new Expansion(List.copyOf(path), atom, Expansion.Status.BUDGET_EXHAUSTED)); + return true; + } + if (!ancestors.add(atom)) { out.add(new Expansion(List.copyOf(path), atom, Expansion.Status.CYCLE)); - return; + return true; } - for (Incidence member : reader.edge(atom).stream().toList()) { - if (!reader.owns(member.member())) { + boolean proceed = true; + for (Iterator members = reader.edge(atom).stream().iterator(); proceed && members.hasNext(); ) { + long member = members.next().member(); + if (!reader.owns(member)) { continue; } - path.add(member.member()); - boolean nested = reader.atom(member.member()).filter(Atom::isEdge).isPresent(); - if (nested) { - expand(member.member(), depth - 1, visited, path, meter, out); + path.add(member); + if (reader.atom(member).filter(Atom::isEdge).isPresent()) { + proceed = expand(member, depth - 1, ancestors, path, meter, out); + } else if (meter.tryConsume(1)) { + out.add(new Expansion(List.copyOf(path), member, Expansion.Status.EMIT)); } else { - out.add(new Expansion(List.copyOf(path), member.member(), Expansion.Status.EMIT)); + out.add(new Expansion(List.copyOf(path), member, Expansion.Status.BUDGET_EXHAUSTED)); + proceed = false; } path.removeLast(); } + ancestors.remove(atom); + return proceed; } } diff --git a/database/src/test/java/io/hstore/db/DatabaseTest.java b/database/src/test/java/io/hstore/db/DatabaseTest.java index 78804215..18e7e44b 100644 --- a/database/src/test/java/io/hstore/db/DatabaseTest.java +++ b/database/src/test/java/io/hstore/db/DatabaseTest.java @@ -430,4 +430,57 @@ void writesOnBranchesStayIsolated() { assertTrue(database.read(reader -> reader.find("Person", "ghost")).isEmpty()); assertTrue(database.read(branch.id(), reader -> reader.find("Person", "ghost")).isPresent()); } + + @Test + void expandFollowsEveryPathAndStaysWithinItsBudget() { + long[] ids = database.write(writer -> { + long leaf = writer.node("Person", "expand-leaf", Map.of("name", "Leaf")); + long bottom = writer.edge("Coauthorship"); + writer.add(bottom, leaf, MemberSpec.PLAIN); + long left = writer.edge("Coauthorship"); + long right = writer.edge("Coauthorship"); + writer.add(left, bottom, MemberSpec.PLAIN); + writer.add(right, bottom, MemberSpec.PLAIN); + long top = writer.edge("Coauthorship"); + writer.add(top, left, MemberSpec.PLAIN); + writer.add(top, right, MemberSpec.PLAIN); + long loop = writer.edge("Coauthorship"); + long back = writer.edge("Coauthorship"); + writer.add(loop, back, MemberSpec.PLAIN); + writer.add(back, loop, MemberSpec.PLAIN); + long wide = writer.edge("Coauthorship"); + for (int i = 0; i < 20; i++) { + writer.add(wide, writer.node("Person", "expand-wide-" + i, Map.of("name", "W" + i)), MemberSpec.PLAIN); + } + long previous = bottom; + for (int level = 0; level < 12; level++) { + long a = writer.edge("Coauthorship"); + long b = writer.edge("Coauthorship"); + writer.add(a, previous, MemberSpec.PLAIN); + writer.add(b, previous, MemberSpec.PLAIN); + previous = writer.edge("Coauthorship"); + writer.add(previous, a, MemberSpec.PLAIN); + writer.add(previous, b, MemberSpec.PLAIN); + } + return new long[]{top, left, right, bottom, leaf, loop, back, wide, previous}; + }); + long top = ids[0], left = ids[1], right = ids[2], bottom = ids[3], leaf = ids[4], loop = ids[5], back = ids[6]; + database.read(reader -> { + Hora hora = Hora.on(reader); + assertEquals(List.of( + new Hora.Expansion(List.of(top, left, bottom, leaf), leaf, Hora.Expansion.Status.EMIT), + new Hora.Expansion(List.of(top, right, bottom, leaf), leaf, Hora.Expansion.Status.EMIT)), + hora.expand(top, 8, Budget.DEFAULT).toList()); + assertEquals(List.of(new Hora.Expansion(List.of(loop, back, loop), loop, Hora.Expansion.Status.CYCLE)), + hora.expand(loop, 8, Budget.DEFAULT).toList()); + List wide = hora.expand(ids[7], 8, Budget.DEFAULT.withRows(5)).toList(); + assertEquals(5, wide.size()); + assertEquals(Hora.Expansion.Status.BUDGET_EXHAUSTED, wide.getLast().status()); + assertEquals(4, wide.stream().filter(row -> row.status() == Hora.Expansion.Status.EMIT).count()); + List layered = hora.expand(ids[8], 64, Budget.DEFAULT.withRows(1_000).withDepth(64)).toList(); + assertTrue(layered.size() <= 1_001, "rows " + layered.size()); + assertEquals(1, layered.stream().filter(row -> row.status() == Hora.Expansion.Status.BUDGET_EXHAUSTED).count()); + return null; + }); + } } diff --git a/docs/database/hora.md b/docs/database/hora.md index 80d77638..b658c7f9 100644 --- a/docs/database/hora.md +++ b/docs/database/hora.md @@ -170,10 +170,13 @@ descends into members that are themselves hyperedges and emits leaves. | Status | Meaning | |---|---| | `EMIT` | a non-edge member reached through `path` | -| `CYCLE` | a hyperedge already visited on this traversal (cycles through membership are possible because hyperedges can contain hyperedges) | -| `BUDGET_EXHAUSTED` | depth `0` reached or the row budget denied the next step | +| `CYCLE` | a hyperedge that is already on `path` (cycles through membership are possible because hyperedges can contain hyperedges). A hyperedge reached again through a different parent is expanded again | +| `BUDGET_EXHAUSTED` | depth `0` reached on this path, or the row budget denied the next step and the traversal stopped | -The effective depth is `min(d, budget.maxDepth)` (default 8); `LIMIT` sets the row budget. +The effective depth is `min(d, budget.maxDepth)` (default 8); `LIMIT` sets the row budget. Every row the traversal +emits and every descent into a nested hyperedge takes one unit of the budget. When the budget refuses, one +`BUDGET_EXHAUSTED` row marks where the traversal stopped and nothing more is emitted, so the output never exceeds the +budget by more than that row, whatever the shape of the nesting. ```sql EXPAND @120 DEPTH 2 LIMIT 20; @@ -273,5 +276,5 @@ compared with `main` to test whether observed overlaps exceed chance; the branch | `OVERLAP JOIN T THRESHOLD t` | `O(Σ_{a∈T} Σ_{v∈M(a)} |I(v)| + #pairs · t log n)` | `O(#partners of one edge + #results)` | | set algebra | `O(min(|A|,|B|) · log max(|A|,|B|))` for intersections via leapfrog | result size | | `CLOSURE e DIM d` | `O(Σ_{k≤d+1} C(|M(e)|, k))` | `O(d)` per subset (lazy) | -| `EXPAND e DEPTH d` | `O(rows emitted)` | `O(depth + visited)` | +| `EXPAND e DEPTH d` | `O(rows emitted)`, bounded by the row budget | `O(depth + rows emitted)` | | `PATTERN` | bounded by the product of candidate domains after pruning | `O(partial bindings)` | From 1a980736f91189970c68ed64e990f532ea46c891 Mon Sep 17 00:00:00 2001 From: venkat1701 Date: Tue, 27 Oct 2026 16:00:00 +0530 Subject: [PATCH 2/3] Tell a reached depth apart from an exhausted budget in EXPAND Rows at the requested DEPTH were labelled BUDGET_EXHAUSTED, so a client could not tell a complete answer from a cut one. They are now DEPTH_LIMIT; BUDGET_EXHAUSTED is kept for the row budget and for the budget's own depth cap. --- database/src/main/java/io/hstore/db/hora/Hora.java | 12 +++++++----- .../src/test/java/io/hstore/db/DatabaseTest.java | 8 ++++++++ docs/database/hora.md | 3 ++- 3 files changed, 17 insertions(+), 6 deletions(-) diff --git a/database/src/main/java/io/hstore/db/hora/Hora.java b/database/src/main/java/io/hstore/db/hora/Hora.java index cabd7fc0..fbf56463 100644 --- a/database/src/main/java/io/hstore/db/hora/Hora.java +++ b/database/src/main/java/io/hstore/db/hora/Hora.java @@ -46,7 +46,7 @@ public record OverlapPair(long left, long right, long overlap) { } public record Expansion(List path, long atom, Status status) { - public enum Status { EMIT, CYCLE, BUDGET_EXHAUSTED } + public enum Status { EMIT, CYCLE, DEPTH_LIMIT, BUDGET_EXHAUSTED } } private final Reader reader; @@ -304,17 +304,19 @@ public Stream expand(long atom, int depth, Budget budget) { reader.require(atom); Budget.Meter meter = budget.start(); List out = new ArrayList<>(); - expand(atom, Math.min(depth, budget.maxDepth()), new HashSet<>(), new ArrayList<>(List.of(atom)), meter, out); + Expansion.Status bottom = budget.maxDepth() < depth ? Expansion.Status.BUDGET_EXHAUSTED : Expansion.Status.DEPTH_LIMIT; + expand(atom, Math.min(depth, budget.maxDepth()), bottom, new HashSet<>(), new ArrayList<>(List.of(atom)), meter, out); return out.stream(); } - private boolean expand(long atom, int depth, Set ancestors, List path, Budget.Meter meter, List out) { + private boolean expand(long atom, int depth, Expansion.Status bottom, Set ancestors, List path, Budget.Meter meter, + List out) { if (!meter.tryConsume(1)) { out.add(new Expansion(List.copyOf(path), atom, Expansion.Status.BUDGET_EXHAUSTED)); return false; } if (depth == 0) { - out.add(new Expansion(List.copyOf(path), atom, Expansion.Status.BUDGET_EXHAUSTED)); + out.add(new Expansion(List.copyOf(path), atom, bottom)); return true; } if (!ancestors.add(atom)) { @@ -329,7 +331,7 @@ private boolean expand(long atom, int depth, Set ancestors, List pat } path.add(member); if (reader.atom(member).filter(Atom::isEdge).isPresent()) { - proceed = expand(member, depth - 1, ancestors, path, meter, out); + proceed = expand(member, depth - 1, bottom, ancestors, path, meter, out); } else if (meter.tryConsume(1)) { out.add(new Expansion(List.copyOf(path), member, Expansion.Status.EMIT)); } else { diff --git a/database/src/test/java/io/hstore/db/DatabaseTest.java b/database/src/test/java/io/hstore/db/DatabaseTest.java index 18e7e44b..db9f4df2 100644 --- a/database/src/test/java/io/hstore/db/DatabaseTest.java +++ b/database/src/test/java/io/hstore/db/DatabaseTest.java @@ -473,6 +473,14 @@ void expandFollowsEveryPathAndStaysWithinItsBudget() { hora.expand(top, 8, Budget.DEFAULT).toList()); assertEquals(List.of(new Hora.Expansion(List.of(loop, back, loop), loop, Hora.Expansion.Status.CYCLE)), hora.expand(loop, 8, Budget.DEFAULT).toList()); + assertEquals(List.of( + new Hora.Expansion(List.of(top, left, bottom), bottom, Hora.Expansion.Status.DEPTH_LIMIT), + new Hora.Expansion(List.of(top, right, bottom), bottom, Hora.Expansion.Status.DEPTH_LIMIT)), + hora.expand(top, 2, Budget.DEFAULT).toList()); + assertEquals(List.of( + new Hora.Expansion(List.of(top, left, bottom), bottom, Hora.Expansion.Status.BUDGET_EXHAUSTED), + new Hora.Expansion(List.of(top, right, bottom), bottom, Hora.Expansion.Status.BUDGET_EXHAUSTED)), + hora.expand(top, 8, Budget.DEFAULT.withDepth(2)).toList()); List wide = hora.expand(ids[7], 8, Budget.DEFAULT.withRows(5)).toList(); assertEquals(5, wide.size()); assertEquals(Hora.Expansion.Status.BUDGET_EXHAUSTED, wide.getLast().status()); diff --git a/docs/database/hora.md b/docs/database/hora.md index b658c7f9..bdaff7f8 100644 --- a/docs/database/hora.md +++ b/docs/database/hora.md @@ -171,7 +171,8 @@ descends into members that are themselves hyperedges and emits leaves. |---|---| | `EMIT` | a non-edge member reached through `path` | | `CYCLE` | a hyperedge that is already on `path` (cycles through membership are possible because hyperedges can contain hyperedges). A hyperedge reached again through a different parent is expanded again | -| `BUDGET_EXHAUSTED` | depth `0` reached on this path, or the row budget denied the next step and the traversal stopped | +| `DEPTH_LIMIT` | a hyperedge at the depth the query asked for; its members were not expanded, and everything above it is complete | +| `BUDGET_EXHAUSTED` | the budget cut the traversal short: the row budget denied the next step and the traversal stopped, or the budget's depth cap (`budget.maxDepth`, lower than the requested depth) was reached on this path | The effective depth is `min(d, budget.maxDepth)` (default 8); `LIMIT` sets the row budget. Every row the traversal emits and every descent into a nested hyperedge takes one unit of the budget. When the budget refuses, one From 01e860e8a5b12f67e72a825c4b42d5cc24683bb3 Mon Sep 17 00:00:00 2001 From: venkat1701 Date: Tue, 27 Oct 2026 16:22:06 +0530 Subject: [PATCH 3/3] Report a cycle at the requested depth as CYCLE --- database/src/main/java/io/hstore/db/hora/Hora.java | 9 +++++---- database/src/test/java/io/hstore/db/DatabaseTest.java | 4 ++++ docs/database/hora.md | 2 +- 3 files changed, 10 insertions(+), 5 deletions(-) diff --git a/database/src/main/java/io/hstore/db/hora/Hora.java b/database/src/main/java/io/hstore/db/hora/Hora.java index fbf56463..e6824804 100644 --- a/database/src/main/java/io/hstore/db/hora/Hora.java +++ b/database/src/main/java/io/hstore/db/hora/Hora.java @@ -315,14 +315,15 @@ private boolean expand(long atom, int depth, Expansion.Status bottom, Set out.add(new Expansion(List.copyOf(path), atom, Expansion.Status.BUDGET_EXHAUSTED)); return false; } - if (depth == 0) { - out.add(new Expansion(List.copyOf(path), atom, bottom)); + if (ancestors.contains(atom)) { + out.add(new Expansion(List.copyOf(path), atom, Expansion.Status.CYCLE)); return true; } - if (!ancestors.add(atom)) { - out.add(new Expansion(List.copyOf(path), atom, Expansion.Status.CYCLE)); + if (depth == 0) { + out.add(new Expansion(List.copyOf(path), atom, bottom)); return true; } + ancestors.add(atom); boolean proceed = true; for (Iterator members = reader.edge(atom).stream().iterator(); proceed && members.hasNext(); ) { long member = members.next().member(); diff --git a/database/src/test/java/io/hstore/db/DatabaseTest.java b/database/src/test/java/io/hstore/db/DatabaseTest.java index db9f4df2..d6c0c450 100644 --- a/database/src/test/java/io/hstore/db/DatabaseTest.java +++ b/database/src/test/java/io/hstore/db/DatabaseTest.java @@ -473,6 +473,10 @@ void expandFollowsEveryPathAndStaysWithinItsBudget() { hora.expand(top, 8, Budget.DEFAULT).toList()); assertEquals(List.of(new Hora.Expansion(List.of(loop, back, loop), loop, Hora.Expansion.Status.CYCLE)), hora.expand(loop, 8, Budget.DEFAULT).toList()); + assertEquals(List.of(new Hora.Expansion(List.of(loop, back, loop), loop, Hora.Expansion.Status.CYCLE)), + hora.expand(loop, 2, Budget.DEFAULT).toList()); + assertEquals(List.of(new Hora.Expansion(List.of(loop, back), back, Hora.Expansion.Status.DEPTH_LIMIT)), + hora.expand(loop, 1, Budget.DEFAULT).toList()); assertEquals(List.of( new Hora.Expansion(List.of(top, left, bottom), bottom, Hora.Expansion.Status.DEPTH_LIMIT), new Hora.Expansion(List.of(top, right, bottom), bottom, Hora.Expansion.Status.DEPTH_LIMIT)), diff --git a/docs/database/hora.md b/docs/database/hora.md index bdaff7f8..17778770 100644 --- a/docs/database/hora.md +++ b/docs/database/hora.md @@ -174,7 +174,7 @@ descends into members that are themselves hyperedges and emits leaves. | `DEPTH_LIMIT` | a hyperedge at the depth the query asked for; its members were not expanded, and everything above it is complete | | `BUDGET_EXHAUSTED` | the budget cut the traversal short: the row budget denied the next step and the traversal stopped, or the budget's depth cap (`budget.maxDepth`, lower than the requested depth) was reached on this path | -The effective depth is `min(d, budget.maxDepth)` (default 8); `LIMIT` sets the row budget. Every row the traversal +Through the Java API the effective depth is `min(d, budget.maxDepth)` (default 8). HQL `EXPAND … DEPTH d` sets both to `d` (1 to 64), so its bottom rows are always `DEPTH_LIMIT`; `LIMIT` sets the row budget. A hyperedge already on the path is reported as `CYCLE` even at the bottom, so a client that continues from `DEPTH_LIMIT` rows never walks into a cycle. Every row the traversal emits and every descent into a nested hyperedge takes one unit of the budget. When the budget refuses, one `BUDGET_EXHAUSTED` row marks where the traversal stopped and nothing more is emitted, so the output never exceeds the budget by more than that row, whatever the shape of the nesting.