ES|QL query builder

src/Helper/Esql/Branch.php

@@ -0,0 +1,33 @@
+<?php
+/**
+ * Elasticsearch PHP Client
+ *
+ * @link      https://github.com/elastic/elasticsearch-php
+ * @copyright Copyright (c) Elasticsearch B.V (https://www.elastic.co)
+ * @license   https://opensource.org/licenses/MIT MIT License
+ *
+ * Licensed to Elasticsearch B.V under one or more agreements.
+ * Elasticsearch B.V licenses this file to you under the MIT License.
+ * See the LICENSE file in the project root for more information.
+ */
+declare(strict_types = 1);
+
+namespace Elastic\Elasticsearch\Helper\Esql;
+
+/**
+ * Implementation of a branch inside a `FORK` processing command.
+ *
+ * This class inherits from EsqlBase to make it possible to chain all the commands
+ * that belong to an ES|QL query in a single expression.
+ */
+class Branch extends EsqlBase {
+    public function __construct()
+    {
+        parent::__construct(null);
+    }
+
+    protected function renderInternal(): string
+    {
+        return "";
+    }
+}

src/Helper/Esql/ChangePointCommand.php

@@ -0,0 +1,72 @@
+<?php
+/**
+ * Elasticsearch PHP Client
+ *
+ * @link      https://github.com/elastic/elasticsearch-php
+ * @copyright Copyright (c) Elasticsearch B.V (https://www.elastic.co)
+ * @license   https://opensource.org/licenses/MIT MIT License
+ *
+ * Licensed to Elasticsearch B.V under one or more agreements.
+ * Elasticsearch B.V licenses this file to you under the MIT License.
+ * See the LICENSE file in the project root for more information.
+ */
+declare(strict_types = 1);
+
+namespace Elastic\Elasticsearch\Helper\Esql;
+
+/**
+ * Implementation of the `CHANGE_POINT` processing command.
+ *
+ * This class inherits from EsqlBase to make it possible to chain all the commands
+ * that belong to an ES|QL query in a single expression.
+ */
+class ChangePointCommand extends EsqlBase {
+    private string $value;
+    private string $key = "";
+    private string $type_name = "";
+    private string $pvalue_name = "";
+
+    public function __construct(EsqlBase $parent, string $value)
+    {
+        parent::__construct($parent);
+        $this->value = $value;
+    }
+
+    /**
+     * Continuation of the `CHANGE_POINT` command.
+     *
+     * @param string $key The column with the key to order the values by. If not
+     *                    specified, `@timestamp` is used.
+     */
+    public function on(string $key): ChangePointCommand
+    {
+        $this->key = $key;
+        return $this;
+    }
+
+    /**
+     * Continuation of the `CHANGE_POINT` command.
+     *
+     * @param string $type_name The name of the output column with the change
+     *                          point type. If not specified, `type` is used.
+     * @param string $pvalue_name The name of the output column with the p-value
+     *                            that indicates how extreme the change point is.
+     *                            If not specified, `pvalue` is used.
+     */
+    public function as(string $type_name, string $pvalue_name): ChangePointCommand
+    {
+        $this->type_name = $type_name;
+        $this->pvalue_name = $pvalue_name;
+        return $this;
+    }
+
+    protected function renderInternal(): string
+    {
+        $key = $this->key ? " ON " . $this->formatId($this->key) : "";
+        $names = ($this->type_name && $this->pvalue_name) ?
+            " AS " . $this->formatId($this->type_name) . ", " .
+                $this->formatId($this->pvalue_name)
+            : "";
+        return "CHANGE_POINT " . $this->value . $key . $names;
+    }
+}

src/Helper/Esql/CompletionCommand.php

