[8.x] [ES|QL] Improve STATS command summary extraction (#199796) (#…

…199970)

# Backport

This will backport the following commits from `main` to `8.x`:
- [[ES|QL] Improve `STATS` command summary extraction
(#199796)](#199796)

<!--- Backport version: 8.9.8 -->

### Questions ?
Please refer to the [Backport tool
documentation](https://github.com/sqren/backport)

<!--BACKPORT [{"author":{"name":"Vadim
Kibana","email":"[email protected]"},"sourceCommit":{"committedDate":"2024-11-13T08:48:05Z","message":"[ES|QL]
Improve `STATS` command summary extraction (#199796)\n\n##
Summary\r\n\r\nPartially addresses
https://github.com/elastic/kibana/issues/191812\r\n\r\n- Correctly
extracts summary from of fields from the `BY` clause of\r\n`STATS`
command.\r\n- The `.summarize()` command now returns `newFields` and
`usedFields`\r\nproperties. The `newFields` is a list of newly created
fields by the\r\n`STATS` command. The `usedFields` is a list of all
fields which were\r\nused by the `STATS` command.\r\n- Improves
parameter node handling.\r\n\r\n\r\n### Example\r\n\r\nExtract all
\"new\" and \"used\" fields from all `STATS`
commands:\r\n\r\n```ts\r\nconst query = EsqlQuery.fromSrc('FROM index |
STATS a = max(b), agg(c) BY d');\r\nconst summary =
mutate.commands.stats.summarize(query);\r\n\r\nconsole.log(summary.newFields);
// [ 'a', '`agg(c)`' ]\r\nconsole.log(summary.usedFields); // [ 'b',
'c', 'd' ]\r\n```\r\n\r\n\r\n### Checklist\r\n\r\nDelete any items that
are not applicable to this PR.\r\n\r\n-
[x]\r\n[Documentation](https://www.elastic.co/guide/en/kibana/master/development-documentation.html)\r\nwas
added for features that require explanation or tutorials\r\n- [x] [Unit
or
functional\r\ntests](https://www.elastic.co/guide/en/kibana/master/development-tests.html)\r\nwere
updated or added to match the most common scenarios\r\n\r\n\r\n### For
maintainers\r\n\r\n- [x] This was checked for breaking API changes and
was
[labeled\r\nappropriately](https://www.elastic.co/guide/en/kibana/master/contributing.html#_add_your_labels)","sha":"d276b4899533b0bde2038c7fedfed7c30a74a80b","branchLabelMapping":{"^v9.0.0$":"main","^v8.17.0$":"8.x","^v(\\d+).(\\d+).\\d+$":"$1.$2"}},"sourcePullRequest":{"labels":["review","release_note:skip","v9.0.0","backport:prev-minor","Feature:ES|QL","Team:ESQL","v8.17.0"],"number":199796,"url":"https://github.com/elastic/kibana/pull/199796","mergeCommit":{"message":"[ES|QL]
Improve `STATS` command summary extraction (#199796)\n\n##
Summary\r\n\r\nPartially addresses
https://github.com/elastic/kibana/issues/191812\r\n\r\n- Correctly
extracts summary from of fields from the `BY` clause of\r\n`STATS`
command.\r\n- The `.summarize()` command now returns `newFields` and
`usedFields`\r\nproperties. The `newFields` is a list of newly created
fields by the\r\n`STATS` command. The `usedFields` is a list of all
fields which were\r\nused by the `STATS` command.\r\n- Improves
parameter node handling.\r\n\r\n\r\n### Example\r\n\r\nExtract all
\"new\" and \"used\" fields from all `STATS`
commands:\r\n\r\n```ts\r\nconst query = EsqlQuery.fromSrc('FROM index |
STATS a = max(b), agg(c) BY d');\r\nconst summary =
mutate.commands.stats.summarize(query);\r\n\r\nconsole.log(summary.newFields);
// [ 'a', '`agg(c)`' ]\r\nconsole.log(summary.usedFields); // [ 'b',
'c', 'd' ]\r\n```\r\n\r\n\r\n### Checklist\r\n\r\nDelete any items that
are not applicable to this PR.\r\n\r\n-
[x]\r\n[Documentation](https://www.elastic.co/guide/en/kibana/master/development-documentation.html)\r\nwas
added for features that require explanation or tutorials\r\n- [x] [Unit
or
functional\r\ntests](https://www.elastic.co/guide/en/kibana/master/development-tests.html)\r\nwere
updated or added to match the most common scenarios\r\n\r\n\r\n### For
maintainers\r\n\r\n- [x] This was checked for breaking API changes and
was
[labeled\r\nappropriately](https://www.elastic.co/guide/en/kibana/master/contributing.html#_add_your_labels)","sha":"d276b4899533b0bde2038c7fedfed7c30a74a80b"}},"sourceBranch":"main","suggestedTargetBranches":["8.x"],"targetPullRequestStates":[{"branch":"main","label":"v9.0.0","labelRegex":"^v9.0.0$","isSourceBranch":true,"state":"MERGED","url":"https://github.com/elastic/kibana/pull/199796","number":199796,"mergeCommit":{"message":"[ES|QL]
Improve `STATS` command summary extraction (#199796)\n\n##
Summary\r\n\r\nPartially addresses
https://github.com/elastic/kibana/issues/191812\r\n\r\n- Correctly
extracts summary from of fields from the `BY` clause of\r\n`STATS`
command.\r\n- The `.summarize()` command now returns `newFields` and
`usedFields`\r\nproperties. The `newFields` is a list of newly created
fields by the\r\n`STATS` command. The `usedFields` is a list of all
fields which were\r\nused by the `STATS` command.\r\n- Improves
parameter node handling.\r\n\r\n\r\n### Example\r\n\r\nExtract all
\"new\" and \"used\" fields from all `STATS`
commands:\r\n\r\n```ts\r\nconst query = EsqlQuery.fromSrc('FROM index |
STATS a = max(b), agg(c) BY d');\r\nconst summary =
mutate.commands.stats.summarize(query);\r\n\r\nconsole.log(summary.newFields);
// [ 'a', '`agg(c)`' ]\r\nconsole.log(summary.usedFields); // [ 'b',
'c', 'd' ]\r\n```\r\n\r\n\r\n### Checklist\r\n\r\nDelete any items that
are not applicable to this PR.\r\n\r\n-
[x]\r\n[Documentation](https://www.elastic.co/guide/en/kibana/master/development-documentation.html)\r\nwas
added for features that require explanation or tutorials\r\n- [x] [Unit
or
functional\r\ntests](https://www.elastic.co/guide/en/kibana/master/development-tests.html)\r\nwere
updated or added to match the most common scenarios\r\n\r\n\r\n### For
maintainers\r\n\r\n- [x] This was checked for breaking API changes and
was
[labeled\r\nappropriately](https://www.elastic.co/guide/en/kibana/master/contributing.html#_add_your_labels)","sha":"d276b4899533b0bde2038c7fedfed7c30a74a80b"}},{"branch":"8.x","label":"v8.17.0","labelRegex":"^v8.17.0$","isSourceBranch":false,"state":"NOT_CREATED"}]}]
BACKPORT-->

---------

Co-authored-by: streamich <[email protected]>
Co-authored-by: Stratoula Kalafateli <[email protected]>

packages/kbn-esql-ast/src/ast/helpers.ts

@@ -14,6 +14,7 @@ import type {
   ESQLFunction,
   ESQLIntegerLiteral,
   ESQLLiteral,
+  ESQLParamLiteral,
   ESQLProperNode,
 } from '../types';
 import { BinaryExpressionGroup } from './constants';
@@ -48,6 +49,9 @@ export const isIntegerLiteral = (node: unknown): node is ESQLIntegerLiteral =>
 export const isDoubleLiteral = (node: unknown): node is ESQLIntegerLiteral =>
   isLiteral(node) && node.literalType === 'double';
 
+export const isParamLiteral = (node: unknown): node is ESQLParamLiteral =>
+  isLiteral(node) && node.literalType === 'param';
+
 export const isColumn = (node: unknown): node is ESQLColumn =>
   isProperNode(node) && node.type === 'column';
 

packages/kbn-esql-ast/src/mutate/README.md

@@ -60,3 +60,21 @@ console.log(src); // FROM index METADATA _lang, _id
     - `.remove()` — Remove a `LIMIT` command by index.
     - `.set()` — Set the limit value of a specific `LIMIT` command.
     - `.upsert()` — Insert a `LIMIT` command, or update the limit value if it already exists.
+  - `.stats`
+    - `.list()` — List all `STATS` commands.
+    - `.byIndex()` — Find a `STATS` command by index.
+    - `.summarize()` — Summarize all `STATS` commands.
+    - `.summarizeCommand()` — Summarize a specific `STATS` command.
+
+
+## Examples
+
+Extract all "new" and "used" fields from all `STATS` commands:
+
+```ts
+const query = EsqlQuery.fromSrc('FROM index | STATS a = max(b), agg(c) BY d');
+const summary = mutate.commands.stats.summarize(query);
+
+console.log(summary.newFields);     // [ 'a', '`agg(c)`' ]
+console.log(summary.usedFields);    // [ 'b', 'c', 'd' ]
+```

packages/kbn-esql-ast/src/mutate/commands/index.ts

@@ -10,5 +10,6 @@
 import * as from from './from';
 import * as limit from './limit';
 import * as sort from './sort';
+import * as stats from './stats';
 
-export { from, limit, sort };
+export { from, limit, sort, stats };