Updated opensearch-php to reflect the latest OpenSearch API spec (2025-03-20) (#325)

Signed-off-by: GitHub <[email protected]>
Co-authored-by: dblock <[email protected]>

Author: opensearch-trigger-bot[bot]

CHANGELOG.md

@@ -10,6 +10,7 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 ### Fixed
 ### Security
 ### Updated APIs
+- Updated opensearch-php APIs to reflect [opensearch-api-specification@fc5e888](https://github.com/opensearch-project/opensearch-api-specification/commit/fc5e888f8b7c1a09ca0c718c1dcb8bbca48c0a37)
 
 ## [2.4.3]
 ### Added

src/OpenSearch/Client.php

@@ -37,6 +37,7 @@
 use OpenSearch\Namespaces\IsmNamespace;
 use OpenSearch\Namespaces\KnnNamespace;
 use OpenSearch\Namespaces\ListNamespace;
+use OpenSearch\Namespaces\LtrNamespace;
 use OpenSearch\Namespaces\MlNamespace;
 use OpenSearch\Namespaces\MonitoringNamespace;
 use OpenSearch\Namespaces\NodesNamespace;
@@ -207,6 +208,11 @@ class Client
      */
     protected $list;
 
+    /**
+     * @var LtrNamespace
+     */
+    protected $ltr;
+
     /**
      * @var MlNamespace
      */
@@ -370,6 +376,7 @@ public function __construct(
         $this->ism = new IsmNamespace($transport, $this->endpointFactory);
         $this->knn = new KnnNamespace($transport, $this->endpointFactory);
         $this->list = new ListNamespace($transport, $this->endpointFactory);
+        $this->ltr = new LtrNamespace($transport, $this->endpointFactory);
         $this->ml = new MlNamespace($transport, $this->endpointFactory);
         // @phpstan-ignore new.deprecated, property.deprecated
         $this->monitoring = new MonitoringNamespace($transport, $this->endpointFactory);
@@ -1962,6 +1969,13 @@ public function list(): ListNamespace
     {
         return $this->list;
     }
+    /**
+     * Returns the ltr namespace
+     */
+    public function ltr(): LtrNamespace
+    {
+        return $this->ltr;
+    }
     /**
      * Returns the ml namespace
      */

src/OpenSearch/Endpoints/Ltr/Stats.php

@@ -0,0 +1,86 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * The OpenSearch Contributors require contributions made to
+ * this file be licensed under the Apache-2.0 license or a
+ * compatible open source license.
+ *
+ * Modifications Copyright OpenSearch Contributors. See
+ * GitHub history for details.
+ */
+
+namespace OpenSearch\Endpoints\Ltr;
+
+use OpenSearch\Endpoints\AbstractEndpoint;
+
+/**
+ * NOTE: This file is autogenerated using util/GenerateEndpoints.php
+ */
+class Stats extends AbstractEndpoint
+{
+    protected $node_id;
+    protected $stat;
+
+    public function getURI(): string
+    {
+        $node_id = $this->node_id ?? null;
+        $stat = $this->stat ?? null;
+        if (isset($node_id) && isset($stat)) {
+            return "/_plugins/_ltr/$node_id/stats/$stat";
+        }
+        if (isset($node_id)) {
+            return "/_plugins/_ltr/$node_id/stats";
+        }
+        if (isset($stat)) {
+            return "/_plugins/_ltr/stats/$stat";
+        }
+        return "/_plugins/_ltr/stats";
+    }
+
+    public function getParamWhitelist(): array
+    {
+        return [
+            'timeout',
+            'pretty',
+            'human',
+            'error_trace',
+            'source',
+            'filter_path'
+        ];
+    }
+
+    public function getMethod(): string
+    {
+        return 'GET';
+    }
+
+    public function setNodeId($node_id): static
+    {
+        if (isset($node_id) !== true) {
+            return $this;
+        }
+        if (is_array($node_id) === true) {
+            $node_id = implode(",", $node_id);
+        }
+        $this->node_id = $node_id;
+
+        return $this;
+    }
+
+    public function setStat($stat): static
+    {
+        if (isset($stat) !== true) {
+            return $this;
+        }
+        if (is_array($stat) === true) {
+            $stat = implode(",", $stat);
+        }
+        $this->stat = $stat;
+
+        return $this;
+    }
+}

src/OpenSearch/Namespaces/ClusterNamespace.php

@@ -254,7 +254,7 @@ public function getDecommissionAwareness(array $params = [])
      * Returns cluster settings.
      *
      * $params['cluster_manager_timeout'] = (string) The amount of time to wait for a response from the cluster manager node. For more information about supported time units, see [Common parameters](https://opensearch.org/docs/latest/api-reference/common-parameters/#time-units).
-     * $params['flat_settings']           = (boolean) When `true`, returns cluster settings in a flat format. (Default = false)
+     * $params['flat_settings']           = (boolean) Whether to return settings in the flat form, which can improve readability, especially for heavily nested settings.For example, the flat form of `"cluster": { "max_shards_per_node": 500 }` is `"cluster.max_shards_per_node": "500"`. (Default = false)
      * $params['include_defaults']        = (boolean) When `true`, returns default cluster settings from the local node. (Default = false)
      * $params['master_timeout']          = (string)
      * $params['timeout']                 = (string)
@@ -362,8 +362,8 @@ public function pendingTasks(array $params = [])
     /**
      * Updates the cluster voting configuration by excluding certain node IDs or names.
      *
-     * $params['node_ids']    = (any) A comma-separated list of node IDs to excludefrom the voting configuration. When using this setting, you cannot also specify `node_names`.
-     * $params['node_names']  = (any) A comma-separated list of node names to exclude from thevoting configuration. When using this setting, you cannot also specify `node_ids`.
+     * $params['node_ids']    = (any) A comma-separated list of node IDs to excludefrom the voting configuration. When using this setting, you cannot also specify `node_names`. Either `node_ids` or `node_names` are required to receive a valid response.
+     * $params['node_names']  = (any) A comma-separated list of node names to exclude from thevoting configuration. When using this setting, you cannot also specify `node_ids`. Either `node_ids` or `node_names` are required to receive a valid response.
      * $params['timeout']     = (string) When adding a voting configuration exclusion, the API waits for thespecified nodes to be excluded from the voting configuration beforereturning a response. If the timeout expires before the appropriate conditionis satisfied, the request fails and returns an error.
      * $params['pretty']      = (boolean) Whether to pretty format the returned JSON response. (Default = false)
      * $params['human']       = (boolean) Whether to return human readable values for statistics. (Default = true)
@@ -385,7 +385,7 @@ public function postVotingConfigExclusions(array $params = [])
     /**
      * Creates or updates a component template.
      *
-     * $params['name']                    = (string) The name of the component template to create. OpenSearch includes the following built-in component templates: `logs-mappings`; `logs-settings`; `metrics-mappings`; `metrics-settings`; `synthetics-mapping`; `synthetics-settings`. OpenSearch uses these templates to configure backing indexes for its data streams. If you want to overwrite one of these templates, set the replacement template `version` to a higher value than the current version. If you want to disable all built-in component and index templates, set `stack.templates.enabled` to `false` using the Cluster Update Settings API.
+     * $params['name']                    = (string) The name of the component template to create. OpenSearch includes the following built-in component templates: `logs-mappings`, `logs-settings`, `metrics-mappings`, `metrics-settings`, `synthetics-mapping`, and `synthetics-settings`. OpenSearch uses these templates to configure backing indexes for its data streams. If you want to overwrite one of these templates, set the replacement template `version` to a higher value than the current version. If you want to disable all built-in component and index templates, set `stack.templates.enabled` to `false` using the [Cluster Update Settings API](https://opensearch.org/docs/latest/api-reference/cluster-api/cluster-settings/).
      * $params['cluster_manager_timeout'] = (string) The amount of time to wait for a response from the cluster manager node. For more information about supported time units, see [Common parameters](https://opensearch.org/docs/latest/api-reference/common-parameters/#time-units).
      * $params['create']                  = (boolean) When `true`, this request cannot replace or update existing component templates. (Default = false)
      * $params['master_timeout']          = (string)
@@ -444,7 +444,7 @@ public function putDecommissionAwareness(array $params = [])
      * Updates the cluster settings.
      *
      * $params['cluster_manager_timeout'] = (string) The amount of time to wait for a response from the cluster manager node. For more information about supported time units, see [Common parameters](https://opensearch.org/docs/latest/api-reference/common-parameters/#time-units).
-     * $params['flat_settings']           = (boolean) Returns settings in a flat format. (Default = false)
+     * $params['flat_settings']           = (boolean) Whether to return settings in the flat form, which can improve readability, especially for heavily nested settings.For example, the flat form of `"cluster": { "max_shards_per_node": 500 }` is `"cluster.max_shards_per_node": "500"`. (Default = false)
      * $params['master_timeout']          = (string)
      * $params['timeout']                 = (string)
      * $params['pretty']                  = (boolean) Whether to pretty format the returned JSON response. (Default = false)
@@ -548,12 +548,12 @@ public function reroute(array $params = [])
     /**
      * Returns comprehensive information about the state of the cluster.
      *
-     * $params['metric']                    = (array) Limits the information returned to only the specified metrics.
+     * $params['metric']                    = (array) Limits the information returned to only the [specified metric groups](https://opensearch.org/docs/latest/api-reference/cluster-api/cluster-stats/#metric-groups).
      * $params['index']                     = (array)
      * $params['allow_no_indices']          = (boolean) Whether to ignore a wildcard index expression that resolves into no concrete indexes. This includes the `_all` string or when no indexes have been specified.
-     * $params['cluster_manager_timeout']   = (string) The amount of time to wait for a response from the cluster manager node. For more information about supported time units, see [Common parameters]({https://opensearch.org/docs/latest/api-reference/common-parameters/#time-units).
+     * $params['cluster_manager_timeout']   = (string) The amount of time to wait for a response from the cluster manager node. For more information about supported time units, see [Common parameters](https://opensearch.org/docs/latest/api-reference/common-parameters/#time-units).
      * $params['expand_wildcards']          = (any)
-     * $params['flat_settings']             = (boolean) Returns settings in a flat format. (Default = false)
+     * $params['flat_settings']             = (boolean) Whether to return settings in the flat form, which can improve readability, especially for heavily nested settings.For example, the flat form of `"cluster": { "max_shards_per_node": 500 }` is `"cluster.max_shards_per_node": "500"`. (Default = false)
      * $params['ignore_unavailable']        = (boolean) Whether the specified concrete indexes should be ignored when unavailable (missing or closed).
      * $params['local']                     = (boolean) Whether to return information from the local node only instead of from the cluster manager node. (Default = false)
      * $params['master_timeout']            = (string)
@@ -584,10 +584,10 @@ public function state(array $params = [])
     /**
      * Returns a high-level overview of cluster statistics.
      *
-     * $params['index_metric']  = (array) A comma-separated list of index metric groups, for example, `docs,store`.
+     * $params['index_metric']  = (array) A comma-separated list of [index metric groups](https://opensearch.org/docs/latest/api-reference/cluster-api/cluster-stats/#index-metric-groups), for example, `docs,store`.
      * $params['metric']        = (array) Limit the information returned to the specified metrics.
      * $params['node_id']       = (array)
-     * $params['flat_settings'] = (boolean) When `true`, returns settings in a flat format. (Default = false)
+     * $params['flat_settings'] = (boolean) Whether to return settings in the flat form, which can improve readability, especially for heavily nested settings.For example, the flat form of `"cluster": { "max_shards_per_node": 500 }` is `"cluster.max_shards_per_node": "500"`. (Default = false)
      * $params['timeout']       = (string) The amount of time to wait for each node to respond.If a node does not respond before its timeout expires, the response does not include its stats.However, timed out nodes are included in the response's `_nodes.failed` property. Defaults to no timeout.
      * $params['pretty']        = (boolean) Whether to pretty format the returned JSON response. (Default = false)
      * $params['human']         = (boolean) Whether to return human readable values for statistics. (Default = true)

src/OpenSearch/Namespaces/IngestNamespace.php

@@ -35,12 +35,12 @@
 class IngestNamespace extends AbstractNamespace
 {
     /**
-     * Deletes a pipeline.
+     * Deletes an ingest pipeline.
      *
-     * $params['id']                      = (string) Pipeline ID or wildcard expression of pipeline IDs used to limit the request. To delete all ingest pipelines in a cluster, use a value of `*`.
-     * $params['cluster_manager_timeout'] = (string) Operation timeout for connection to cluster-manager node.
+     * $params['id']                      = (string) The pipeline ID or wildcard expression of pipeline IDs used to limit the request. To delete all ingest pipelines in a cluster, use a value of `*`.
+     * $params['cluster_manager_timeout'] = (string) The amount of time allowed to establish a connection to the cluster manager node.
      * $params['master_timeout']          = (string) Period to wait for a connection to the cluster-manager node.If no response is received before the timeout expires, the request fails and returns an error.
-     * $params['timeout']                 = (string) Period to wait for a response.If no response is received before the timeout expires, the request fails and returns an error.
+     * $params['timeout']                 = (string) The amount of time to wait for a response.
      * $params['pretty']                  = (boolean) Whether to pretty format the returned JSON response. (Default = false)
      * $params['human']                   = (boolean) Whether to return human readable values for statistics. (Default = true)
      * $params['error_trace']             = (boolean) Whether to include the stack trace of returned errors. (Default = false)
@@ -62,10 +62,10 @@ public function deletePipeline(array $params = [])
     }
 
     /**
-     * Returns a pipeline.
+     * Returns an ingest pipeline.
      *
-     * $params['id']                      = (string) Comma-separated list of pipeline IDs to retrieve. Wildcard (`*`) expressions are supported. To get all ingest pipelines, omit this parameter or use `*`.
-     * $params['cluster_manager_timeout'] = (string) Operation timeout for connection to cluster-manager node.
+     * $params['id']                      = (string) A comma-separated list of pipeline IDs to retrieve. Wildcard (`*`) expressions are supported. To get all ingest pipelines, omit this parameter or use `*`.
+     * $params['cluster_manager_timeout'] = (string) The amount of time allowed to establish a connection to the cluster manager node.
      * $params['master_timeout']          = (string) Period to wait for a connection to the cluster-manager node.If no response is received before the timeout expires, the request fails and returns an error.
      * $params['pretty']                  = (boolean) Whether to pretty format the returned JSON response. (Default = false)
      * $params['human']                   = (boolean) Whether to return human readable values for statistics. (Default = true)
@@ -88,9 +88,9 @@ public function getPipeline(array $params = [])
     }
 
     /**
-     * Returns a list of the built-in patterns.
+     * Returns a list of built-in grok patterns.
      *
-     * $params['s']           = (boolean) Sort returned patterns by key name. (Default = false)
+     * $params['s']           = (boolean) Determines how to sort returned grok patterns by key name. (Default = false)
      * $params['pretty']      = (boolean) Whether to pretty format the returned JSON response. (Default = false)
      * $params['human']       = (boolean) Whether to return human readable values for statistics. (Default = true)
      * $params['error_trace'] = (boolean) Whether to include the stack trace of returned errors. (Default = false)
@@ -109,18 +109,18 @@ public function processorGrok(array $params = [])
     }
 
     /**
-     * Creates or updates a pipeline.
+     * Creates or updates an ingest pipeline.
      *
-     * $params['id']                      = (string) ID of the ingest pipeline to create or update.
-     * $params['cluster_manager_timeout'] = (string) Operation timeout for connection to cluster-manager node.
+     * $params['id']                      = (string) The ID of the ingest pipeline.
+     * $params['cluster_manager_timeout'] = (string) The amount of time allowed to establish a connection to the cluster manager node.
      * $params['master_timeout']          = (string) Period to wait for a connection to the cluster-manager node. If no response is received before the timeout expires, the request fails and returns an error.
-     * $params['timeout']                 = (string) Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.
+     * $params['timeout']                 = (string) The amount of time to wait for a response.
      * $params['pretty']                  = (boolean) Whether to pretty format the returned JSON response. (Default = false)
      * $params['human']                   = (boolean) Whether to return human readable values for statistics. (Default = true)
      * $params['error_trace']             = (boolean) Whether to include the stack trace of returned errors. (Default = false)
      * $params['source']                  = (string) The URL-encoded request definition. Useful for libraries that do not accept a request body for non-POST requests.
      * $params['filter_path']             = (any) Used to reduce the response. This parameter takes a comma-separated list of filters. It supports using wildcards to match any field or part of a field’s name. You can also exclude fields with "-".
-     * $params['body']                    = (array) The ingest definition (Required)
+     * $params['body']                    = (array) The ingest definition. (Required)
      *
      * @param array $params Associative array of parameters
      * @return array
@@ -139,10 +139,10 @@ public function putPipeline(array $params = [])
     }
 
     /**
-     * Allows to simulate a pipeline with example documents.
+     * Simulates an ingest pipeline with example documents.
      *
-     * $params['id']          = (string) Pipeline to test. If you don't specify a `pipeline` in the request body, this parameter is required.
-     * $params['verbose']     = (boolean) If `true`, the response includes output data for each processor in the executed pipeline. (Default = false)
+     * $params['id']          = (string) The pipeline to test. If you don't specify a `pipeline` in the request body, this parameter is required.
+     * $params['verbose']     = (boolean) When `true`, the response includes output data for each processor in the pipeline (Default = false)
      * $params['pretty']      = (boolean) Whether to pretty format the returned JSON response. (Default = false)
      * $params['human']       = (boolean) Whether to return human readable values for statistics. (Default = true)
      * $params['error_trace'] = (boolean) Whether to include the stack trace of returned errors. (Default = false)