@@ -0,0 +1,74 @@
+<?php
+/**
+ * Elasticsearch PHP Client
+ *
+ * @link      https://github.com/elastic/elasticsearch-php
+ * @copyright Copyright (c) Elasticsearch B.V (https://www.elastic.co)
+ * @license   https://opensource.org/licenses/MIT MIT License
+ *
+ * Licensed to Elasticsearch B.V under one or more agreements.
+ * Elasticsearch B.V licenses this file to you under the MIT License.
+ * See the LICENSE file in the project root for more information.
+ */
+declare(strict_types = 1);
+
+namespace Elastic\Elasticsearch\Helper\Esql;
+
+use RuntimeException;
+
+/**
+ * Implementation of the `COMPLETION` processing command.
+ *
+ * This class inherits from EsqlBase to make it possible to chain all the commands
+ * that belong to an ES|QL query in a single expression.
+ */
+class CompletionCommand extends EsqlBase {
+    private string $prompt;
+    private array $named_prompt = [];
+    private string $inference_id = "";
+
+    public function __construct(EsqlBase $parent, array $prompt)
+    {
+        if (sizeof($prompt) != 1) {
+            throw new RuntimeException("Only one prompt is supported");
+        }
+        parent::__construct($parent);
+        if ($this->isNamedArgumentList($prompt)) {
+            $this->named_prompt = $prompt;
+        }
+        else {
+            $this->prompt = $prompt[0];
+        }
+    }
+
+    /**
+     * Continuation of the `COMPLETION` command.
+     *
+     * @param string $inference_id The ID of the inference endpoint to use for
+     *                             the task. The inference endpoint must be
+     *                             configured with the `completion` task type.
+     */
+    public function with(string $inference_id): CompletionCommand
+    {
+        $this->inference_id = $inference_id;
+        return $this;
+    }
+
+    protected function renderInternal(): string
+    {
+        if (!$this->inference_id) {
+            throw new RuntimeException("The completion command requires an inference ID");
+        }
+        $with = ["inference_id" => $this->inference_id];
+        if ($this->named_prompt) {
+            return "COMPLETION " .
+                $this->formatId(array_keys($this->named_prompt)[0]) . " = " .
+                $this->formatId(array_values($this->named_prompt)[0]) .
+                " WITH " . json_encode($with);
+        }
+        else {
+            return "COMPLETION " . $this->formatId($this->prompt) .
+                " WITH " . json_encode($with);
+        }
+    }
+}

src/Helper/Esql/DissectCommand.php

@@ -0,0 +1,52 @@
+<?php
+/**
+ * Elasticsearch PHP Client
+ *
+ * @link      https://github.com/elastic/elasticsearch-php
+ * @copyright Copyright (c) Elasticsearch B.V (https://www.elastic.co)
+ * @license   https://opensource.org/licenses/MIT MIT License
+ *
+ * Licensed to Elasticsearch B.V under one or more agreements.
+ * Elasticsearch B.V licenses this file to you under the MIT License.
+ * See the LICENSE file in the project root for more information.
+ */
+declare(strict_types = 1);
+
+namespace Elastic\Elasticsearch\Helper\Esql;
+
+/**
+ * Implementation of the `DISSECT` processing command.
+ *
+ * This class inherits from EsqlBase to make it possible to chain all the commands
+ * that belong to an ES|QL query in a single expression.
+ */
+class DissectCommand extends EsqlBase {
+    private string $input;
+    private string $pattern;
+    private string $separator = "";
+
+    public function __construct(EsqlBase $parent, string $input, string $pattern)
+    {
+        parent::__construct($parent);
+        $this->input = $input;
+        $this->pattern = $pattern;
+    }
+
+    /**
+     * Continuation of the `DISSECT` command.
+     *
+     * @param string $separator A string used as the separator between appended
+     *                          values, when using the append modifier.
+     */
+    public function append_separator(string $separator): DissectCommand
+    {
+        $this->separator = $separator;
+        return $this;
+    }
+
+    protected function renderInternal(): string
+    {
+        $sep = $this->separator ? " APPEND_SEPARATOR=" . json_encode($this->separator) : "";
+        return "DISSECT " . $this->formatId($this->input) . " " . json_encode($this->pattern) . $sep;
+    }
+}

src/Helper/Esql/DropCommand.php

