parser

Documentation

Overview

Package parser houses the generated ANTLR4 lexer and parser for the Relational SQL dialect, plus the thin Go wrapper that wires them into a ParseTree suitable for consumption by the semantic analyzer.

The generated code lives under gen/. Regenerate with:

just generate-parser

That recipe is a thin wrapper around the Bazel target //pkg/relational/core/parser/grammar:generate_parser. Bazel fetches + caches the ANTLR 4.13.1 complete jar as an external repo (@antlr4_tool_jar, pinned by sha256 in MODULE.bazel; version must match the antlr4-go/antlr/v4 runtime in go.mod). The sh_binary runs the lexer first, then the parser with -lib pointing at the lexer's .tokens file, and drops the output into gen/.

CI gates generator drift via `just generate && git diff --exit-code`, so any change to the .g4 grammars must be accompanied by a fresh regeneration. `just generate-parser` is itself part of `just generate`.

The grammar files in grammar/ are copied near-verbatim from Java source at fdb-record-layer/fdb-relational-core/src/main/antlr/. There is one documented deviation: the Java-side ERROR_RECOGNITION lexer rule contained an inline Java action block which ANTLR's Go target copies literally and cannot compile. The action is removed in our copy with a NOTE comment explaining the change; default error listeners still surface unknown characters as "token recognition errors", so behaviour is preserved.

When re-syncing grammar from Java source: copy the files over, then delete the action block from the ERROR_RECOGNITION rule again.

Package parser — public wrapper around the ANTLR-generated Relational SQL parser and lexer. Consumers call Parse(sql) and receive a parse tree ready for the semantic analyzer.

Index

• func Parse(sql string) (ctx antlrgen.IRootContext, err error)
• func ParseExpression(sql string) (ctx antlrgen.IExpressionContext, err error)
• func ParseFunction(sql string) (ctx antlrgen.ISqlInvokedFunctionContext, err error)
• func ParseView(sql string) (ctx antlrgen.IQueryContext, err error)
• func ValidateNoPreparedParams(tree antlr.ParseTree) error

Functions

func Parse

func Parse(sql string) (ctx antlrgen.IRootContext, err error)

Parse runs the Relational SQL lexer + parser over sql and returns the resulting parse tree root. Keywords are matched case-insensitively; the original source casing is preserved in token text (identifiers, literals).

On failure Parse returns an *api.Error with Code == api.ErrCodeSyntaxError. The Message is of the form

syntax error:
<source line containing the offending token>
<spaces><^^^ underlining the token>

Matches Java's com.apple.foundationdb.relational.recordlayer.query. QueryParser.parse(): Java reports only the FIRST syntax error and runs ParseHelpers.underlineParsingError to produce the underline. Downstream errors after a syntax failure are usually cascade noise.

func ParseExpression

func ParseExpression(sql string) (ctx antlrgen.IExpressionContext, err error)

ParseExpression parses a bare boolean/scalar expression fragment and returns its IExpressionContext. Used to synthesize a JOIN ON predicate from a `USING (col, ...)` clause: the column list is lowered to the equivalent ON text (`col = rhs.col AND ...`) and re-parsed here so all downstream ON consumers (map-eval, cascades predicate resolution, explain) treat USING exactly like ON. Any ANTLR-internal panic on adversarial input is converted to a clean ErrCodeSyntaxError.

func ParseFunction

func ParseFunction(sql string) (ctx antlrgen.ISqlInvokedFunctionContext, err error)

ParseFunction parses a CREATE FUNCTION ... statement and returns the SqlInvokedFunction parse tree (the body after the CREATE keyword). Mirrors Java's QueryParser.parseFunction. The "CREATE" token is consumed before the sqlInvokedFunction rule runs because the grammar's sqlInvokedFunction starts after CREATE — so the token stream needs to be advanced once.

On empty or malformed input the pre-consumption of CREATE would otherwise panic ("cannot consume EOF" from ANTLR); guard by peeking the stream and reporting a clean syntax error instead.

func ParseView

func ParseView(sql string) (ctx antlrgen.IQueryContext, err error)

ParseView parses a view definition (the body of CREATE VIEW foo AS ...) and returns the query parse tree. Mirrors Java's QueryParser.parseView. Any ANTLR-internal panic on adversarial token streams is converted to a clean ErrCodeSyntaxError.

func ValidateNoPreparedParams

func ValidateNoPreparedParams(tree antlr.ParseTree) error

ValidateNoPreparedParams walks a parse tree and returns an error if any ? / $N prepared-statement placeholder is present. Mirrors Java's QueryParser.validateNoPreparedParams — certain contexts (function bodies, view definitions) reject parameters because binding happens at parse time, not execution time.