feat: support GRAPH_TABLE operator

ast/ast.go

@@ -189,6 +189,7 @@ func (SubQueryTableExpr) isTableExpr() {}
 func (ParenTableExpr) isTableExpr()    {}
 func (Join) isTableExpr()              {}
 func (TVFCallExpr) isTableExpr()       {}
+func (GraphTableExpr) isTableExpr()    {}
 
 // JoinCondition represents condition part of JOIN expression.
 type JoinCondition interface {
@@ -4659,6 +4660,55 @@ func (GQLLimit) isGQLPrimitiveQueryStatement()                      {}
 func (GQLOffset) isGQLPrimitiveQueryStatement()                     {}
 func (BadGQLPrimitiveQueryStatement) isGQLPrimitiveQueryStatement() {}
 
+// GraphTableQuery represents a query body in a GRAPH_TABLE operator.
+type GraphTableQuery interface {
+	Node
+	isGraphTableQuery()
+}
+
+func (GQLMultiLinearQueryStatement) isGraphTableQuery() {}
+func (GraphTableMatch) isGraphTableQuery()              {}
+
+// GraphTableExpr represents GRAPH_TABLE operator in SQL.
+//
+//	GRAPH_TABLE({{.GraphName | sql}} {{.Query | sql}}) {{.As | sqlOpt}} {{.Sample | sqlOpt}}
+type GraphTableExpr struct {
+	// pos = GraphTable
+	// end = (Sample ?? As).end || Rparen + 1
+
+	GraphTable token.Pos // position of "GRAPH_TABLE"
+	Rparen     token.Pos // position of ")"
+
+	GraphName *Path
+	Query     GraphTableQuery
+	As        *AsAlias     // optional
+	Sample    *TableSample // optional
+}
+
+// GraphTableMatch represents the SQL/PGQ form of a GRAPH_TABLE query.
+//
+//	{{.Match | sql}} {{.Columns | sqlOpt}}
+type GraphTableMatch struct {
+	// pos = Match.pos
+	// end = (Columns ?? Match).end
+
+	Match   *GQLMatch
+	Columns *GraphTableColumns // optional
+}
+
+// GraphTableColumns is a COLUMNS shape clause in a GRAPH_TABLE query.
+//
+//	COLUMNS({{.Items | sqlJoin ", "}})
+type GraphTableColumns struct {
+	// pos = Columns
+	// end = Rparen + 1
+
+	Columns token.Pos // position of "COLUMNS"
+	Rparen  token.Pos // position of ")"
+
+	Items []SelectItem // len(Items) > 0
+}
+
 // GQLGraphQuery is a top-level GQL query.
 //
 //	{{.Hint | sqlOpt}} {{.GraphClause | sql}} {{.Query | sql}}

ast/sql.go

@@ -1540,6 +1540,18 @@ func (c *Call) SQL() string {
 //
 // ================================================================================
 
+func (n *GraphTableExpr) SQL() string {
+	return "GRAPH_TABLE(" + n.GraphName.SQL() + " " + n.Query.SQL() + ")" + sqlOpt(" ", n.As, "") + sqlOpt(" ", n.Sample, "")
+}
+
+func (m *GraphTableMatch) SQL() string {
+	return m.Match.SQL() + sqlOpt(" ", m.Columns, "")
+}
+
+func (c *GraphTableColumns) SQL() string {
+	return "COLUMNS(" + sqlJoin(c.Items, ", ") + ")"
+}
+
 func (q *GQLGraphQuery) SQL() string {
 	return sqlOpt("", q.Hint, " ") + q.GraphClause.SQL() + " " + q.Query.SQL()
 }

parser.go

@@ -1210,6 +1210,22 @@ func (p *Parser) parseSimpleTableExpr() ast.TableExpr {
 		return p.parseUnnestSuffix(expr, unnest, rparen)
 	}
 
+	if p.Token.Kind == "GRAPH_TABLE" {
+		graphTable := p.expect("GRAPH_TABLE").Pos
+		p.expect("(")
+		graphName := p.parsePath()
+		query := p.parseGraphTableQuery()
+		rparen := p.expect(")").Pos
+		as := p.tryParseAsAlias(withOptionalAs)
+		return p.parseTableExprSuffix(&ast.GraphTableExpr{
+			GraphTable: graphTable,
+			GraphName:  graphName,
+			Query:      query,
+			Rparen:     rparen,
+			As:         as,
+		})
+	}
+
 	if p.Token.Kind == token.TokenIdent {
 		ids := p.parseIdentOrPath()
 		if p.Token.Kind == "(" {
@@ -1221,7 +1237,52 @@ func (p *Parser) parseSimpleTableExpr() ast.TableExpr {
 		return p.parsePathTableExprSuffix(&ast.Path{Idents: ids})
 	}
 
-	panic(p.errorfAtToken(&p.Token, "expected token: (, UNNEST, <ident>, but: %s", p.Token.Kind))
+	panic(p.errorfAtToken(&p.Token, "expected token: (, UNNEST, GRAPH_TABLE, <ident>, but: %s", p.Token.Kind))
+}
+
+func (p *Parser) parseGraphTableQuery() ast.GraphTableQuery {
+	// A single MATCH followed by COLUMNS or the GRAPH_TABLE closing parenthesis
+	// is the SQL/PGQ form. Other MATCH forms are advanced GQL query blocks.
+	if p.lookaheadGraphTableMatch() {
+		return p.parseGraphTableMatch()
+	}
+	return p.parseGQLMultiLinearQueryStatement()
+}
+
+func (p *Parser) lookaheadGraphTableMatch() bool {
+	if !p.Token.IsKeywordLike("MATCH") {
+		return false
+	}
+
+	lexer := p.cloneLexer()
+	defer func() { p.Lexer = lexer }()
+
+	p.parseGQLMatch()
+	return p.Token.IsKeywordLike("COLUMNS") || p.Token.Kind == ")"
+}
+
+func (p *Parser) parseGraphTableMatch() *ast.GraphTableMatch {
+	match := p.parseGQLMatch()
+	var columns *ast.GraphTableColumns
+	if p.Token.IsKeywordLike("COLUMNS") {
+		columns = p.parseGraphTableColumns()
+	}
+	return &ast.GraphTableMatch{
+		Match:   match,
+		Columns: columns,
+	}
+}
+
+func (p *Parser) parseGraphTableColumns() *ast.GraphTableColumns {
+	columns := p.expectKeywordLike("COLUMNS").Pos
+	p.expect("(")
+	items := parseCommaSeparatedList(p, p.parseSelectItem)
+	rparen := p.expect(")").Pos
+	return &ast.GraphTableColumns{
+		Columns: columns,
+		Rparen:  rparen,
+		Items:   items,
+	}
 }
 
 func (p *Parser) parseTVFCallExpr(ids []*ast.Ident) *ast.TVFCallExpr {
@@ -1395,6 +1456,8 @@ func (p *Parser) parseTableExprSuffix(join ast.TableExpr) ast.TableExpr {
 		j.Sample = sample
 	case *ast.ParenTableExpr:
 		j.Sample = sample
+	case *ast.GraphTableExpr:
+		j.Sample = sample
 	default:
 		panic(fmt.Sprintf("BUG: unexpected join: %#v", join))
 	}

testdata/input/query/!bad_graph_table_return_columns.sql

@@ -0,0 +1 @@
+SELECT * FROM GRAPH_TABLE (FinGraph MATCH (n:Person) RETURN n COLUMNS (n.id))

testdata/input/query/graph_table_alias.sql

@@ -0,0 +1 @@
+SELECT t.v FROM GRAPH_TABLE (FinGraph LET x = 1 RETURN x AS v) t

testdata/input/query/graph_table_as_alias.sql

@@ -0,0 +1 @@
+SELECT t.v FROM GRAPH_TABLE (FinGraph LET x = 1 RETURN x AS v) AS t TABLESAMPLE BERNOULLI (10 PERCENT)

testdata/input/query/graph_table_join.sql

@@ -0,0 +1,4 @@
+SELECT a.id, g.v
+FROM Accounts AS a
+JOIN GRAPH_TABLE (FinGraph LET x = 1 RETURN x AS v) AS g
+ON a.id = g.v

testdata/input/query/graph_table_match_columns.sql

@@ -0,0 +1 @@
+SELECT name, number FROM GRAPH_TABLE (FinGraph MATCH (n:Person) COLUMNS (n.name AS name, 1 AS number))

testdata/input/query/graph_table_match_columns_dot_star.sql

@@ -0,0 +1 @@
+SELECT * FROM GRAPH_TABLE (FinGraph MATCH (n:Person) COLUMNS (n.*, 1 AS number))

testdata/input/query/graph_table_match_no_columns.sql

@@ -0,0 +1 @@
+SELECT n.id FROM GRAPH_TABLE (FinGraph MATCH (n:Person)) AS g

testdata/input/query/graph_table_match_return.sql

@@ -0,0 +1 @@
+SELECT id FROM GRAPH_TABLE (FinGraph MATCH (n:Person) RETURN n.id AS id)

testdata/input/query/graph_table_minimal.sql

@@ -0,0 +1 @@
+SELECT * FROM GRAPH_TABLE (FinGraph LET x = 1 RETURN x AS v)

testdata/input/query/graph_table_next.sql

@@ -0,0 +1 @@
+SELECT * FROM GRAPH_TABLE (FinGraph LET a = 1 RETURN a AS x NEXT FILTER WHERE x > 0 RETURN x) AS t

testdata/input/query/graph_table_qualified_graph.sql

@@ -0,0 +1 @@
+SELECT * FROM GRAPH_TABLE (schema.FinGraph FILTER WHERE TRUE RETURN 1 AS v) AS t

testdata/input/query/graph_table_tablesample.sql

@@ -0,0 +1,6 @@
+SELECT *
+FROM GRAPH_TABLE(
+  FinGraph
+  LET x = 1
+  RETURN x AS v
+) TABLESAMPLE BERNOULLI (10 PERCENT)