From 9fa41fe4b961789b998bad76171cafcf6f49b4e9 Mon Sep 17 00:00:00 2001
From: Ashutosh Bapat <ashutosh.bapat.oss@gmail.com>
Date: Wed, 25 Feb 2026 19:03:43 +0530
Subject: [PATCH v20260226 2/4] Add comments to parse_graphtable.c

... describing functionality of transform* functions in that file.
---
 src/backend/parser/parse_clause.c     |  5 +++++
 src/backend/parser/parse_graphtable.c | 30 +++++++++++++++++++++++++++
 2 files changed, 35 insertions(+)

diff --git a/src/backend/parser/parse_clause.c b/src/backend/parser/parse_clause.c
index 85904198c05..967eea44f1c 100644
--- a/src/backend/parser/parse_clause.c
+++ b/src/backend/parser/parse_clause.c
@@ -967,6 +967,11 @@ transformRangeGraphTable(ParseState *pstate, RangeGraphTable *rgt)
 
 	gp = transformGraphPattern(pstate, rgt->graph_pattern);
 
+	/*
+	 * Construct a targetlist representing the COLUMNS specified in the
+	 * GRAPH_TABLE. This uses previously constructed list of element pattern
+	 * variables in the GraphTableParseState.
+	 */
 	foreach(lc, rgt->columns)
 	{
 		ResTarget  *rt = lfirst_node(ResTarget, lc);
diff --git a/src/backend/parser/parse_graphtable.c b/src/backend/parser/parse_graphtable.c
index d4fc12f8d02..912ac880c28 100644
--- a/src/backend/parser/parse_graphtable.c
+++ b/src/backend/parser/parse_graphtable.c
@@ -34,6 +34,17 @@
 
 /*
  * Transform a property reference.
+ *
+ * A property reference is parsed as a ColumnRef of the form:
+ * <variable>.<property>. If <variable> is one of the variables bound to an
+ * element pattern in the graph pattern and <property> can be resolved as a
+ * property of the property graph, then we return a GraphPropertyRef node
+ * representing the property reference. If the <variable> exists in the graph
+ * pattern but <property> does not exist in the property graph, we raise an
+ * error. However, if <variable> does not exist in the graph pattern, we return
+ * NULL to let the caller handle it as some other kind of ColumnRef. The
+ * variables bound to the element patterns in the graph pattern are expected to
+ * be collected in the GraphTableParseState.
  */
 Node *
 transformGraphTablePropertyRef(ParseState *pstate, ColumnRef *cref)
@@ -90,6 +101,14 @@ transformGraphTablePropertyRef(ParseState *pstate, ColumnRef *cref)
 
 /*
  * Transform a label expression.
+ *
+ * A label expression is parsed as either a ColumnRef with a single field or a
+ * label expression like label disjunction. The single field in the ColumnRef is
+ * treated as a label name and transformed to a GraphLabelRef node. The label
+ * expression is recursively transformed into an expression tree containg
+ * GraphLabelRef nodes corresponding to the names of the labels appearing in the
+ * expression. If any label name cannot be resolved to a label in the property
+ * graph, an error is raised.
  */
 static Node *
 transformLabelExpr(GraphTableParseState *gpstate, Node *labelexpr)
@@ -157,6 +176,12 @@ transformLabelExpr(GraphTableParseState *gpstate, Node *labelexpr)
 
 /*
  * Transform a GraphElementPattern.
+ *
+ * Transform the label expression and the where clause in the element pattern
+ * given by GraphElementPattern. The variable name in the GraphElementPattern is
+ * added to the list of variables in the GraphTableParseState which is used to
+ * resolve property references in this element pattern or elsewhere in the
+ * GRAPH_TABLE.
  */
 static Node *
 transformGraphElementPattern(ParseState *pstate, GraphElementPattern *gep)
@@ -205,6 +230,11 @@ transformPathPatternList(ParseState *pstate, List *path_pattern)
 
 /*
  * Transform a GraphPattern.
+ *
+ * A GraphPattern consists of a list of one or more path patterns and an
+ * optional where clause. Transform them. We use the previously constructure
+ * list of variables in the GraphTableParseState to resolve property references
+ * in the WHERE clause.
  */
 Node *
 transformGraphPattern(ParseState *pstate, GraphPattern *graph_pattern)
-- 
2.34.1

