Store LIMIT BY expressions in AST and update documentation

- Add LimitBy field to SelectQuery AST to store LIMIT BY expressions
- Update parser to store LIMIT BY expressions instead of discarding them
- Add documentation in CLAUDE.md about explain.txt being ground truth
- Update AST golden files to include limit_by field
- Add comments in explain output clarifying LIMIT BY is not in EXPLAIN AST

Note: LIMIT BY expressions are stored in the AST for semantic information
but are not output in EXPLAIN AST (matching ClickHouse behavior).

Author: claude

ast/ast.go

@@ -61,6 +61,7 @@ type SelectQuery struct {
 	Window      []*WindowDefinition   `json:"window,omitempty"`
 	OrderBy     []*OrderByElement     `json:"order_by,omitempty"`
 	Limit       Expression            `json:"limit,omitempty"`
+	LimitBy     []Expression          `json:"limit_by,omitempty"`
 	Offset      Expression            `json:"offset,omitempty"`
 	Settings    []*SettingExpr        `json:"settings,omitempty"`
 	IntoOutfile *IntoOutfileClause    `json:"into_outfile,omitempty"`

internal/explain/select.go

@@ -106,6 +106,8 @@ func explainSelectQuery(sb *strings.Builder, n *ast.SelectQuery, indent string,
 	if n.Limit != nil {
 		Node(sb, n.Limit, depth+1)
 	}
+	// Note: LIMIT BY expressions are stored in the AST but not output in EXPLAIN AST
+	// (ClickHouse doesn't output them in EXPLAIN AST)
 	// SETTINGS - output here if there's no FORMAT, otherwise it's at SelectWithUnionQuery level
 	if len(n.Settings) > 0 && n.Format == nil {
 		fmt.Fprintf(sb, "%s Set\n", indent)
@@ -214,6 +216,7 @@ func countSelectQueryChildren(n *ast.SelectQuery) int {
 	if n.Offset != nil {
 		count++
 	}
+	// Note: LimitBy is stored in AST but not counted in EXPLAIN AST children
 	// SETTINGS is counted here only if there's no FORMAT
 	// If FORMAT is present, SETTINGS is at SelectWithUnionQuery level
 	if len(n.Settings) > 0 && n.Format == nil {

parser/CLAUDE.md

@@ -1,5 +1,16 @@
 # Parser Development Notes
 
+## Test Data Files
+
+The `testdata/` directory contains test cases from ClickHouse. Each test has:
+
+- `query.sql` - The SQL query to parse
+- `explain.txt` - **DO NOT MODIFY** - This is the ground truth output from ClickHouse's `EXPLAIN AST` command. Our parser must produce output that matches this exactly.
+- `metadata.json` - Test metadata (todo, skip, etc.)
+- `ast.json` - Optional golden file for AST regression testing
+
+To fix a failing test, you must fix the **parser** to produce output matching `explain.txt`, never modify `explain.txt` itself.
+
 ## Running Tests
 
 Always run parser tests with a 5 second timeout:

parser/parser.go

@@ -375,9 +375,9 @@ func (p *Parser) parseSelect() *ast.SelectQuery {
 		// LIMIT BY clause (ClickHouse specific: LIMIT n BY expr1, expr2, ...)
 		if p.currentIs(token.BY) {
 			p.nextToken()
-			// Parse LIMIT BY expressions - skip them for now
+			// Parse LIMIT BY expressions
 			for !p.isEndOfExpression() {
-				p.parseExpression(LOWEST)
+				sel.LimitBy = append(sel.LimitBy, p.parseExpression(LOWEST))
 				if p.currentIs(token.COMMA) {
 					p.nextToken()
 				} else {

parser/testdata/00176_distinct_limit_by_limit_bug_43377/ast.json

@@ -94,7 +94,14 @@
                       "limit": {
                         "type": "Integer",
                         "value": 10
-                      }
+                      },
+                      "limit_by": [
+                        {
+                          "parts": [
+                            "Title"
+                          ]
+                        }
+                      ]
                     }
                   ]
                 }

parser/testdata/00583_limit_by_expressions/ast.json

@@ -22,7 +22,13 @@
       "limit": {
         "type": "Integer",
         "value": 1
-      }
+      },
+      "limit_by": [
+        {
+          "type": "Integer",
+          "value": 1
+        }
+      ]
     }
   ]
 }

parser/testdata/00590_limit_by_column_removal/ast.json

@@ -43,7 +43,14 @@
       "limit": {
         "type": "Integer",
         "value": 1
-      }
+      },
+      "limit_by": [
+        {
+          "parts": [
+            "y"
+          ]
+        }
+      ]
     }
   ]
 }

parser/testdata/01471_limit_by_format/ast.json

@@ -21,7 +21,10 @@
         "limit": {
           "type": "Integer",
           "value": 1
-        }
+        },
+        "limit_by": [
+          {}
+        ]
       }
     ]
   }

parser/testdata/02281_limit_by_distributed/ast.json

@@ -98,7 +98,14 @@
                       "limit": {
                         "type": "Integer",
                         "value": 1
-                      }
+                      },
+                      "limit_by": [
+                        {
+                          "parts": [
+                            "k"
+                          ]
+                        }
+                      ]
                     }
                   ]
                 }

parser/testdata/03290_limit_by_segv/ast.json

@@ -27,7 +27,12 @@
                       "limit": {
                         "type": "Integer",
                         "value": 0
-                      }
+                      },
+                      "limit_by": [
+                        {
+                          "pattern": "1"
+                        }
+                      ]
                     }
                   ]
                 }