@@ -0,0 +1,38 @@
+<?php
+/**
+ * Elasticsearch PHP Client
+ *
+ * @link      https://github.com/elastic/elasticsearch-php
+ * @copyright Copyright (c) Elasticsearch B.V (https://www.elastic.co)
+ * @license   https://opensource.org/licenses/MIT MIT License
+ *
+ * Licensed to Elasticsearch B.V under one or more agreements.
+ * Elasticsearch B.V licenses this file to you under the MIT License.
+ * See the LICENSE file in the project root for more information.
+ */
+declare(strict_types = 1);
+
+namespace Elastic\Elasticsearch\Helper\Esql;
+
+/**
+ * Implementation of the `DROP` processing command.
+ *
+ * This class inherits from EsqlBase to make it possible to chain all the commands
+ * that belong to an ES|QL query in a single expression.
+ */
+class DropCommand extends EsqlBase {
+    private array $columns;
+
+    public function __construct(EsqlBase $parent, array $columns)
+    {
+        parent::__construct($parent);
+        $this->columns = $columns;
+    }
+
+    protected function renderInternal(): string
+    {
+        return "DROP " . implode(
+            ", ", array_map(array($this, "formatId"), $this->columns)
+        );
+    }
+}

src/Helper/Esql/EnrichCommand.php

@@ -0,0 +1,91 @@
+<?php
+/**
+ * Elasticsearch PHP Client
+ *
+ * @link      https://github.com/elastic/elasticsearch-php
+ * @copyright Copyright (c) Elasticsearch B.V (https://www.elastic.co)
+ * @license   https://opensource.org/licenses/MIT MIT License
+ *
+ * Licensed to Elasticsearch B.V under one or more agreements.
+ * Elasticsearch B.V licenses this file to you under the MIT License.
+ * See the LICENSE file in the project root for more information.
+ */
+declare(strict_types = 1);
+
+namespace Elastic\Elasticsearch\Helper\Esql;
+
+/**
+ * Implementation of the `ENRICH` processing command.
+ *
+ * This class inherits from EsqlBase to make it possible to chain all the commands
+ * that belong to an ES|QL query in a single expression.
+ */
+class EnrichCommand extends EsqlBase {
+    private string $policy;
+    private string $match_field = "";
+    private array $fields = [];
+    private array $named_fields = [];
+
+    public function __construct(EsqlBase $parent, string $policy)
+    {
+        parent::__construct($parent);
+        $this->policy = $policy;
+    }
+
+    /**
+     * Continuation of the `ENRICH` command.
+     *
+     * @param string $match_field The match field. `ENRICH` uses its value to
+     *                            look for records in the enrich index. If not
+     *                            specified, the match will be performed on the
+     *                            column with the same name as the `match_field`
+     *                            defined in the enrich policy.
+     */
+    public function on(string $match_field): EnrichCommand
+    {
+        $this->match_field = $match_field;
+        return $this;
+    }
+
+    /**
+     * Continuation of the `ENRICH` command.
+     *
+     * @param string ...$fields The enrich fields from the enrich index that
+     *                          are added to the result as new columns, given
+     *                          as positional or named arguments. If a column
+     *                          with the same name as the enrich field already
+     *                          exists, the existing column will be replaced by
+     *                          the new column. If not specified, each of the
+     *                          enrich fields defined in the policy is added. A
+     *                          column with the same name as the enrich field
+     *                          will be dropped unless the enrich field is
+     *                          renamed.
+     */
+    public function with(string ...$fields): EnrichCommand
+    {
+        if ($this->isNamedArgumentList($fields)) {
+            $this->named_fields = $fields;
+        }
+        else {
+            $this->fields = $fields;
+        }
+        return $this;
+    }
+
+    protected function renderInternal(): string
+    {
+        $on = ($this->match_field != "") ? " ON " . $this->formatId($this->match_field) : "";
+        $with = "";
+        $items = [];
+        if (sizeof($this->named_fields)) {
+            $with = " WITH " . $this->formatKeyValues($this->named_fields);
+        }
+        else if (sizeof($this->fields)) {
+            $with = implode(
+                ", ",
+                array_map(fn($value): string => $this->formatId($value), $this->fields)
+            );
+        }
+        return "ENRICH " . $this->policy . $on . $with;
+    }
+}