gudusoft.gsqlparser.ir.semantic.builder

Class SemanticIRBuildOptions

Object

gudusoft.gsqlparser.ir.semantic.builder.SemanticIRBuildOptions

public final class SemanticIRBuildOptions
extends Object

Caller-supplied knobs for a SemanticIRBuilder.build* invocation.

Immutable; instances are created from defaults() and refined with the with* copiers. The no-options build* overloads behave exactly as defaults(), so existing callers are unaffected.

Degrade mode

By default the builder is all-or-nothing: a construct it does not support anywhere in the statement aborts the whole build* call with a SemanticIRBuilder.SemanticIRBuildException, and the caller loses the analysis of the blocks that were fully understood. With degrade mode enabled, an unsupported nested block is instead reported as a Diagnostic and the rest of the statement is still returned.

Degrade mode is deliberately narrow. It applies only to blocks the surrounding statement does not depend on for its own shape — today, the lifted body of a predicate subquery (EXISTS (...), IN (SELECT ...), a comparison / ANY / ALL against a subquery). Those bodies are emitted as their own StatementGraph and are unreachable from the host block: no relation points at them and no lineage edge targets them, so dropping one cannot change a single fact the host block publishes.

It does not apply to a failure in the host block itself, nor to CTE bodies, FROM-clause subqueries or scalar-subquery projections — the host block's relations, output columns and lineage are derived from those, so skipping one would publish a host block that looks complete while silently missing sources. Those keep throwing.

A degraded block is never dropped silently. It is replaced, in the same position of SemanticProgram.getStatements(), by a placeholder whose StatementGraph.getKind() is and whose StatementGraph.getUnanalyzedReason() carries the original Diagnostic — code, message and, when the AST could be anchored, the SourceSpan of the offending block. The same diagnostic is returned atomically by the builder's build*Result methods and therefore appears in AnalysisResult.getDiagnostics() too. Legacy build* callers can still obtain the compatibility snapshot through SemanticIRBuilder.drainBuildDiagnostics().

API status: advanced/preview. Callers using these options own the low-level parsing, resolver, provider, diagnostics, and recovery contract. Prefer SqlSemanticAnalyzer for the supported SQL-text pipeline.

See Also:

StatementGraph.isUnanalyzed()

Method Summary

Modifier and Type	Method and Description
static SemanticIRBuildOptions	defaults()
boolean	equals(Object o)
int	hashCode()
boolean	isDegradeUnsupportedNestedBlocks()
String	toString()
SemanticIRBuildOptions	withDegradeUnsupportedNestedBlocks(boolean degrade)

Methods inherited from class Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Method Detail

defaults

public static SemanticIRBuildOptions defaults()

Returns:

the default options — degrade mode off, i.e. the historical all-or-nothing behaviour of the two-argument build* overloads.

withDegradeUnsupportedNestedBlocks

public SemanticIRBuildOptions withDegradeUnsupportedNestedBlocks(boolean degrade)

Parameters:

degrade - true to report an unsupported nested predicate subquery body as a diagnostic plus an placeholder instead of aborting the build

Returns:

a copy of these options with the flag set

isDegradeUnsupportedNestedBlocks

public boolean isDegradeUnsupportedNestedBlocks()

equals

public boolean equals(Object o)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

toString

public String toString()

Overrides:

toString in class Object