Skip to content

ES|QL: enable EXPLAIN (snapshot only) #129526

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 18 commits into
base: main
Choose a base branch
from
+2,293 −2,177
Open

ES|QL: enable EXPLAIN (snapshot only) #129526

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
453ad04
ES|QL: enable EXPLAIN (snapshot only)
luigidellaquila Jun 17, 2025
ffbe3fd
Warnings
luigidellaquila Jun 17, 2025
ce0279b
Fix test
luigidellaquila Jun 17, 2025
d3503a3
Fix test
luigidellaquila Jun 17, 2025
996cb45
Merge branch 'main' into esql/explain
luigidellaquila Jun 17, 2025
8b7e234
Use LP RP instead
luigidellaquila Jun 17, 2025
936d10c
Merge branch 'main' into esql/explain
luigidellaquila Jun 17, 2025
448ebc4
dev mode only
luigidellaquila Jun 17, 2025
080e82e
Fix FROM
luigidellaquila Jun 17, 2025
93354e9
Merge branch 'main' into esql/explain
luigidellaquila Jun 17, 2025
ef8fe18
Make it type+plan
luigidellaquila Jun 18, 2025
ff436ec
Merge branch 'main' into esql/explain
luigidellaquila Jun 19, 2025
83a54d1
[CI] Auto commit changes from spotless
elasticsearchmachine Jun 19, 2025
1c5c3fe
Merge branch 'main' into esql/explain
luigidellaquila Jun 19, 2025
ab8ea09
Merge remote-tracking branch 'luigidellaquila/esql/explain' into esql…
luigidellaquila Jun 19, 2025
f794ef0
Merge branch 'main' into esql/explain
luigidellaquila Jun 19, 2025
82e48f4
Merge branch 'main' into esql/explain
luigidellaquila Jun 20, 2025
83a1a96
Fix output
luigidellaquila Jun 20, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 0 additions & 19 deletions x-pack/plugin/esql/qa/server/src/main/resources/explain.csv-spec
View file
Open in desktop

This file was deleted.

3 changes: 1 addition & 2 deletions x-pack/plugin/esql/src/main/antlr/EsqlBaseLexer.tokens
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

8 changes: 4 additions & 4 deletions x-pack/plugin/esql/src/main/antlr/EsqlBaseParser.g4
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,12 +33,12 @@ query
;

sourceCommand
: explainCommand
| fromCommand
: fromCommand
| rowCommand
| showCommand
// in development
| {this.isDevVersion()}? timeSeriesCommand
| {this.isDevVersion()}? explainCommand
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Moving it to dev mode. It didn't work before, so there is really no reason to have it in the GA grammar

;

processingCommand
Expand Down Expand Up @@ -239,11 +239,11 @@ commandOption
;

explainCommand
: EXPLAIN subqueryExpression
: DEV_EXPLAIN subqueryExpression
;

subqueryExpression
: OPENING_BRACKET query CLOSING_BRACKET
: LP query RP
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Aligned with FORK

;

showCommand
Expand Down
3 changes: 1 addition & 2 deletions x-pack/plugin/esql/src/main/antlr/EsqlBaseParser.tokens
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

6 changes: 3 additions & 3 deletions x-pack/plugin/esql/src/main/antlr/lexer/Explain.g4
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,12 +9,12 @@ lexer grammar Explain;
//
// Explain
//
EXPLAIN : 'explain' -> pushMode(EXPLAIN_MODE);

DEV_EXPLAIN : {this.isDevVersion()}? 'explain' -> pushMode(EXPLAIN_MODE);

mode EXPLAIN_MODE;
EXPLAIN_OPENING_BRACKET : OPENING_BRACKET -> type(OPENING_BRACKET), pushMode(DEFAULT_MODE);
EXPLAIN_LP : LP -> type(LP), pushMode(DEFAULT_MODE);
EXPLAIN_PIPE : PIPE -> type(PIPE), popMode;

EXPLAIN_WS : WS -> channel(HIDDEN);
EXPLAIN_LINE_COMMENT : LINE_COMMENT -> channel(HIDDEN);
EXPLAIN_MULTILINE_COMMENT : MULTILINE_COMMENT -> channel(HIDDEN);
3 changes: 3 additions & 0 deletions x-pack/plugin/esql/src/main/antlr/lexer/From.g4
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,9 @@ FROM_COMMA : COMMA -> type(COMMA);
FROM_ASSIGN : ASSIGN -> type(ASSIGN);
METADATA : 'metadata';

// we need this for EXPLAIN
FROM_RP : RP -> type(RP), popMode;
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see this RP is missing from some modes:

Now, JOIN technically would fail anyway, as the "ON" token changes to expression mode, so the question is if we want it to fail at lexer or parser level (?).
My guess is that a query like EXPLAIN (FROM index | LOOKUP JOIN lookup) would fail in different ways depending on this, but I'm not sure of which error we usually prefer

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My actual concern is that every time we add a new command we'll have to do all this push/pop dance, but that's a broader topic...
About the error message, I'm not sure either


// in 8.14 ` were not allowed
// this has been relaxed in 8.15 since " is used for quoting
fragment UNQUOTED_SOURCE_PART
Expand Down
7 changes: 6 additions & 1 deletion x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/action/EsqlCapabilities.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1210,7 +1210,12 @@ public enum Cap {
*
* https://github.com/elastic/elasticsearch/issues/129322
*/
NO_PLAIN_STRINGS_IN_LITERALS;
NO_PLAIN_STRINGS_IN_LITERALS,

/**
* (Re)Added EXPLAIN command
*/
EXPLAIN(Build.current().isSnapshot());

private final boolean enabled;

Expand Down
11 changes: 6 additions & 5 deletions x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/parser/EsqlBaseLexer.interp
View file
Open in desktop

Large diffs are not rendered by default.

2,280 changes: 1,147 additions & 1,133 deletions x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/parser/EsqlBaseLexer.java
View file
Open in desktop

Large diffs are not rendered by default.

6 changes: 3 additions & 3 deletions x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/parser/EsqlBaseParser.interp
View file
Open in desktop

Large diffs are not rendered by default.

Loading