gudusoft.gsqlparser.ir.semantic.binding

Interface NameBindingProvider

All Known Implementing Classes:

Resolver2NameBindingProvider

public interface NameBindingProvider

Boundary between the SQL parser/resolver world and the Semantic IR world.

The Semantic IR builder never reads TObjectName.getResolution() directly; it always asks a NameBindingProvider. This makes it possible to swap implementations (current: TSQLResolver2; future: Bound IR; tests: stub).

Method Summary

Modifier and Type	Method and Description
ColumnBinding	bindColumn(TObjectName columnRef) Resolve a column-typed TObjectName to a ColumnBinding.
RelationBinding	bindRelation(TTable table) Resolve a FROM-clause relation reference to a RelationBinding.
default Map<String,List<String>>	getInScopeRelationColumns() Slice 60 — return the in-scope relation column map last set via withInScopeRelationColumns(java.util.Map<java.lang.String, java.util.List<java.lang.String>>).
default List<String>	getRelationColumnNames(TTable table) Slice 58 — catalog-known column names for table in catalog declaration order, or null when no catalog information is available for this relation.
default UsingScope	getUsingScope() Slice 65 — return the using scope last set via withUsingScope(gudusoft.gsqlparser.ir.semantic.binding.UsingScope).
default boolean	isCalculatedProjectionAliasFallback(TObjectName columnRef, TSelectSqlStatement enclosingSelect) Slice 19 (alias-bound PARTITION BY discriminator).
default NameBindingProvider	withCteContext(Set<String> cteNamesInScope) Return a new provider configured for a CTE scope.
default NameBindingProvider	withInScopeRelationColumns(Map<String,List<String>> nameToColumns) Slice 60 — return a new provider scoped with a map of "in-scope relation alias → published column names" for the current consuming SELECT.
default NameBindingProvider	withSourceTableFallback(boolean enabled) Slice 93 — return a new provider that trusts Phase 1's linkColumnToTable-set TObjectName.getSourceTable() as an EXACT_MATCH when Phase 2 (TSQLResolver2) left TObjectName.getResolution() null.
default NameBindingProvider	withTolerantOuterBinding(Set<String> innerLocalAliasesLower) Slice 117 — return a new provider that admits qualified outer-scope column references as synthetic EXACT_MATCH bindings instead of letting them surface as NOT_FOUND.
default NameBindingProvider	withUsingScope(UsingScope scope) Slice 65 — return a new provider scoped with the UsingScope for the current SELECT body.

Method Detail

bindRelation

RelationBinding bindRelation(TTable table)

Resolve a FROM-clause relation reference to a RelationBinding. Returns null when the binding is not available (e.g. unresolved).

bindColumn

ColumnBinding bindColumn(TObjectName columnRef)

Resolve a column-typed TObjectName to a ColumnBinding. Returns null when the binding is not available; callers must then decide whether to treat that as a hard error.

withCteContext

default NameBindingProvider withCteContext(Set<String> cteNamesInScope)

Return a new provider configured for a CTE scope. The default returns the same instance, which means callers without CTE context behave unchanged. Implementations that distinguish CTE references from base tables should override this and return a per-scope copy.

The set is treated as case-insensitive by convention; callers should pass already-lowercased CTE names.

isCalculatedProjectionAliasFallback

default boolean isCalculatedProjectionAliasFallback(TObjectName columnRef,
                                                    TSelectSqlStatement enclosingSelect)

Slice 19 (alias-bound PARTITION BY discriminator). True when columnRef is an unqualified column reference whose binding lacks definite FROM-scope evidence AND whose name (case-insensitive) matches a calculated-expression alias in the directly-enclosing SELECT's result-column list.

Used by the IR builder to reject alias-bound PARTITION BY refs that today bind heuristically to a base table (e.g. salary*2 AS doubled, PARTITION BY doubled → resolver synthesises employees.doubled via inferred_from_usage). Without schema metadata the resolver cannot tell whether the name is an alias or a real shadowing column; slice 19 chooses conservative rejection over silent guess.

The default returns false so providers without resolver state fall through transparently. Resolver2NameBindingProvider overrides this with the real check (unqualified-only + !hasDefiniteEvidence() + AST walk over enclosingSelect.getResultColumnList() for a calculated alias of the same name).

Parameters:

columnRef - the column-typed AST node being inspected

enclosingSelect - the SELECT statement whose result columns define the alias scope; the builder already holds this and passes it in (avoids context-dependent walks inside the resolver layer)

Returns:

true to reject this reference as alias-bound; false otherwise

withInScopeRelationColumns

default NameBindingProvider withInScopeRelationColumns(Map<String,List<String>> nameToColumns)

