gudusoft.gsqlparser.ir.semantic.binding

Class UsingScope

Object

gudusoft.gsqlparser.ir.semantic.binding.UsingScope

public final class UsingScope
extends Object

Slice 65 — per-SELECT merged-key scope for JOIN ... USING.

Slice 64 admitted JOIN ... USING (k) at the predicate side (joinColumnRefs). Slice 65 lifts the output / non-JOIN-ON clause side: unqualified references to a USING merged key (in SELECT / WHERE / GROUP BY / HAVING / ORDER BY) resolve to the merged source list of every relation in the USING(k) equivalence class.

Equivalence classes are per-key (DSU over USING joins); multiple disconnected classes can exist for the same key name. has(java.lang.String) tells whether a name is a USING key; isAmbiguous(java.lang.String) signals either disconnected-class ambiguity or an out-of-class same-named column (caller throws with ambiguityReason(java.lang.String)).

Each SemanticIRBuilder.buildSelectStatementImpl invocation resets its provider's using scope to EMPTY at entry, then optionally narrows the provider with its own scope. This prevents an enclosing SELECT's USING from leaking into recursive nested builds (predicate-subquery bodies, scalar-subquery bodies, set-op branch bodies, CTE bodies, FROM-subquery bodies).

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	UsingScope.EquivalenceClass One equivalence class of FROM-clause relations connected by a specific USING key.
static class	UsingScope.MergedKeyEntry One merged-key entry: a class and its FROM-ordered merged source column refs (narrowed by catalog when available).

Field Summary

Fields

Modifier and Type	Field and Description
static UsingScope	EMPTY

Constructor Summary

Constructors

Constructor and Description
UsingScope(Map<String,List<UsingScope.MergedKeyEntry>> entriesByName, Map<String,String> ambiguityReasonByName)
UsingScope(Map<String,List<UsingScope.MergedKeyEntry>> entriesByName, Map<String,String> ambiguityReasonByName, List<String> naturalDegradeRelations)

Method Summary

Modifier and Type	Method and Description
String	ambiguityReason(String name) Diagnostic text for an ambiguous name.
List<UsingScope.MergedKeyEntry>	entriesFor(String name) All entries for a USING key.
UsingScope.MergedKeyEntry	entryContaining(String name, TTable table) Returns the UsingScope.MergedKeyEntry whose equivalence class contains table by object identity, or null if table is not in any class for name.
boolean	has(String name) True iff name matches a USING key in this scope (case-insensitive).
boolean	hasMergedKeys() True iff this scope carries at least one merged-key equivalence class — i.e.
boolean	hasNaturalDegrade() True iff this FROM clause contains a catalog-less NATURAL JOIN whose shared keys could not be enumerated, enabling the degrade fallback for unqualified column references.
boolean	isAmbiguous(String name) True iff a bare unqualified name reference is ambiguous — either because two disconnected USING classes carry the same key name, or because catalog declares the same column on a relation outside the (single) equivalence class.
boolean	isEmpty() Whether this scope carries no information at all — neither merged-key entries nor a NATURAL-degrade fallback.
List<ColumnRef>	mergedSourcesFor(String name) Flattened sources of the SINGLE entry for name.
String	naturalDegradeFallbackAlias() The deterministic left-side relation alias to which an unbindable unqualified reference degrades, or null when there is no NATURAL-degrade fallback.

Methods inherited from class Object

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

Field Detail

EMPTY

public static final UsingScope EMPTY

Constructor Detail

UsingScope

public UsingScope(Map<String,List<UsingScope.MergedKeyEntry>> entriesByName,
                  Map<String,String> ambiguityReasonByName)

UsingScope

public UsingScope(Map<String,List<UsingScope.MergedKeyEntry>> entriesByName,
                  Map<String,String> ambiguityReasonByName,
                  List<String> naturalDegradeRelations)

Method Detail

has

public boolean has(String name)

True iff name matches a USING key in this scope (case-insensitive).

isAmbiguous

public boolean isAmbiguous(String name)

True iff a bare unqualified name reference is ambiguous — either because two disconnected USING classes carry the same key name, or because catalog declares the same column on a relation outside the (single) equivalence class.

ambiguityReason

public String ambiguityReason(String name)

Diagnostic text for an ambiguous name. Returns null when not ambiguous.

entriesFor

public List<UsingScope.MergedKeyEntry> entriesFor(String name)

All entries for a USING key. Empty when !has(name).

entryContaining

public UsingScope.MergedKeyEntry entryContaining(String name,
                                                 TTable table)

Returns the UsingScope.MergedKeyEntry whose equivalence class contains table by object identity, or null if table is not in any class for name.

TTable instances do not override equals, so identity check is the only safe membership test.

mergedSourcesFor

public List<ColumnRef> mergedSourcesFor(String name)

Flattened sources of the SINGLE entry for name.

Throws:

IllegalStateException - when the scope has zero or multiple entries for name — callers must check has(java.lang.String) and isAmbiguous(java.lang.String) first.

isEmpty

public boolean isEmpty()

Whether this scope carries no information at all — neither merged-key entries nor a NATURAL-degrade fallback. Callers install the scope on the provider only when this is false.

hasMergedKeys

public boolean hasMergedKeys()

True iff this scope carries at least one merged-key equivalence class — i.e. the FROM clause has a JOIN ... USING (or a catalog-resolved NATURAL JOIN) that produced merged keys. Distinct from hasNaturalDegrade(), which covers the catalog-less NATURAL case where no keys could be enumerated. Used to anchor the degrade of an otherwise-fatal unqualified column-binding miss: a USING join is a structural reason an unqualified non-key column cannot be placed without a catalog, so the analysis degrades rather than aborts.

hasNaturalDegrade

public boolean hasNaturalDegrade()

True iff this FROM clause contains a catalog-less NATURAL JOIN whose shared keys could not be enumerated, enabling the degrade fallback for unqualified column references. See naturalDegradeRelations.

naturalDegradeFallbackAlias

public String naturalDegradeFallbackAlias()

The deterministic left-side relation alias to which an unbindable unqualified reference degrades, or null when there is no NATURAL-degrade fallback. This is the first (leftmost in FROM order) NATURAL-join relation.