Document limitation: cannot flatten OR/AND chains in EXPLAIN output (#92)

Author: kyleconroy

ast/ast.go

@@ -1037,10 +1037,11 @@ const (
 
 // BinaryExpr represents a binary expression.
 type BinaryExpr struct {
-	Position token.Position `json:"-"`
-	Left     Expression     `json:"left"`
-	Op       string         `json:"op"`
-	Right    Expression     `json:"right"`
+	Position      token.Position `json:"-"`
+	Left          Expression     `json:"left"`
+	Op            string         `json:"op"`
+	Right         Expression     `json:"right"`
+	Parenthesized bool           `json:"parenthesized,omitempty"` // True if wrapped in explicit parentheses
 }
 
 func (b *BinaryExpr) Pos() token.Position { return b.Position }

internal/explain/expressions.go

@@ -264,6 +264,18 @@ func explainBinaryExpr(sb *strings.Builder, n *ast.BinaryExpr, indent string, de
 		return
 	}
 
+	// For OR and AND operators, flatten left-associative chains
+	// but preserve explicit parenthesization like "(a OR b) OR c"
+	if n.Op == "OR" || n.Op == "AND" {
+		operands := collectLogicalOperands(n)
+		fmt.Fprintf(sb, "%sFunction %s (children %d)\n", indent, fnName, 1)
+		fmt.Fprintf(sb, "%s ExpressionList (children %d)\n", indent, len(operands))
+		for _, op := range operands {
+			Node(sb, op, depth+2)
+		}
+		return
+	}
+
 	fmt.Fprintf(sb, "%sFunction %s (children %d)\n", indent, fnName, 1)
 	fmt.Fprintf(sb, "%s ExpressionList (children %d)\n", indent, 2)
 	Node(sb, n.Left, depth+2)
@@ -291,6 +303,26 @@ func collectConcatOperands(n *ast.BinaryExpr) []ast.Expression {
 	return operands
 }
 
+// collectLogicalOperands flattens chained OR/AND operations into a list of operands,
+// but respects explicit parenthesization. For example:
+// - "a OR b OR c" → [a, b, c] (flattened)
+// - "(a OR b) OR c" → [(a OR b), c] (preserved due to explicit parens)
+func collectLogicalOperands(n *ast.BinaryExpr) []ast.Expression {
+	var operands []ast.Expression
+
+	// Recursively collect from left side if it's the same operator AND not parenthesized
+	if left, ok := n.Left.(*ast.BinaryExpr); ok && left.Op == n.Op && !left.Parenthesized {
+		operands = append(operands, collectLogicalOperands(left)...)
+	} else {
+		operands = append(operands, n.Left)
+	}
+
+	// Don't flatten right side - explicit parentheses would be on the left in left-associative parsing
+	operands = append(operands, n.Right)
+
+	return operands
+}
+
 func explainUnaryExpr(sb *strings.Builder, n *ast.UnaryExpr, indent string, depth int) {
 	// Handle negate of literal numbers - output as negative literal instead of function
 	if n.Op == "-" {
@@ -410,6 +442,14 @@ func explainAliasedExpr(sb *strings.Builder, n *ast.AliasedExpr, depth int) {
 			for _, op := range operands {
 				Node(sb, op, depth+2)
 			}
+		} else if e.Op == "OR" || e.Op == "AND" {
+			// For OR and AND operators, flatten but respect explicit parenthesization
+			operands := collectLogicalOperands(e)
+			fmt.Fprintf(sb, "%sFunction %s (alias %s) (children %d)\n", indent, fnName, escapeAlias(n.Alias), 1)
+			fmt.Fprintf(sb, "%s ExpressionList (children %d)\n", indent, len(operands))
+			for _, op := range operands {
+				Node(sb, op, depth+2)
+			}
 		} else {
 			fmt.Fprintf(sb, "%sFunction %s (alias %s) (children %d)\n", indent, fnName, escapeAlias(n.Alias), 1)
 			fmt.Fprintf(sb, "%s ExpressionList (children %d)\n", indent, 2)
@@ -582,6 +622,18 @@ func explainWithElement(sb *strings.Builder, n *ast.WithElement, indent string,
 			for _, op := range operands {
 				Node(sb, op, depth+2)
 			}
+		} else if e.Op == "OR" || e.Op == "AND" {
+			// For OR and AND operators, flatten but respect explicit parenthesization
+			operands := collectLogicalOperands(e)
+			if n.Name != "" {
+				fmt.Fprintf(sb, "%sFunction %s (alias %s) (children %d)\n", indent, fnName, n.Name, 1)
+			} else {
+				fmt.Fprintf(sb, "%sFunction %s (children %d)\n", indent, fnName, 1)
+			}
+			fmt.Fprintf(sb, "%s ExpressionList (children %d)\n", indent, len(operands))
+			for _, op := range operands {
+				Node(sb, op, depth+2)
+			}
 		} else {
 			if n.Name != "" {
 				fmt.Fprintf(sb, "%sFunction %s (alias %s) (children %d)\n", indent, fnName, n.Name, 1)

parser/expression.go

@@ -910,6 +910,13 @@ func (p *Parser) parseGroupedOrTuple() ast.Expression {
 	}
 
 	p.expect(token.RPAREN)
+
+	// Mark binary expressions as parenthesized so we can preserve explicit
+	// grouping in EXPLAIN output (e.g., "(a OR b) OR c" vs "a OR b OR c")
+	if binExpr, ok := first.(*ast.BinaryExpr); ok {
+		binExpr.Parenthesized = true
+	}
+
 	return first
 }
 

parser/testdata/00091_prewhere_two_conditions/metadata.json

@@ -1 +1 @@
-{"explain_todo":{"stmt11":true,"stmt12":true,"stmt5":true,"stmt6":true,"stmt7":true}}
+{}

parser/testdata/00093_prewhere_array_join/metadata.json

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

parser/testdata/00110_external_sort/metadata.json

@@ -1,7 +1 @@
-{
-  "explain_todo": {
-    "stmt6": true,
-    "stmt7": true,
-    "stmt8": true
-  }
-}
+{}

parser/testdata/00167_read_bytes_from_fs/metadata.json

@@ -1 +1 @@
-{"explain_todo":{"stmt4":true}}
+{}

parser/testdata/00170_s3_cache/metadata.json

@@ -1,12 +1 @@
-{
-  "explain_todo": {
-    "stmt28": true,
-    "stmt42": true,
-    "stmt43": true,
-    "stmt44": true,
-    "stmt45": true,
-    "stmt46": true,
-    "stmt47": true,
-    "stmt48": true
-  }
-}
+{}

parser/testdata/00172_early_constant_folding/metadata.json

@@ -1 +1 @@
-{"explain_todo":{"stmt3":true,"stmt4":true}}
+{}

parser/testdata/00229_prewhere_column_missing/metadata.json

@@ -1,6 +1 @@
-{
-  "explain_todo": {
-    "stmt20": true,
-    "stmt21": true
-  }
-}
+{}