Add EXPLAIN settings and explicit type support (#67)

Author: kyleconroy

ast/ast.go

@@ -559,9 +559,11 @@ const (
 
 // ExplainQuery represents an EXPLAIN statement.
 type ExplainQuery struct {
-	Position    token.Position `json:"-"`
-	ExplainType ExplainType    `json:"explain_type"`
-	Statement   Statement      `json:"statement"`
+	Position     token.Position `json:"-"`
+	ExplainType  ExplainType    `json:"explain_type"`
+	Statement    Statement      `json:"statement"`
+	HasSettings  bool           `json:"has_settings,omitempty"`
+	ExplicitType bool           `json:"explicit_type,omitempty"` // true if type was explicitly specified
 }
 
 func (e *ExplainQuery) Pos() token.Position { return e.Position }

internal/explain/statements.go

@@ -384,22 +384,36 @@ func explainSystemQuery(sb *strings.Builder, indent string) {
 }
 
 func explainExplainQuery(sb *strings.Builder, n *ast.ExplainQuery, indent string, depth int) {
+	// Determine the type string - only show if explicitly specified
+	typeStr := ""
+	if n.ExplicitType {
+		typeStr = " " + string(n.ExplainType)
+	}
+
 	// EXPLAIN CURRENT TRANSACTION has no children
 	if n.ExplainType == ast.ExplainCurrentTransaction {
 		// At top level (depth 0), ClickHouse outputs "Explain EXPLAIN <TYPE>"
 		if depth == 0 {
-			fmt.Fprintf(sb, "%sExplain EXPLAIN %s\n", indent, n.ExplainType)
+			fmt.Fprintf(sb, "%sExplain EXPLAIN%s\n", indent, typeStr)
 		} else {
-			fmt.Fprintf(sb, "%sExplain %s\n", indent, n.ExplainType)
+			fmt.Fprintf(sb, "%sExplain%s\n", indent, typeStr)
 		}
 		return
 	}
+	// Count children: settings (if present) + statement
+	children := 1
+	if n.HasSettings {
+		children++
+	}
 	// At top level (depth 0), ClickHouse outputs "Explain EXPLAIN <TYPE>"
 	// Nested in subqueries, it outputs "Explain <TYPE>"
 	if depth == 0 {
-		fmt.Fprintf(sb, "%sExplain EXPLAIN %s (children %d)\n", indent, n.ExplainType, 1)
+		fmt.Fprintf(sb, "%sExplain EXPLAIN%s (children %d)\n", indent, typeStr, children)
 	} else {
-		fmt.Fprintf(sb, "%sExplain %s (children %d)\n", indent, n.ExplainType, 1)
+		fmt.Fprintf(sb, "%sExplain%s (children %d)\n", indent, typeStr, children)
+	}
+	if n.HasSettings {
+		fmt.Fprintf(sb, "%s Set\n", indent)
 	}
 	Node(sb, n.Statement, depth+1)
 }

parser/parser.go

@@ -2895,18 +2895,23 @@ func (p *Parser) parseExplain() *ast.ExplainQuery {
 		switch strings.ToUpper(p.current.Value) {
 		case "AST":
 			explain.ExplainType = ast.ExplainAST
+			explain.ExplicitType = true
 			p.nextToken()
 		case "SYNTAX":
 			explain.ExplainType = ast.ExplainSyntax
+			explain.ExplicitType = true
 			p.nextToken()
 		case "PLAN":
 			explain.ExplainType = ast.ExplainPlan
+			explain.ExplicitType = true
 			p.nextToken()
 		case "PIPELINE":
 			explain.ExplainType = ast.ExplainPipeline
+			explain.ExplicitType = true
 			p.nextToken()
 		case "ESTIMATE":
 			explain.ExplainType = ast.ExplainEstimate
+			explain.ExplicitType = true
 			p.nextToken()
 		case "CURRENT":
 			// EXPLAIN CURRENT TRANSACTION
@@ -2915,6 +2920,7 @@ func (p *Parser) parseExplain() *ast.ExplainQuery {
 				p.nextToken()
 			}
 			explain.ExplainType = ast.ExplainCurrentTransaction
+			explain.ExplicitType = true
 			return explain // No statement follows CURRENT TRANSACTION
 		default:
 			explain.ExplainType = ast.ExplainPlan
@@ -2926,6 +2932,7 @@ func (p *Parser) parseExplain() *ast.ExplainQuery {
 	// Options can be identifiers or keywords like OPTIMIZE followed by =
 	for p.peekIs(token.EQ) && !p.currentIs(token.SELECT) && !p.currentIs(token.WITH) {
 		// This is an option (name = value)
+		explain.HasSettings = true
 		p.nextToken() // skip option name
 		p.nextToken() // skip =
 		p.parseExpression(LOWEST) // skip value

parser/parser_test.go

@@ -245,7 +245,7 @@ func TestParser(t *testing.T) {
 							if len(metadata.ExplainTodo) == 0 {
 								metadata.ExplainTodo = nil
 							}
-							updatedBytes, err := json.Marshal(metadata)
+							updatedBytes, err := json.MarshalIndent(metadata, "", "  ")
 							if err != nil {
 								t.Errorf("Failed to marshal updated metadata: %v", err)
 							} else if err := os.WriteFile(metadataPath, append(updatedBytes, '\n'), 0644); err != nil {

parser/testdata/01508_explain_header/metadata.json

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

parser/testdata/01556_explain_select_with_union_query/metadata.json

@@ -1,12 +1 @@
-{
-  "explain_todo": {
-    "stmt15": true,
-    "stmt16": true,
-    "stmt18": true,
-    "stmt19": true,
-    "stmt4": true,
-    "stmt5": true,
-    "stmt7": true,
-    "stmt8": true
-  }
-}
+{"explain_todo":{"stmt16":true,"stmt19":true,"stmt5":true,"stmt8":true}}

parser/testdata/01576_alias_column_rewrite/metadata.json

@@ -1,17 +1 @@
-{
-  "explain_todo": {
-    "stmt22": true,
-    "stmt23": true,
-    "stmt3": true,
-    "stmt32": true,
-    "stmt33": true,
-    "stmt34": true,
-    "stmt36": true,
-    "stmt37": true,
-    "stmt38": true,
-    "stmt4": true,
-    "stmt42": true,
-    "stmt5": true,
-    "stmt51": true
-  }
-}
+{"explain_todo":{"stmt22":true,"stmt23":true,"stmt3":true,"stmt4":true,"stmt42":true,"stmt5":true,"stmt51":true}}

parser/testdata/01763_filter_push_down_bugs/metadata.json

@@ -1,8 +1 @@
-{
-  "explain_todo": {
-    "stmt11": true,
-    "stmt23": true,
-    "stmt24": true,
-    "stmt5": true
-  }
-}
+{"explain_todo":{"stmt11":true,"stmt5":true}}

parser/testdata/01951_distributed_push_down_limit/metadata.json

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

parser/testdata/01952_optimize_distributed_group_by_sharding_key/metadata.json

@@ -1,20 +1 @@
-{
-  "explain_todo": {
-    "stmt10": true,
-    "stmt11": true,
-    "stmt12": true,
-    "stmt14": true,
-    "stmt15": true,
-    "stmt16": true,
-    "stmt17": true,
-    "stmt18": true,
-    "stmt19": true,
-    "stmt20": true,
-    "stmt21": true,
-    "stmt5": true,
-    "stmt6": true,
-    "stmt7": true,
-    "stmt8": true,
-    "stmt9": true
-  }
-}
+{"explain_todo":{"stmt11":true,"stmt12":true,"stmt16":true,"stmt17":true,"stmt20":true,"stmt21":true,"stmt7":true,"stmt8":true}}