feat: GQL basic structure (#339)

* feat: Implement basic GQL structure and RETURN clause

- Add GQL AST nodes for GRAPH, RETURN, NEXT, and set operators
- Implement GQL parser with Lookahead and recursive descent
- Implement GQL unparser in ast/sql.go
- Add comprehensive test suite for basic GQL queries
- Enforce mandatory AS aliases in RETURN clauses in tests

* refactor(gql): Refine GQL AST node naming and field structures

- Rename GQL operational nodes to match SQL naming patterns (e.g., GQLReturnStatement -> GQLReturn)
- Simplify field names in compositional GQL nodes (e.g., Query, Statements, Items)
- Add BadGQLLinearQueryStatement and BadGQLPrimitiveQueryStatement for error recovery
- Update parser and unparser to reflect the refined AST structure
- Update generated files and test expectations

* gql: support RETURN * and mandatory AS for aliases in basic structure

* gql: rename property graph name to FinGraph in tests

* Fix ordering in ast.go

* Modify GQLReturnItem.Alias to AsAlias

* Refine parseGQLSimpleLinearQueryStatement

* Fix testdata

* Revert unintended diff

* Revert "Revert unintended diff"

This reverts commit 93052b4.

Author: apstndb

ast/ast.go

@@ -76,6 +76,7 @@ func (BadStatement) isStatement()        {}
 func (BadDDL) isStatement()              {}
 func (BadDML) isStatement()              {}
 func (QueryStatement) isStatement()      {}
+func (GQLGraphQuery) isStatement()       {}
 func (CreateSchema) isStatement()        {}
 func (DropSchema) isStatement()          {}
 func (CreateDatabase) isStatement()      {}
@@ -4324,3 +4325,128 @@ type Call struct {
 	Name *Path
 	Args []TVFArg // len(Args) > 0
 }
+
+// ================================================================================
+//
+// GQL
+//
+// ================================================================================
+
+// GQLLinearQueryStatement represents a linear query statement.
+type GQLLinearQueryStatement interface {
+	Node
+	isGQLLinearQueryStatement()
+}
+
+func (GQLSimpleLinearQueryStatement) isGQLLinearQueryStatement()   {}
+func (GQLCompoundLinearQueryStatement) isGQLLinearQueryStatement() {}
+func (BadGQLLinearQueryStatement) isGQLLinearQueryStatement()      {}
+
+// GQLPrimitiveQueryStatement represents a primitive query statement.
+type GQLPrimitiveQueryStatement interface {
+	Node
+	isGQLPrimitiveQueryStatement()
+}
+
+func (GQLReturn) isGQLPrimitiveQueryStatement()                     {}
+func (BadGQLPrimitiveQueryStatement) isGQLPrimitiveQueryStatement() {}
+
+// GQLGraphQuery is a top-level GQL query.
+//
+//	{{.Hint | sqlOpt}} {{.GraphClause | sql}} {{.Query | sql}}
+type GQLGraphQuery struct {
+	// pos = (Hint ?? GraphClause).pos
+	// end = Query.end
+
+	Hint        *Hint
+	GraphClause *GQLGraphClause
+
+	Query *GQLMultiLinearQueryStatement
+}
+
+// GQLGraphClause is a GRAPH clause in GQL.
+//
+//	GRAPH {{.PropertyGraphName | sql}}
+type GQLGraphClause struct {
+	// pos = Graph
+	// end = PropertyGraphName.end
+
+	Graph             token.Pos
+	PropertyGraphName *Path
+}
+
+// GQLMultiLinearQueryStatement is a list of linear query statements chained with NEXT.
+//
+//	{{.Statements | sqlJoin " NEXT "}}
+type GQLMultiLinearQueryStatement struct {
+	// pos = Statements[0].pos
+	// end = Statements[$].end
+
+	Statements []GQLLinearQueryStatement // len(Statements) > 0
+}
+
+// BadGQLLinearQueryStatement is a bad GQLLinearQueryStatement node.
+//
+//	{{.BadNode | sql}}
+type BadGQLLinearQueryStatement struct {
+	// pos = BadNode.pos
+	// end = BadNode.end
+
+	BadNode *BadNode
+}
+
+// GQLSimpleLinearQueryStatement is a list of primitive query statements that ends with RETURN.
+//
+//	{{.Statements | sqlJoin " "}}
+type GQLSimpleLinearQueryStatement struct {
+	// pos = Statements[0].pos
+	// end = Statements[$].end
+
+	Statements []GQLPrimitiveQueryStatement // len(Statements) > 0
+}
+
+// GQLCompoundLinearQueryStatement represents a list of linear query statements composited with the set operators.
+//
+//	{{.Statements | sqlJoin (printf " %s %s " .Op .AllOrDistinct)}}
+type GQLCompoundLinearQueryStatement struct {
+	// pos = Statements[0].pos
+	// end = Statements[$].end
+
+	Op            SetOp
+	AllOrDistinct AllOrDistinct
+	Statements    []GQLLinearQueryStatement // len(Statements) >= 2
+}
+
+// BadGQLPrimitiveQueryStatement is a bad GQLPrimitiveQueryStatement node.
+//
+//	{{.BadNode | sql}}
+type BadGQLPrimitiveQueryStatement struct {
+	// pos = BadNode.pos
+	// end = BadNode.end
+
+	BadNode *BadNode
+}
+
+// GQLReturn is a RETURN statement in GQL.
+//
+//	RETURN {{.AllOrDistinct | sqlOpt}} {{.Items | sqlJoin ", "}}
+type GQLReturn struct {
+	// pos = Return
+	// end = Items[$].end
+
+	Return        token.Pos
+	AllOrDistinct AllOrDistinct
+	Items         []*GQLReturnItem
+}
+
+// GQLReturnItem is an item in a RETURN statement.
+//
+//	{{.Expr | sql}}{{if .Alias}} {{.Alias | sqlOpt}}{{end}}
+type GQLReturnItem struct {
+	// pos = Star || Expr.pos
+	// end = Star + 1 || (Alias ?? Expr).end
+
+	Star  token.Pos
+	Expr  Expr
+	Alias *AsAlias // optional
+}

ast/pos.go

@@ -172,12 +172,14 @@ func (b *BadNode) SQL() string {
 	return sql
 }
 
-func (b *BadStatement) SQL() string { return sqlOpt("", b.Hint, " ") + b.BadNode.SQL() }
-func (b *BadQueryExpr) SQL() string { return b.BadNode.SQL() }
-func (b *BadExpr) SQL() string      { return b.BadNode.SQL() }
-func (b *BadType) SQL() string      { return b.BadNode.SQL() }
-func (b *BadDDL) SQL() string       { return b.BadNode.SQL() }
-func (b *BadDML) SQL() string       { return sqlOpt("", b.Hint, " ") + b.BadNode.SQL() }
+func (b *BadStatement) SQL() string                  { return sqlOpt("", b.Hint, " ") + b.BadNode.SQL() }
+func (b *BadQueryExpr) SQL() string                  { return b.BadNode.SQL() }
+func (b *BadExpr) SQL() string                       { return b.BadNode.SQL() }
+func (b *BadType) SQL() string                       { return b.BadNode.SQL() }
+func (b *BadDDL) SQL() string                        { return b.BadNode.SQL() }
+func (b *BadDML) SQL() string                        { return sqlOpt("", b.Hint, " ") + b.BadNode.SQL() }
+func (b *BadGQLLinearQueryStatement) SQL() string    { return b.BadNode.SQL() }
+func (b *BadGQLPrimitiveQueryStatement) SQL() string { return b.BadNode.SQL() }
 
 // ================================================================================
 //
@@ -1442,3 +1444,41 @@ func (u *UpdateItem) SQL() string {
 func (c *Call) SQL() string {
 	return "CALL " + c.Name.SQL() + "(" + sqlJoin(c.Args, ", ") + ")"
 }
+
+// ================================================================================
+//
+// GQL
+//
+// ================================================================================
+
+func (q *GQLGraphQuery) SQL() string {
+	return sqlOpt("", q.Hint, " ") + q.GraphClause.SQL() + " " + q.Query.SQL()
+}
+
+func (c *GQLGraphClause) SQL() string {
+	return "GRAPH " + c.PropertyGraphName.SQL()
+}
+
+func (s *GQLMultiLinearQueryStatement) SQL() string {
+	return sqlJoin(s.Statements, " NEXT ")
+}
+
+func (s *GQLSimpleLinearQueryStatement) SQL() string {
+	return sqlJoin(s.Statements, " ")
+}
+
+func (s *GQLCompoundLinearQueryStatement) SQL() string {
+	sep := " " + string(s.Op) + strOpt(s.AllOrDistinct != "", " "+string(s.AllOrDistinct)) + " "
+	return sqlJoin(s.Statements, sep)
+}
+
+func (s *GQLReturn) SQL() string {
+	return "RETURN " + strOpt(s.AllOrDistinct != "", string(s.AllOrDistinct)+" ") + sqlJoin(s.Items, ", ")
+}
+
+func (i *GQLReturnItem) SQL() string {
+	if !i.Star.Invalid() {
+		return "*"
+	}
+	return i.Expr.SQL() + sqlOpt(" ", i.Alias, "")
+}