Add LimitByOffset support for LIMIT BY clauses

Handle LIMIT offset, count BY expr and LIMIT n OFFSET m BY expr syntax
by storing the offset separately from the regular OFFSET clause.

- Added LimitByOffset field to SelectQuery AST
- Updated parser to extract offset for LIMIT BY clauses
- Updated explain output to include LimitByOffset

Fixed test: 00939_limit_by_offset/stmt7

Author: claude

ast/ast.go

@@ -81,6 +81,7 @@ type SelectQuery struct {
 	Limit            Expression            `json:"limit,omitempty"`
 	LimitBy          []Expression          `json:"limit_by,omitempty"`
 	LimitByLimit     Expression            `json:"limit_by_limit,omitempty"`     // LIMIT value before BY (e.g., LIMIT 1 BY x LIMIT 3)
+	LimitByOffset    Expression            `json:"limit_by_offset,omitempty"`    // Offset for LIMIT BY (e.g., LIMIT 2, 3 BY x -> offset=2)
 	LimitByHasLimit  bool                  `json:"limit_by_has_limit,omitempty"` // true if LIMIT BY was followed by another LIMIT
 	Offset           Expression            `json:"offset,omitempty"`
 	Settings            []*SettingExpr `json:"settings,omitempty"`

internal/explain/select.go

@@ -139,32 +139,46 @@ func explainSelectQueryWithInheritedWith(sb *strings.Builder, stmt ast.Statement
 			Node(sb, i, depth+2)
 		}
 	}
-	// OFFSET
-	if sq.Offset != nil {
-		Node(sb, sq.Offset, depth+1)
-	}
-	// LIMIT BY handling
+	// LIMIT BY handling - order: LimitByOffset, LimitByLimit, LimitBy expressions, Offset, Limit
 	if sq.LimitByLimit != nil {
+		// Output LIMIT BY offset first (if present)
+		if sq.LimitByOffset != nil {
+			Node(sb, sq.LimitByOffset, depth+1)
+		}
+		// Output LIMIT BY count
 		Node(sb, sq.LimitByLimit, depth+1)
+		// Output LIMIT BY expressions
 		if len(sq.LimitBy) > 0 {
 			fmt.Fprintf(sb, "%s ExpressionList (children %d)\n", indent, len(sq.LimitBy))
 			for _, expr := range sq.LimitBy {
 				Node(sb, expr, depth+2)
 			}
 		}
+		// Output regular OFFSET
+		if sq.Offset != nil {
+			Node(sb, sq.Offset, depth+1)
+		}
+		// Output regular LIMIT
 		if sq.Limit != nil {
 			Node(sb, sq.Limit, depth+1)
 		}
 	} else if len(sq.LimitBy) > 0 {
+		// LIMIT BY without explicit LimitByLimit
 		if sq.Limit != nil {
 			Node(sb, sq.Limit, depth+1)
 		}
 		fmt.Fprintf(sb, "%s ExpressionList (children %d)\n", indent, len(sq.LimitBy))
 		for _, expr := range sq.LimitBy {
 			Node(sb, expr, depth+2)
 		}
-	} else if sq.Limit != nil {
-		Node(sb, sq.Limit, depth+1)
+	} else {
+		// No LIMIT BY - just regular OFFSET and LIMIT
+		if sq.Offset != nil {
+			Node(sb, sq.Offset, depth+1)
+		}
+		if sq.Limit != nil {
+			Node(sb, sq.Limit, depth+1)
+		}
 	}
 	// SETTINGS (when no INTERPOLATE - the case with INTERPOLATE is handled above)
 	if len(sq.Settings) > 0 && len(sq.Interpolate) == 0 && !sq.SettingsAfterFormat {
@@ -417,35 +431,46 @@ func explainSelectQuery(sb *strings.Builder, n *ast.SelectQuery, indent string,
 			Node(sb, i, depth+2)
 		}
 	}
