diff --git a/CHANGELOG.md b/CHANGELOG.md index 1c290244..7e2e9709 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,7 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) ### Removed ### Fixed ### Updated APIs +- Updated opensearch-php APIs to reflect [opensearch-api-specification@b67104c](https://github.com/opensearch-project/opensearch-api-specification/commit/b67104c30e515702df88bba9c173d04033d07a45) ### Security ### Dependencies diff --git a/src/OpenSearch/Endpoints/Indices/Exists.php b/src/OpenSearch/Endpoints/Indices/Exists.php index 9d90b98f..0968b109 100644 --- a/src/OpenSearch/Endpoints/Indices/Exists.php +++ b/src/OpenSearch/Endpoints/Indices/Exists.php @@ -42,6 +42,7 @@ public function getParamWhitelist(): array { return [ 'allow_no_indices', + 'cluster_manager_timeout', 'expand_wildcards', 'flat_settings', 'ignore_unavailable', diff --git a/src/OpenSearch/Endpoints/Indices/PutAlias.php b/src/OpenSearch/Endpoints/Indices/PutAlias.php index a4d28852..62599f4c 100644 --- a/src/OpenSearch/Endpoints/Indices/PutAlias.php +++ b/src/OpenSearch/Endpoints/Indices/PutAlias.php @@ -21,7 +21,6 @@ namespace OpenSearch\Endpoints\Indices; -use OpenSearch\Common\Exceptions\RuntimeException; use OpenSearch\Endpoints\AbstractEndpoint; /** @@ -33,19 +32,18 @@ class PutAlias extends AbstractEndpoint public function getURI(): string { - if (isset($this->index) !== true) { - throw new RuntimeException( - 'index is required for put_alias' - ); + $name = $this->name ?? null; + $index = $this->index ?? null; + if (isset($index) && isset($name)) { + return "/$index/_alias/$name"; } - $index = $this->index; - if (isset($this->name) !== true) { - throw new RuntimeException( - 'name is required for put_alias' - ); + if (isset($index)) { + return "/$index/_alias"; } - $name = $this->name; - return "/$index/_alias/$name"; + if (isset($name)) { + return "/_alias/$name"; + } + return "/_alias"; } public function getParamWhitelist(): array diff --git a/src/OpenSearch/Endpoints/Nodes/Info.php b/src/OpenSearch/Endpoints/Nodes/Info.php index 4d8cca2c..39bb5c6b 100644 --- a/src/OpenSearch/Endpoints/Nodes/Info.php +++ b/src/OpenSearch/Endpoints/Nodes/Info.php @@ -28,22 +28,21 @@ */ class Info extends AbstractEndpoint { + protected $node_id_or_metric; protected $metric; protected $node_id; public function getURI(): string { + $node_id_or_metric = $this->node_id_or_metric ?? null; $metric = $this->metric ?? null; $node_id = $this->node_id ?? null; + if (isset($node_id_or_metric)) { + return "/_nodes/$node_id_or_metric"; + } if (isset($node_id) && isset($metric)) { return "/_nodes/$node_id/$metric"; } - if (isset($node_id)) { - return "/_nodes/$node_id"; - } - if (isset($metric)) { - return "/_nodes/$metric"; - } return "/_nodes"; } @@ -65,6 +64,16 @@ public function getMethod(): string return 'GET'; } + public function setNodeIdOrMetric($node_id_or_metric): Info + { + if (isset($node_id_or_metric) !== true) { + return $this; + } + $this->node_id_or_metric = $node_id_or_metric; + + return $this; + } + public function setMetric($metric): Info { if (isset($metric) !== true) { diff --git a/src/OpenSearch/Endpoints/Sql/Close.php b/src/OpenSearch/Endpoints/Sql/Close.php new file mode 100644 index 00000000..2ef15e00 --- /dev/null +++ b/src/OpenSearch/Endpoints/Sql/Close.php @@ -0,0 +1,57 @@ +body = $body; + + return $this; + } +} diff --git a/src/OpenSearch/Endpoints/Sql/Explain.php b/src/OpenSearch/Endpoints/Sql/Explain.php index ef0269ca..6291c3b3 100644 --- a/src/OpenSearch/Endpoints/Sql/Explain.php +++ b/src/OpenSearch/Endpoints/Sql/Explain.php @@ -1,5 +1,7 @@ body = $body; + + return $this; + } } diff --git a/src/OpenSearch/Endpoints/Sql/GetStats.php b/src/OpenSearch/Endpoints/Sql/GetStats.php new file mode 100644 index 00000000..d0992feb --- /dev/null +++ b/src/OpenSearch/Endpoints/Sql/GetStats.php @@ -0,0 +1,47 @@ +body = $body; + + return $this; + } +} diff --git a/src/OpenSearch/Endpoints/Sql/Query.php b/src/OpenSearch/Endpoints/Sql/Query.php index 1ba8170f..c92970e0 100644 --- a/src/OpenSearch/Endpoints/Sql/Query.php +++ b/src/OpenSearch/Endpoints/Sql/Query.php @@ -1,5 +1,7 @@ body = $body; + + return $this; + } } diff --git a/src/OpenSearch/Namespaces/IndicesNamespace.php b/src/OpenSearch/Namespaces/IndicesNamespace.php index 65d41c1b..7d6b5ca5 100644 --- a/src/OpenSearch/Namespaces/IndicesNamespace.php +++ b/src/OpenSearch/Namespaces/IndicesNamespace.php @@ -412,18 +412,19 @@ public function deleteTemplate(array $params = []) /** * Returns information about whether a particular index exists. * - * $params['index'] = (array) Comma-separated list of data streams, indices, and aliases. Supports wildcards (`*`). - * $params['allow_no_indices'] = (boolean) If `false`, the request returns an error if any wildcard expression, index alias, or `_all` value targets only missing or closed indices.This behavior applies even if the request targets other open indices. (Default = false) - * $params['expand_wildcards'] = (any) Type of index that wildcard patterns can match.If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams.Supports comma-separated values, such as `open,hidden`.Valid values are: `all`, `open`, `closed`, `hidden`, `none`. - * $params['flat_settings'] = (boolean) If `true`, returns settings in flat format. (Default = false) - * $params['ignore_unavailable'] = (boolean) If `false`, the request returns an error if it targets a missing or closed index. (Default = false) - * $params['include_defaults'] = (boolean) If `true`, return all default settings in the response. (Default = false) - * $params['local'] = (boolean) If `true`, the request retrieves information from the local node only. (Default = false) - * $params['pretty'] = (boolean) Whether to pretty format the returned JSON response. - * $params['human'] = (boolean) Whether to return human readable values for statistics. - * $params['error_trace'] = (boolean) Whether to include the stack trace of returned errors. - * $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) Comma-separated list of filters used to reduce the response. + * $params['index'] = (array) Comma-separated list of data streams, indices, and aliases. Supports wildcards (`*`). + * $params['allow_no_indices'] = (boolean) If `false`, the request returns an error if any wildcard expression, index alias, or `_all` value targets only missing or closed indices.This behavior applies even if the request targets other open indices. (Default = false) + * $params['cluster_manager_timeout'] = (string) Operation timeout for connection to cluster-manager node. + * $params['expand_wildcards'] = (any) Type of index that wildcard patterns can match.If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams.Supports comma-separated values, such as `open,hidden`.Valid values are: `all`, `open`, `closed`, `hidden`, `none`. + * $params['flat_settings'] = (boolean) If `true`, returns settings in flat format. (Default = false) + * $params['ignore_unavailable'] = (boolean) If `false`, the request returns an error if it targets a missing or closed index. (Default = false) + * $params['include_defaults'] = (boolean) If `true`, return all default settings in the response. (Default = false) + * $params['local'] = (boolean) If `true`, the request retrieves information from the local node only. (Default = false) + * $params['pretty'] = (boolean) Whether to pretty format the returned JSON response. + * $params['human'] = (boolean) Whether to return human readable values for statistics. + * $params['error_trace'] = (boolean) Whether to include the stack trace of returned errors. + * $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) Comma-separated list of filters used to reduce the response. * * @param array $params Associative array of parameters * @return bool @@ -902,8 +903,8 @@ public function open(array $params = []) /** * Creates or updates an alias. * - * $params['index'] = (array) Comma-separated list of data streams or indices to add. Supports wildcards (`*`). Wildcard patterns that match both data streams and indices return an error. (Required) - * $params['name'] = (string) Alias to update. If the alias doesn't exist, the request creates it. Index alias names support date math. (Required) + * $params['name'] = (string) Alias to update. If the alias doesn't exist, the request creates it. Index alias names support date math. + * $params['index'] = (array) Comma-separated list of data streams or indices to add. Supports wildcards (`*`). Wildcard patterns that match both data streams and indices return an error. * $params['cluster_manager_timeout'] = (string) Operation timeout for connection to cluster-manager node. * $params['master_timeout'] = (string) Period to wait for a connection to the master 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. @@ -919,15 +920,15 @@ public function open(array $params = []) */ public function putAlias(array $params = []) { - $index = $this->extractArgument($params, 'index'); $name = $this->extractArgument($params, 'name'); + $index = $this->extractArgument($params, 'index'); $body = $this->extractArgument($params, 'body'); $endpointBuilder = $this->endpoints; $endpoint = $endpointBuilder('Indices\PutAlias'); $endpoint->setParams($params); - $endpoint->setIndex($index); $endpoint->setName($name); + $endpoint->setIndex($index); $endpoint->setBody($body); return $this->performRequest($endpoint); diff --git a/src/OpenSearch/Namespaces/NodesNamespace.php b/src/OpenSearch/Namespaces/NodesNamespace.php index e9b39043..e9baf762 100644 --- a/src/OpenSearch/Namespaces/NodesNamespace.php +++ b/src/OpenSearch/Namespaces/NodesNamespace.php @@ -63,27 +63,30 @@ public function hotThreads(array $params = []) /** * Returns information about nodes in the cluster. * - * $params['metric'] = (array) Limits the information returned to the specific metrics. Supports a comma-separated list, such as http,ingest. - * $params['node_id'] = (array) Comma-separated list of node IDs or names used to limit returned information. - * $params['flat_settings'] = (boolean) If true, returns settings in flat format. (Default = false) - * $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['pretty'] = (boolean) Whether to pretty format the returned JSON response. - * $params['human'] = (boolean) Whether to return human readable values for statistics. - * $params['error_trace'] = (boolean) Whether to include the stack trace of returned errors. - * $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) Comma-separated list of filters used to reduce the response. + * $params['node_id_or_metric'] = (any) Limits the information returned to a list of node IDs or specific metrics. Supports a comma-separated list, such as node1,node2 or http,ingest. + * $params['metric'] = (array) Limits the information returned to the specific metrics. Supports a comma-separated list, such as http,ingest. + * $params['node_id'] = (array) Comma-separated list of node IDs or names used to limit returned information. + * $params['flat_settings'] = (boolean) If true, returns settings in flat format. (Default = false) + * $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['pretty'] = (boolean) Whether to pretty format the returned JSON response. + * $params['human'] = (boolean) Whether to return human readable values for statistics. + * $params['error_trace'] = (boolean) Whether to include the stack trace of returned errors. + * $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) Comma-separated list of filters used to reduce the response. * * @param array $params Associative array of parameters * @return array */ public function info(array $params = []) { + $node_id_or_metric = $this->extractArgument($params, 'node_id_or_metric'); $metric = $this->extractArgument($params, 'metric'); $node_id = $this->extractArgument($params, 'node_id'); $endpointBuilder = $this->endpoints; $endpoint = $endpointBuilder('Nodes\Info'); $endpoint->setParams($params); + $endpoint->setNodeIdOrMetric($node_id_or_metric); $endpoint->setMetric($metric); $endpoint->setNodeId($node_id); diff --git a/src/OpenSearch/Namespaces/SqlNamespace.php b/src/OpenSearch/Namespaces/SqlNamespace.php index 19285cfb..8f58f545 100644 --- a/src/OpenSearch/Namespaces/SqlNamespace.php +++ b/src/OpenSearch/Namespaces/SqlNamespace.php @@ -1,5 +1,7 @@ endpoints; + $body = $this->extractArgument($params, 'body'); - /** @var AbstractEndpoint $endpoint */ - $endpoint = $endpointBuilder('Sql\Query'); - $endpoint->setBody(array_filter([ - 'query' => $this->extractArgument($params, 'query'), - 'cursor' => $this->extractArgument($params, 'cursor'), - 'fetch_size' => $this->extractArgument($params, 'fetch_size'), - ])); + $endpointBuilder = $this->endpoints; + $endpoint = $endpointBuilder('Sql\Close'); $endpoint->setParams($params); + $endpoint->setBody($body); return $this->performRequest($endpoint); } - /** - * $params['query'] = (string) The SQL Query + * Shows how a query is executed against OpenSearch. * - * @param array{'query': string} $params Associative array of parameters + * $params['format'] = (string) A short version of the Accept header, e.g. json, yaml. + * $params['sanitize'] = (boolean) Specifies whether to escape special characters in the results (Default = true) + * $params['pretty'] = (boolean) Whether to pretty format the returned JSON response. + * $params['human'] = (boolean) Whether to return human readable values for statistics. + * $params['error_trace'] = (boolean) Whether to include the stack trace of returned errors. + * $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) Comma-separated list of filters used to reduce the response. + * + * @param array $params Associative array of parameters * @return array */ - public function explain(array $params): array + public function explain(array $params = []) { - $endpointBuilder = $this->endpoints; - - $query = $this->extractArgument($params, 'query'); + $body = $this->extractArgument($params, 'body'); - /** @var AbstractEndpoint $endpoint */ + $endpointBuilder = $this->endpoints; $endpoint = $endpointBuilder('Sql\Explain'); - $endpoint->setBody([ - 'query' => $query, - ]); $endpoint->setParams($params); + $endpoint->setBody($body); return $this->performRequest($endpoint); } + /** + * Collect metrics for the plugin within the interval. + * + * $params['format'] = (string) A short version of the Accept header, e.g. json, yaml. + * $params['sanitize'] = (boolean) Specifies whether to escape special characters in the results (Default = true) + * $params['pretty'] = (boolean) Whether to pretty format the returned JSON response. + * $params['human'] = (boolean) Whether to return human readable values for statistics. + * $params['error_trace'] = (boolean) Whether to include the stack trace of returned errors. + * $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) Comma-separated list of filters used to reduce the response. + * + * @param array $params Associative array of parameters + * @return array + */ + public function getStats(array $params = []) + { + $endpointBuilder = $this->endpoints; + $endpoint = $endpointBuilder('Sql\GetStats'); + $endpoint->setParams($params); + return $this->performRequest($endpoint); + } /** - * $params['cursor'] = (string) The cursor given by the server + * By a stats endpoint, you are able to collect metrics for the plugin within the interval. * - * @param array{'cursor': string} $params Associative array of parameters + * $params['format'] = (string) A short version of the Accept header, e.g. json, yaml. + * $params['sanitize'] = (boolean) Specifies whether to escape special characters in the results (Default = true) + * $params['pretty'] = (boolean) Whether to pretty format the returned JSON response. + * $params['human'] = (boolean) Whether to return human readable values for statistics. + * $params['error_trace'] = (boolean) Whether to include the stack trace of returned errors. + * $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) Comma-separated list of filters used to reduce the response. + * + * @param array $params Associative array of parameters * @return array */ - public function closeCursor(array $params): array + public function postStats(array $params = []) { + $body = $this->extractArgument($params, 'body'); + $endpointBuilder = $this->endpoints; + $endpoint = $endpointBuilder('Sql\PostStats'); + $endpoint->setParams($params); + $endpoint->setBody($body); - /** @var AbstractEndpoint $endpoint */ - $endpoint = $endpointBuilder('Sql\CursorClose'); - $endpoint->setBody(array_filter([ - 'cursor' => $this->extractArgument($params, 'cursor'), - ])); + return $this->performRequest($endpoint); + } + /** + * Send a SQL/PPL query to the SQL plugin. + * + * $params['format'] = (string) A short version of the Accept header, e.g. json, yaml. + * $params['sanitize'] = (boolean) Specifies whether to escape special characters in the results (Default = true) + * $params['pretty'] = (boolean) Whether to pretty format the returned JSON response. + * $params['human'] = (boolean) Whether to return human readable values for statistics. + * $params['error_trace'] = (boolean) Whether to include the stack trace of returned errors. + * $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) Comma-separated list of filters used to reduce the response. + * + * @param array $params Associative array of parameters + * @return array + */ + public function query(array $params = []) + { + $body = $this->extractArgument($params, 'body'); + + $endpointBuilder = $this->endpoints; + $endpoint = $endpointBuilder('Sql\Query'); $endpoint->setParams($params); + $endpoint->setBody($body); return $this->performRequest($endpoint); }