[ES|QL] High-level AST APIs for the WHERE command (#199998)

## Summary

Partially addresses #191812

Implements high-level APIs for working with `WHERE` command.

- `commands.where.list()` — lists all `WHERE` commands.
- `commands.where.byIndex()` — finds the Nth `WHERE` command in
the query.
- `commands.where.byField()` — finds the first `WHERE` command
which uses a specified field or a param.


### Checklist

Delete any items that are not applicable to this PR.

- [x] [Unit or functional
tests](https://www.elastic.co/guide/en/kibana/master/development-tests.html)
were updated or added to match the most common scenarios

### For maintainers

- [x] This was checked for breaking API changes and was [labeled
appropriately](https://www.elastic.co/guide/en/kibana/master/contributing.html#_add_your_labels)

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 };