-	// OFFSET (ClickHouse outputs offset before limit in EXPLAIN AST)
-	if n.Offset != nil {
-		Node(sb, n.Offset, depth+1)
-	}
-	// LIMIT BY handling
+	// LIMIT BY handling - order: LimitByOffset, LimitByLimit, LimitBy expressions, Offset, Limit
 	if n.LimitByLimit != nil {
-		// Case: LIMIT n BY x LIMIT m -> output LimitByLimit, LimitBy, Limit
+		// Output LIMIT BY offset first (if present)
+		if n.LimitByOffset != nil {
+			Node(sb, n.LimitByOffset, depth+1)
+		}
+		// Output LIMIT BY count
 		Node(sb, n.LimitByLimit, depth+1)
+		// Output LIMIT BY expressions
 		if len(n.LimitBy) > 0 {
 			fmt.Fprintf(sb, "%s ExpressionList (children %d)\n", indent, len(n.LimitBy))
 			for _, expr := range n.LimitBy {
 				Node(sb, expr, depth+2)
 			}
 		}
+		// Output regular OFFSET
+		if n.Offset != nil {
+			Node(sb, n.Offset, depth+1)
+		}
+		// Output regular LIMIT
 		if n.Limit != nil {
 			Node(sb, n.Limit, depth+1)
 		}
 	} else if len(n.LimitBy) > 0 {
-		// Case: LIMIT n BY x (no second LIMIT) -> output Limit, then LimitBy
+		// LIMIT BY without explicit LimitByLimit
 		if n.Limit != nil {
 			Node(sb, n.Limit, depth+1)
 		}
 		fmt.Fprintf(sb, "%s ExpressionList (children %d)\n", indent, len(n.LimitBy))
 		for _, expr := range n.LimitBy {
 			Node(sb, expr, depth+2)
 		}
-	} else if n.Limit != nil {
-		// Case: plain LIMIT n (no BY)
-		Node(sb, n.Limit, depth+1)
+	} else {
+		// No LIMIT BY - just regular OFFSET and LIMIT
+		if n.Offset != nil {
+			Node(sb, n.Offset, depth+1)
+		}
+		if n.Limit != nil {
+			Node(sb, n.Limit, depth+1)
+		}
 	}
 	// SETTINGS is output at SelectQuery level only when NOT after FORMAT
 	// When SettingsAfterFormat is true, it's output at SelectWithUnionQuery level instead
@@ -617,8 +642,11 @@ func countSelectQueryChildren(n *ast.SelectQuery) int {
 	if len(n.Interpolate) > 0 {
 		count++
 	}
+	if n.LimitByOffset != nil {
+		count++ // LIMIT offset in "LIMIT offset, count BY x"
+	}
 	if n.LimitByLimit != nil {
-		count++ // LIMIT n in "LIMIT n BY x LIMIT m"
+		count++ // LIMIT count in "LIMIT n BY x LIMIT m"
 	}
 	if n.Limit != nil {
 		count++

parser/parser.go

@@ -1210,6 +1210,19 @@ func (p *Parser) parseSelectInternal(preParsedWith []ast.Expression) *ast.Select
 		// LIMIT BY clause (ClickHouse specific: LIMIT n BY expr1, expr2, ...)
 		if p.currentIs(token.BY) {
 			p.nextToken()
+			// If we had comma syntax (LIMIT offset, count BY ...), save values for LIMIT BY
+			// Otherwise just LIMIT n BY ... uses n as the count
+			if sel.Offset != nil {
+				// LIMIT offset, count BY ... -> LimitByOffset=offset, LimitByLimit=count
+				sel.LimitByOffset = sel.Offset
+				sel.LimitByLimit = sel.Limit
+				sel.Offset = nil
+				sel.Limit = nil
+			} else {
+				// LIMIT n BY ... -> LimitByLimit=n
+				sel.LimitByLimit = sel.Limit
+				sel.Limit = nil
+			}
 			// Parse LIMIT BY expressions
 			for !p.isEndOfExpression() {
 				expr := p.parseExpression(LOWEST)
@@ -1223,8 +1236,6 @@ func (p *Parser) parseSelectInternal(preParsedWith []ast.Expression) *ast.Select
 			// After LIMIT BY, there can be another LIMIT for overall output
 			if p.currentIs(token.LIMIT) {
 				p.nextToken()
-				// Save the LIMIT BY limit value (e.g., LIMIT 1 BY x -> LimitByLimit=1)
-				sel.LimitByLimit = sel.Limit
 				sel.Limit = p.parseExpression(LOWEST)
 				sel.LimitByHasLimit = true
 			}
@@ -1248,6 +1259,11 @@ func (p *Parser) parseSelectInternal(preParsedWith []ast.Expression) *ast.Select
 		// LIMIT n OFFSET m BY expr syntax - handle BY after OFFSET
 		if p.currentIs(token.BY) && sel.Limit != nil && len(sel.LimitBy) == 0 {
 			p.nextToken()
+			// Move Limit and Offset to LimitByLimit and LimitByOffset
+			sel.LimitByLimit = sel.Limit
+			sel.LimitByOffset = sel.Offset
+			sel.Limit = nil
+			sel.Offset = nil
 			// Parse LIMIT BY expressions
 			for !p.isEndOfExpression() {
 				expr := p.parseExpression(LOWEST)

parser/testdata/00939_limit_by_offset/metadata.json

@@ -1,5 +1 @@
-{
-  "explain_todo": {
-    "stmt7": true
-  }
-}
+{}