Slice 60 — return a new provider scoped with a map of "in-scope relation alias → published column names" for the current consuming SELECT. Used by SemanticIRBuilder.tryExpandStar to expand SELECT * / SELECT alias.* when the FROM-clause relation binds to a CTE or a FROM-subquery body already built earlier in the same build() invocation.

Semantics are REPLACE, not merge: callers always pass the complete visible map for the scope. Implementations must defensively copy and lower-case keys; values should be made unmodifiable. The default returns the same instance (no-op).

withCteContext(Set) and withInScopeRelationColumns are independent facets of the same per-scope provider context. Implementations must preserve the other facet's state across each narrower call.

getInScopeRelationColumns

default Map<String,List<String>> getInScopeRelationColumns()

Slice 60 — return the in-scope relation column map last set via withInScopeRelationColumns(java.util.Map<java.lang.String, java.util.List<java.lang.String>>). Default returns an empty map.

getRelationColumnNames

default List<String> getRelationColumnNames(TTable table)

Slice 58 — catalog-known column names for table in catalog declaration order, or null when no catalog information is available for this relation.

Used by SemanticIRBuilder.tryExpandStar to expand SELECT * and SELECT alias.* projections into per- column OutputColumns, each carrying a ColumnRef to the underlying base column.

Default returns null so providers without catalog access fall through transparently and the builder emits a structured unsupported diagnostic. Resolver2NameBindingProvider overrides this when constructed with a non-null TSQLEnv.

Implementations must not return an empty list to mean "catalog known but no columns"; an empty list is treated identically to null (no usable catalog) by the builder.

Parameters:

table - the FROM-clause relation node being expanded; never null in practice (the builder filters out null tables before calling)

Returns:

column-name list in declaration order, or null when no catalog metadata is available

withUsingScope

default NameBindingProvider withUsingScope(UsingScope scope)

Slice 65 — return a new provider scoped with the UsingScope for the current SELECT body. Used by collectors and SemanticIRBuilder.expandBareStarOverUsing to resolve unqualified merged-key references to the merged source list.

Semantics are REPLACE, not merge: each buildSelectStatementImpl invocation MUST call this with UsingScope.EMPTY at entry so an enclosing SELECT's USING cannot leak into recursive nested builds (predicate-subquery bodies, scalar-subquery bodies, set-op branch bodies, CTE bodies, FROM-subquery bodies all see only their own scope).

withCteContext(java.util.Set), withInScopeRelationColumns(java.util.Map), and withUsingScope are independent facets of the same per-scope provider context. Implementations must preserve the other facets' state across each narrower call.

Default returns the same instance (no-op).

getUsingScope

default UsingScope getUsingScope()

Slice 65 — return the using scope last set via withUsingScope(gudusoft.gsqlparser.ir.semantic.binding.UsingScope). Default returns UsingScope.EMPTY.

withSourceTableFallback

default NameBindingProvider withSourceTableFallback(boolean enabled)

Slice 93 — return a new provider that trusts Phase 1's linkColumnToTable-set TObjectName.getSourceTable() as an EXACT_MATCH when Phase 2 (TSQLResolver2) left TObjectName.getResolution() null. Used for Hive multi-insert sub-SELECT bodies whose secondary branches are not traversed by Resolver2 during TGSqlParser.parse(); without the fallback, those branches would universally fail with NOT_FOUND.

Safety: the fallback fires only when resolution == null (proves Phase 2 did not run, NOT that it explicitly rejected) AND the column's SQL-written qualifier (if any) is consistent with Phase 1's chosen source table — the implementation verifies the qualifier matches the source's name or alias case-insensitively before promoting.

Default returns the same instance (no-op).

withTolerantOuterBinding

default NameBindingProvider withTolerantOuterBinding(Set<String> innerLocalAliasesLower)

Slice 117 — return a new provider that admits qualified outer-scope column references as synthetic EXACT_MATCH bindings instead of letting them surface as NOT_FOUND. Used by the UPDATE SET-RHS scalar-subquery extractor so a correlated outer reference like t.k (where t is the UPDATE target or a FROM-side outer relation, NOT inside the inner SELECT's FROM list) survives appendMergedOrBoundColumnRef's strict non-EXACT_MATCH reject. The slice-11 promoteCorrelatedRefsToOuterReference then sees the ref's alias and synthesises an OUTER_REFERENCE relation.

The innerLocalAliasesLower argument scopes the fallback: a qualified ref whose qualifier IS in the inner local aliases is NOT promoted (typos like t.bad_col where t is the inner FROM alias still reject with COLUMN_BINDING_NON_EXACT — they are real errors). Unqualified refs are NOT promoted (their binding remains ambiguous between inner and outer).

Passing an empty or null set disables the fallback (no-op).

Default returns the same instance (no-op).