[8.x] [ES|QL] High-level AST APIs for the `WHERE` command (#…

…199998) (#202110)

# Backport

This will backport the following commits from `main` to `8.x`:
- [[ES|QL] High-level AST APIs for the `WHERE` command
(#199998)](#199998)

<!--- Backport version: 9.4.3 -->

### 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-28T09:14:50Z","message":"[ES|QL]
High-level AST APIs for the `WHERE` command (#199998)\n\n##
Summary\r\n\r\nPartially addresses
https://github.com/elastic/kibana/issues/191812\r\n\r\nImplements
high-level APIs for working with `WHERE` command.\r\n\r\n-
`commands.where.list()` &mdash; lists all `WHERE` commands.\r\n-
`commands.where.byIndex()` &mdash; finds the Nth `WHERE` command
in\r\nthe query.\r\n- `commands.where.byField()` &mdash; finds the first
`WHERE` command\r\nwhich uses a specified field or a
param.\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] [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### 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":"3e899e748e03000eef1712dd65e01d8fc6e99930","branchLabelMapping":{"^v9.0.0$":"main","^v8.18.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.18.0"],"title":"[ES|QL]
High-level AST APIs for the `WHERE`
command","number":199998,"url":"https://github.com/elastic/kibana/pull/199998","mergeCommit":{"message":"[ES|QL]
High-level AST APIs for the `WHERE` command (#199998)\n\n##
Summary\r\n\r\nPartially addresses
https://github.com/elastic/kibana/issues/191812\r\n\r\nImplements
high-level APIs for working with `WHERE` command.\r\n\r\n-
`commands.where.list()` &mdash; lists all `WHERE` commands.\r\n-
`commands.where.byIndex()` &mdash; finds the Nth `WHERE` command
in\r\nthe query.\r\n- `commands.where.byField()` &mdash; finds the first
`WHERE` command\r\nwhich uses a specified field or a
param.\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] [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### 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":"3e899e748e03000eef1712dd65e01d8fc6e99930"}},"sourceBranch":"main","suggestedTargetBranches":["8.x"],"targetPullRequestStates":[{"branch":"main","label":"v9.0.0","branchLabelMappingKey":"^v9.0.0$","isSourceBranch":true,"state":"MERGED","url":"https://github.com/elastic/kibana/pull/199998","number":199998,"mergeCommit":{"message":"[ES|QL]
High-level AST APIs for the `WHERE` command (#199998)\n\n##
Summary\r\n\r\nPartially addresses
https://github.com/elastic/kibana/issues/191812\r\n\r\nImplements
high-level APIs for working with `WHERE` command.\r\n\r\n-
`commands.where.list()` &mdash; lists all `WHERE` commands.\r\n-
`commands.where.byIndex()` &mdash; finds the Nth `WHERE` command
in\r\nthe query.\r\n- `commands.where.byField()` &mdash; finds the first
`WHERE` command\r\nwhich uses a specified field or a
param.\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] [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### 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":"3e899e748e03000eef1712dd65e01d8fc6e99930"}},{"branch":"8.x","label":"v8.18.0","branchLabelMappingKey":"^v8.18.0$","isSourceBranch":false,"state":"NOT_CREATED"}]}]
BACKPORT-->

Co-authored-by: Vadim Kibana <[email protected]>

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

@@ -29,6 +29,9 @@ import {
   ESQLPositionalParamLiteral,
   ESQLOrderExpression,
   ESQLSource,
+  ESQLParamLiteral,
+  ESQLFunction,
+  ESQLAstItem,
 } from '../types';
 import { AstNodeParserFields, AstNodeTemplate, PartialFields } from './types';
 
@@ -171,6 +174,53 @@ export namespace Builder {
       };
     };
 
+    export namespace func {
+      export const node = (
+        template: AstNodeTemplate<ESQLFunction>,
+        fromParser?: Partial<AstNodeParserFields>
+      ): ESQLFunction => {
+        return {
+          ...template,
+          ...Builder.parserFields(fromParser),
+          type: 'function',
+        };
+      };
+
+      export const call = (
+        nameOrOperator: string | ESQLIdentifier | ESQLParamLiteral,
+        args: ESQLAstItem[],
+        template?: Omit<AstNodeTemplate<ESQLFunction>, 'subtype' | 'name' | 'operator' | 'args'>,
+        fromParser?: Partial<AstNodeParserFields>
+      ): ESQLFunction => {
+        let name: string;
+        let operator: ESQLIdentifier | ESQLParamLiteral;
+        if (typeof nameOrOperator === 'string') {
+          name = nameOrOperator;
+          operator = Builder.identifier({ name });
+        } else {
+          operator = nameOrOperator;
+          name = LeafPrinter.print(operator);
+        }
+        return Builder.expression.func.node(
+          { ...template, name, operator, args, subtype: 'variadic-call' },
+          fromParser
+        );
+      };
+
+      export const binary = (
+        name: string,
+        args: [left: ESQLAstItem, right: ESQLAstItem],
+        template?: Omit<AstNodeTemplate<ESQLFunction>, 'subtype' | 'name' | 'operator' | 'args'>,
+        fromParser?: Partial<AstNodeParserFields>
+      ): ESQLFunction => {
+        const operator = Builder.identifier({ name });
+        return Builder.expression.func.node(
+          { ...template, name, operator, args, subtype: 'binary-expression' },
+          fromParser
+        );
+      };
+    }
+
     export namespace literal {
       /**
        * Constructs an integer literal node.
@@ -189,6 +239,21 @@ export namespace Builder {
         return node;
       };
 
+      export const integer = (
+        value: number,
+        template?: Omit<AstNodeTemplate<ESQLIntegerLiteral | ESQLDecimalLiteral>, 'name'>,
+        fromParser?: Partial<AstNodeParserFields>
+      ): ESQLIntegerLiteral | ESQLDecimalLiteral => {
+        return Builder.expression.literal.numeric(
+          {
+            ...template,
+            value,
+            literalType: 'integer',
+          },
+          fromParser
+        );
+      };
+
       export const list = (
         template: Omit<AstNodeTemplate<ESQLList>, 'name'>,
         fromParser?: Partial<AstNodeParserFields>
@@ -262,5 +327,25 @@ export namespace Builder {
 
       return node;
     };
+
+    export const build = (
+      name: string,
+      options: Partial<ESQLParamLiteral> = {},
+      fromParser?: Partial<AstNodeParserFields>
+    ): ESQLParam => {
+      const value: string = name.startsWith('?') ? name.slice(1) : name;
+
+      if (!value) {
+        return Builder.param.unnamed(options);
+      }
+
+      const isNumeric = !isNaN(Number(value)) && String(Number(value)) === value;
+
+      if (isNumeric) {
+        return Builder.param.positional({ ...options, value: Number(value) }, fromParser);
+      } else {
+        return Builder.param.named({ ...options, value }, fromParser);
+      }
+    };
   }
 }

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

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