gudusoft.gsqlparser.ir.semantic

Class SqlSemanticAnalyzer

Object

gudusoft.gsqlparser.ir.semantic.SqlSemanticAnalyzer

public final class SqlSemanticAnalyzer
extends Object

Public service wrapper for the Semantic IR pipeline. Given a SQL string and a vendor (and optionally a catalog), returns an AnalysisResult carrying the built SemanticProgram, its JSON encoding, and any Diagnostics emitted during analysis.

Slice 75 introduced the packaging surface; slice 76 added the Catalog DTO overload so external callers can supply catalog metadata without depending on the internal TSQLEnv type. Neither slice changes semantic behaviour — the pipeline is:

1. TGSqlParser with EResolverType.RESOLVER2;
2. SemanticIRBuilder.build(gudusoft.gsqlparser.stmt.TSelectSqlStatement, gudusoft.gsqlparser.ir.semantic.binding.NameBindingProvider) with a Resolver2NameBindingProvider (wired to the catalog when one is supplied);
3. SemanticIRJsonExporter.toJson(gudusoft.gsqlparser.ir.semantic.SemanticProgram) for the JSON form.

Slice 75 supports a single SELECT statement per analyze(java.lang.String, gudusoft.gsqlparser.EDbVendor) call. Parse failures, multi-statement input, non-SELECT input, and builder rejections all surface as structured Diagnostics on the result (never as exceptions for the documented failure modes). Unexpected runtime failures inside the analyzer propagate as RuntimeExceptions so bugs fail loudly rather than being silently bound to a stable diagnostic message.

External callers should branch on AnalysisResult.isSuccessful() and pattern-match on Diagnostic.getCode() (DiagnosticCode is the stable contract); message text remains user-visible English and may change without notice.

Overload-resolution note. The two 3-arg overloads accept Catalog or TSQLEnv; the types are unrelated, so passing a literal null third argument is ambiguous at compile time. Callers who have no catalog should use the 2-arg analyze(String, EDbVendor) overload.

This class is stateless and its static methods are safe to call from multiple threads.

Method Summary

Modifier and Type	Method and Description
static AnalysisResult	analyze(String sql, EDbVendor vendor) Convenience overload — equivalent to analyze(sql, vendor, (TSQLEnv) null).
static AnalysisResult	analyze(String sql, EDbVendor vendor, Catalog catalog) Slice 76 — analyze a single SELECT statement using catalog metadata supplied as a Catalog DTO instead of a TSQLEnv.
static AnalysisResult	analyze(String sql, EDbVendor vendor, TSQLEnv catalog) Analyze a single SELECT statement using catalog metadata supplied as a TSQLEnv.
static String	schemaVersion() Current JSON schema version emitted by this analyzer.

Methods inherited from class Object

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

Method Detail

schemaVersion

public static String schemaVersion()

Current JSON schema version emitted by this analyzer.

Implemented as a method (not a public static final String constant) so binary consumers compiled against one version of this library do NOT silently see the old value after a drop-in JAR upgrade — Java compile-time inlining of String constants would otherwise break the version contract (codex diff-review round-1 Q3).

The returned value is always equal to SemanticIRJsonExporter.SCHEMA_VERSION.

analyze

public static AnalysisResult analyze(String sql,
                                     EDbVendor vendor)

Convenience overload — equivalent to analyze(sql, vendor, (TSQLEnv) null).

Use this when no catalog metadata is available. Slice 76 extracted the no-catalog delegation through a private helper so the 2-arg call remains unambiguous after the Catalog overload was added.

analyze

public static AnalysisResult analyze(String sql,
                                     EDbVendor vendor,
                                     TSQLEnv catalog)

Analyze a single SELECT statement using catalog metadata supplied as a TSQLEnv.

Slice 75's original catalog entry point. Retained as the authoritative pipeline input — slice 76's Catalog overload bridges to a generated TSQLEnv internally so identifier semantics (case folding, qualifier expansion, vendor rules) flow through one code path only.

Failure modes that return a structured result (never throw):

• parse failure (rc != 0) → DiagnosticCode.PARSE_FAILED;
• empty statement list (parse rc=0 but no statements) → DiagnosticCode.PARSE_FAILED;
• more than one statement → DiagnosticCode.MULTIPLE_STATEMENTS_NOT_SUPPORTED;
• first statement is not a TSelectSqlStatement → DiagnosticCode.STATEMENT_KIND_NOT_SUPPORTED;
• builder rejection (SemanticIRBuilder.SemanticIRBuildException) → the diagnostic from the exception.

Genuine programming errors throw IllegalArgumentException (null sql or null vendor). Unexpected RuntimeExceptions from the builder propagate to the caller.

Parameters:

sql - non-null SQL text (single statement; trailing statements yield DiagnosticCode.MULTIPLE_STATEMENTS_NOT_SUPPORTED)

vendor - non-null vendor enum

catalog - optional TSQLEnv for catalog-backed resolution; pass null to disable catalog lookups (star expansion and similar catalog-required features will be rejected with their existing slice-58 / 66 diagnostics). See the overload-resolution note in the class javadoc — to pass a literal null, use the 2-arg analyze(String, EDbVendor) overload instead.

Returns:

immutable result with program, json, and diagnostics

analyze

public static AnalysisResult analyze(String sql,
                                     EDbVendor vendor,
                                     Catalog catalog)

Slice 76 — analyze a single SELECT statement using catalog metadata supplied as a Catalog DTO instead of a TSQLEnv.

The DTO is converted to a TSQLEnv internally; all resolver / identifier behaviour is identical to the TSQLEnv-flavored overload. The point of this overload is purely to keep the internal TSQLEnv type off the public API surface for external callers.

A null Catalog is treated as "no catalog" (equivalent to the 2-arg analyze(String, EDbVendor) overload). Note that to pass a literal null you must use the 2-arg overload — see the overload-resolution note in the class javadoc.

Parameters:

sql - non-null SQL text

vendor - non-null vendor enum

catalog - optional DTO catalog (may be null when the caller has already typed the reference as Catalog)

Returns:

immutable result with program, json, and diagnostics

Since:

slice 76