From f4b8b9df49d99c0d7d50ac48184e20c6aae0305f Mon Sep 17 00:00:00 2001 From: dblock Date: Sat, 27 Jul 2024 03:35:04 +0000 Subject: [PATCH] Updated opensearch-php to reflect the latest OpenSearch API spec (2024-07-27) Signed-off-by: GitHub --- CHANGELOG.md | 1 + src/OpenSearch/Endpoints/Indices/Exists.php | 1 + src/OpenSearch/Endpoints/Indices/PutAlias.php | 22 ++- src/OpenSearch/Endpoints/Nodes/Info.php | 21 ++- src/OpenSearch/Endpoints/Sql/Close.php | 57 ++++++++ src/OpenSearch/Endpoints/Sql/Explain.php | 31 +++- src/OpenSearch/Endpoints/Sql/GetStats.php | 47 +++++++ src/OpenSearch/Endpoints/Sql/PostStats.php | 57 ++++++++ src/OpenSearch/Endpoints/Sql/Query.php | 31 +++- .../Namespaces/IndicesNamespace.php | 33 ++--- src/OpenSearch/Namespaces/NodesNamespace.php | 21 +-- src/OpenSearch/Namespaces/SqlNamespace.php | 133 +++++++++++++----- 12 files changed, 368 insertions(+), 87 deletions(-) create mode 100644 src/OpenSearch/Endpoints/Sql/Close.php create mode 100644 src/OpenSearch/Endpoints/Sql/GetStats.php create mode 100644 src/OpenSearch/Endpoints/Sql/PostStats.php diff --git a/CHANGELOG.md b/CHANGELOG.md index 1c2902445..59d89387f 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@aec3145](https://github.com/opensearch-project/opensearch-api-specification/commit/aec314547f64b13a7f57d9e8834d45ca5795e010) ### Security ### Dependencies diff --git a/src/OpenSearch/Endpoints/Indices/Exists.php b/src/OpenSearch/Endpoints/Indices/Exists.php index 9d90b98f2..0968b1090 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 a4d288520..62599f4c6 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 4d8cca2c5..39bb5c6b8 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 000000000..2ef15e00e --- /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 ef0269ca0..6291c3b39 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 000000000..d0992feba --- /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 1ba8170f9..c92970e0c 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 65d41c1be..7d6b5ca56 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 e9b390430..e9baf762c 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 19285cfb0..8f58f545f 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); }