ESQL: explain command (#249)

* explain grammar

* correct handling of lexer modes

* review comments

x-pack/plugin/esql/qa/server/src/main/resources/explain.csv-spec

@@ -0,0 +1,15 @@
+explainFrom
+explain [ from foo ];
+
+plan:keyword | type:keyword
+"Project[[?*]]
+\_UnresolvedRelation[foo]" | PARSED
+;
+
+explainCompositeQuery
+explain [ row a = 1 | where a > 0 ];
+
+plan:keyword | type:keyword
+"Filter[?a > 0[INTEGER]]
+ \_Row[[1[INTEGER] AS a]]" | PARSED
+;

x-pack/plugin/esql/src/main/antlr/EsqlBaseLexer.g4

@@ -1,6 +1,7 @@
 lexer grammar EsqlBaseLexer;
 
 EVAL : 'eval' -> pushMode(EXPRESSION);
+EXPLAIN : 'explain' -> pushMode(EXPRESSION);
 FROM : 'from' -> pushMode(SOURCE_IDENTIFIERS);
 ROW : 'row' -> pushMode(EXPRESSION);
 STATS : 'stats' -> pushMode(EXPRESSION);
@@ -75,6 +76,8 @@ FALSE : 'false';
 FIRST : 'first';
 LAST : 'last';
 LP : '(';
+OPENING_BRACKET : '[' -> pushMode(DEFAULT_MODE);
+CLOSING_BRACKET : ']' -> popMode, popMode; // pop twice, once to clear mode of current cmd and once to exit DEFAULT_MODE
 NOT : 'not';
 NULL : 'null';
 NULLS : 'nulls';
@@ -120,6 +123,7 @@ EXPR_WS
 mode SOURCE_IDENTIFIERS;
 
 SRC_PIPE : '|' -> type(PIPE), popMode;
+SRC_CLOSING_BRACKET : ']' -> popMode, popMode, type(CLOSING_BRACKET);
 SRC_COMMA : ',' -> type(COMMA);
 
 SRC_UNQUOTED_IDENTIFIER

x-pack/plugin/esql/src/main/antlr/EsqlBaseLexer.tokens

@@ -1,87 +1,93 @@
 EVAL=1
-FROM=2
-ROW=3
-STATS=4
-WHERE=5
-SORT=6
-LIMIT=7
-UNKNOWN_COMMAND=8
-LINE_COMMENT=9
-MULTILINE_COMMENT=10
-WS=11
-PIPE=12
-STRING=13
-INTEGER_LITERAL=14
-DECIMAL_LITERAL=15
-BY=16
-AND=17
-ASC=18
-ASSIGN=19
-COMMA=20
-DESC=21
-DOT=22
-FALSE=23
-FIRST=24
-LAST=25
-LP=26
-NOT=27
-NULL=28
-NULLS=29
-OR=30
-RP=31
-TRUE=32
-EQ=33
-NEQ=34
-LT=35
-LTE=36
-GT=37
-GTE=38
-PLUS=39
-MINUS=40
-ASTERISK=41
-SLASH=42
-PERCENT=43
-UNQUOTED_IDENTIFIER=44
-QUOTED_IDENTIFIER=45
-EXPR_LINE_COMMENT=46
-EXPR_MULTILINE_COMMENT=47
-EXPR_WS=48
-SRC_UNQUOTED_IDENTIFIER=49
-SRC_QUOTED_IDENTIFIER=50
-SRC_LINE_COMMENT=51
-SRC_MULTILINE_COMMENT=52
-SRC_WS=53
+EXPLAIN=2
+FROM=3
+ROW=4
+STATS=5
+WHERE=6
+SORT=7
+LIMIT=8
+UNKNOWN_COMMAND=9
+LINE_COMMENT=10
+MULTILINE_COMMENT=11
+WS=12
+PIPE=13
+STRING=14
+INTEGER_LITERAL=15
+DECIMAL_LITERAL=16
+BY=17
+AND=18
+ASC=19
+ASSIGN=20
+COMMA=21
+DESC=22
+DOT=23
+FALSE=24
+FIRST=25
+LAST=26
+LP=27
+OPENING_BRACKET=28
+CLOSING_BRACKET=29
+NOT=30
+NULL=31
+NULLS=32
+OR=33
+RP=34
+TRUE=35
+EQ=36
+NEQ=37
+LT=38
+LTE=39
+GT=40
+GTE=41
+PLUS=42
+MINUS=43
+ASTERISK=44
+SLASH=45
+PERCENT=46
+UNQUOTED_IDENTIFIER=47
+QUOTED_IDENTIFIER=48
+EXPR_LINE_COMMENT=49
+EXPR_MULTILINE_COMMENT=50
+EXPR_WS=51
+SRC_UNQUOTED_IDENTIFIER=52
+SRC_QUOTED_IDENTIFIER=53
+SRC_LINE_COMMENT=54
+SRC_MULTILINE_COMMENT=55
+SRC_WS=56
 'eval'=1
-'from'=2
-'row'=3
-'stats'=4
-'where'=5
-'sort'=6
-'limit'=7
-'by'=16
-'and'=17
-'asc'=18
-'='=19
-'desc'=21
-'.'=22
-'false'=23
-'first'=24
-'last'=25
-'('=26
-'not'=27
-'null'=28
-'nulls'=29
-'or'=30
-')'=31
-'true'=32
-'=='=33
-'!='=34
-'<'=35
-'<='=36
-'>'=37
-'>='=38
-'+'=39
-'-'=40
-'*'=41
-'/'=42
-'%'=43
+'explain'=2
+'from'=3
+'row'=4
+'stats'=5
+'where'=6
+'sort'=7
+'limit'=8
+'by'=17
+'and'=18
+'asc'=19
+'='=20
+'desc'=22
+'.'=23
+'false'=24
+'first'=25
+'last'=26
+'('=27
+'['=28
+']'=29
+'not'=30
+'null'=31
+'nulls'=32
+'or'=33
+')'=34
+'true'=35
+'=='=36
+'!='=37
+'<'=38
+'<='=39
+'>'=40
+'>='=41
+'+'=42
+'-'=43
+'*'=44
+'/'=45
+'%'=46

x-pack/plugin/esql/src/main/antlr/EsqlBaseParser.g4

@@ -20,8 +20,9 @@ query
     ;
 
 sourceCommand
-    : rowCommand
+    : explainCommand
     | fromCommand
+    | rowCommand
     ;
 
 processingCommand
@@ -140,3 +141,11 @@ string
 comparisonOperator
     : EQ | NEQ | LT | LTE | GT | GTE
     ;
+
+explainCommand
+    : EXPLAIN subqueryExpression
+    ;
+
+subqueryExpression
+    : OPENING_BRACKET query CLOSING_BRACKET
+    ;