Module com.darkcollective.relix.symbol

Package com.darkcollective.relix.symbol.graph.internal

Class SchemaGraphSearch

java.lang.Object

com.darkcollective.relix.symbol.graph.internal.SchemaGraphSearch

public final class SchemaGraphSearch
extends Object

Minimal-path (Steiner-tree) search over a SchemaGraph.

Given the terminals a request touches (the relations owning the columns it names), the join Relix must build is the minimal connected subgraph of the schema graph spanning them. This is a Steiner tree over a small graph, where exhaustive enumeration is cheap: the search grows connected edge-sets outward from the terminals a breadth at a time, so the first breadth that spans every terminal yields all minimal-size paths at once.

• Exactly one minimal path → PathSearchResult.unique(); assemble it mechanically. The model never guesses the join.
• Several equally minimal paths → PathSearchResult.ambiguous(); the two-FK issues → users case. Enumerated by relationship name for a "did you mean?".
• Terminals in different components → PathSearchResult.disconnected().

Minimality = fewest edges = fewest tables. A tree connecting a fixed set of relations has one fewer edge than it has nodes, so minimising edges minimises intermediate tables — exactly the "minimise the number of tables in the resultant relation" goal.

Derived endpoints participate only when nominated (§1.5 (ii)). A QueryRelationSymbol node is excluded from the search unless it is a terminal (the request named it) or listed in the nominated set. So an un-nominated "active orders" view never competes with its base relation, while a nominated one does — the base-vs-view gate whose preference policy is item 4.

Self-referential edges (org hierarchies, symmetric cross-sells) are loops that connect no new relation, so they never appear in a minimal tree. Resolving an explicit self-join is a nomination the model must make (it names the relationship), which is out of scope for terminal-driven search; the search simply tolerates such edges rather than mis-selecting them.

Method Summary

Modifier and Type	Method	Description
static PathSearchResult	search(SchemaGraph graph, Collection<? extends RelationSymbol> terminals)	Searches with no nominated derived endpoints (base relations only).
static PathSearchResult	search(SchemaGraph graph, Collection<? extends RelationSymbol> terminals, Collection<? extends RelationSymbol> nominated)	Enumerates the minimal connected subgraph(s) spanning terminals.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

search

public static PathSearchResult search(SchemaGraph graph,
 Collection<? extends RelationSymbol> terminals)

Searches with no nominated derived endpoints (base relations only).

search

public static PathSearchResult search(SchemaGraph graph,
 Collection<? extends RelationSymbol> terminals,
 Collection<? extends RelationSymbol> nominated)

Enumerates the minimal connected subgraph(s) spanning terminals.

Parameters:

graph - the schema graph to search

terminals - the relations the query touches; deduplicated by graph key

nominated - derived (QueryRelationSymbol) relations permitted to participate as path nodes (§1.5 (ii)); base relations always participate

Returns:

the search outcome — unique, ambiguous, or disconnected