From 7c6e3b7bc0b71d62daba0a04fd893b691b21dddf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EC=A1=B0=ED=98=9C=EC=98=A8?= <68319395+hye-on@users.noreply.github.com> Date: Thu, 23 Jan 2025 06:39:11 +0900 Subject: [PATCH 1/2] Add time field to getStats schema in _common.yml (#803) * Add time field to getStats schema in _common.yml Signed-off-by: hye-on * Update CHANGELOG for GetStats schema changes Signed-off-by: hye-on * Mark getTime as deprecated Signed-off-by: hye-on * Add x-version-deprecated and x-version-added 2.19 to schema Signed-off-by: hye-on --------- Signed-off-by: hye-on Signed-off-by: Daniel (dB.) Doubrovkine Co-authored-by: Daniel (dB.) Doubrovkine --- CHANGELOG.md | 1 + spec/schemas/_common.yaml | 5 +++++ 2 files changed, 6 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index b90de9cc..073dcec2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -54,6 +54,7 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) - Added `GET`, `POST /_plugins/_ml/tasks/_search`, `GET /_plugins/_ml/tools`, `tools/{tool_name}` ([#797](https://github.com/opensearch-project/opensearch-api-specification/pull/797)) - Added `POST /_plugins/_ml/agents/{agent_id}/_execute`, `GET /_plugins/_ml/agents/{agent_id}`, `GET`, `POST /_plugins/_ml/agents/_search` ([#798](https://github.com/opensearch-project/opensearch-api-specification/pull/798)) - Added a warning for test file names that don't match the API being tested ([#793](https://github.com/opensearch-project/opensearch-api-specification/pull/793)) +- Added `time` field to the `GetStats` schema in `_common.yml` ([#803](https://github.com/opensearch-project/opensearch-api-specification/pull/803)) - Added version for `POST /_plugins/_ml/_train/{algorithm_name}`, `_predict/{algorithm_name}/{model_id}`, and `_train_predict/{algorithm_name}` ([#763](https://github.com/opensearch-project/opensearch-api-specification/pull/763)) ### Removed diff --git a/spec/schemas/_common.yaml b/spec/schemas/_common.yaml index 6a50f39c..516d3f95 100644 --- a/spec/schemas/_common.yaml +++ b/spec/schemas/_common.yaml @@ -1724,6 +1724,11 @@ components: format: int64 getTime: $ref: '#/components/schemas/Duration' + deprecated: true + x-version-deprecated: '2.19' + time: + $ref: '#/components/schemas/Duration' + x-version-added: '2.19' time_in_millis: $ref: '#/components/schemas/DurationValueUnitMillis' exists_total: From 592336afb88844f0c5785ba4b085dba3884ac580 Mon Sep 17 00:00:00 2001 From: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> Date: Thu, 23 Jan 2025 13:24:45 -0600 Subject: [PATCH 2/2] Update Cluster namespace descriptions (#806) * Cluser namespace descriptions. Signed-off-by: Archer * Fix linter Signed-off-by: Archer * Apply suggestions from code review Co-authored-by: Nathan Bower Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> * Update spec/namespaces/cluster.yaml Co-authored-by: Nathan Bower Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> --------- Signed-off-by: Archer Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> Co-authored-by: Nathan Bower --- spec/namespaces/cluster.yaml | 228 ++++++++++++++--------------------- spec/schemas/_common.yaml | 4 + 2 files changed, 93 insertions(+), 139 deletions(-) diff --git a/spec/namespaces/cluster.yaml b/spec/namespaces/cluster.yaml index 566cf317..7a6f13c8 100644 --- a/spec/namespaces/cluster.yaml +++ b/spec/namespaces/cluster.yaml @@ -9,7 +9,7 @@ paths: operationId: cluster.allocation_explain.0 x-operation-group: cluster.allocation_explain x-version-added: '1.0' - description: Provides explanations for shard allocations in the cluster. + description: Explains how shards are allocated in the current cluster and provides an explanation for why unassigned shards can't be allocated to a node. externalDocs: url: https://opensearch.org/docs/latest/api-reference/cluster-api/cluster-allocation/ parameters: @@ -24,7 +24,7 @@ paths: operationId: cluster.allocation_explain.1 x-operation-group: cluster.allocation_explain x-version-added: '1.0' - description: Provides explanations for shard allocations in the cluster. + description: Explains how shards are allocated in the current cluster and provides an explanation for why unassigned shards can't be allocated to a node. externalDocs: url: https://opensearch.org/docs/latest/api-reference/cluster-api/cluster-allocation/ parameters: @@ -40,7 +40,7 @@ paths: operationId: cluster.delete_decommission_awareness.0 x-operation-group: cluster.delete_decommission_awareness x-version-added: '1.0' - description: Delete any existing decommission. + description: Recommissions a decommissioned zone. externalDocs: url: https://opensearch.org/docs/latest/api-reference/cluster-api/cluster-decommission/#example-decommissioning-and-recommissioning-a-zone responses: @@ -51,7 +51,7 @@ paths: operationId: cluster.get_decommission_awareness.0 x-operation-group: cluster.get_decommission_awareness x-version-added: '1.0' - description: Get details and status of decommissioned attribute. + description: Retrieves the decommission status for all zones. externalDocs: url: https://opensearch.org/docs/latest/api-reference/cluster-api/cluster-decommission/#example-getting-zone-decommission-status parameters: @@ -64,7 +64,7 @@ paths: operationId: cluster.put_decommission_awareness.0 x-operation-group: cluster.put_decommission_awareness x-version-added: '1.0' - description: Decommissions an awareness attribute. + description: Decommissions a cluster zone based on awareness. This can greatly benefit multi-zone deployments, where awareness attributes can aid in applying new upgrades to a cluster in a controlled fashion. externalDocs: url: https://opensearch.org/docs/latest/api-reference/cluster-api/cluster-decommission/#example-decommissioning-and-recommissioning-a-zone parameters: @@ -130,8 +130,8 @@ paths: x-operation-group: cluster.pending_tasks x-version-added: '1.0' description: |- - Returns a list of any cluster-level changes (e.g. create index, update mapping, - allocate or fail shard) which have not yet been executed. + Returns a list of pending cluster-level tasks, such as index creation, mapping updates, + or new allocations. externalDocs: url: https://opensearch.org/docs/latest parameters: @@ -241,7 +241,7 @@ paths: operationId: cluster.state.0 x-operation-group: cluster.state x-version-added: '1.0' - description: Returns a comprehensive information about the state of the cluster. + description: Returns comprehensive information about the state of the cluster. externalDocs: url: https://opensearch.org/docs/latest parameters: @@ -262,7 +262,7 @@ paths: operationId: cluster.state.1 x-operation-group: cluster.state x-version-added: '1.0' - description: Returns a comprehensive information about the state of the cluster. + description: Returns comprehensive information about the state of the cluster. externalDocs: url: https://opensearch.org/docs/latest parameters: @@ -284,7 +284,7 @@ paths: operationId: cluster.state.2 x-operation-group: cluster.state x-version-added: '1.0' - description: Returns a comprehensive information about the state of the cluster. + description: Returns comprehensive information about the state of the cluster. externalDocs: url: https://opensearch.org/docs/latest parameters: @@ -307,7 +307,7 @@ paths: operationId: cluster.stats.0 x-operation-group: cluster.stats x-version-added: '1.0' - description: Returns high-level overview of cluster statistics. + description: Returns a high-level overview of cluster statistics. externalDocs: url: https://opensearch.org/docs/latest/api-reference/cluster-api/cluster-stats/ parameters: @@ -321,7 +321,7 @@ paths: operationId: cluster.stats.1 x-operation-group: cluster.stats x-version-added: '1.0' - description: Returns high-level overview of cluster statistics. + description: Returns a high-level overview of cluster statistics. externalDocs: url: https://opensearch.org/docs/latest/api-reference/cluster-api/cluster-stats/ parameters: @@ -336,7 +336,7 @@ paths: operationId: cluster.stats.2 x-operation-group: cluster.stats x-version-added: '2.18' - description: Returns high-level overview of cluster statistics. + description: Returns a high-level overview of cluster statistics. externalDocs: url: https://opensearch.org/docs/latest/api-reference/cluster-api/cluster-stats/ parameters: @@ -352,7 +352,7 @@ paths: operationId: cluster.stats.3 x-operation-group: cluster.stats x-version-added: '2.18' - description: Returns high-level overview of cluster statistics. + description: Returns a high-level overview of cluster statistics. externalDocs: url: https://opensearch.org/docs/latest/api-reference/cluster-api/cluster-stats/ parameters: @@ -369,7 +369,7 @@ paths: operationId: cluster.post_voting_config_exclusions.0 x-operation-group: cluster.post_voting_config_exclusions x-version-added: '1.0' - description: Updates the cluster voting config exclusions by node ids or node names. + description: Updates the cluster voting configuration by excluding certain node IDs or names. externalDocs: url: https://opensearch.org/docs/latest parameters: @@ -383,7 +383,7 @@ paths: operationId: cluster.delete_voting_config_exclusions.0 x-operation-group: cluster.delete_voting_config_exclusions x-version-added: '1.0' - description: Clears cluster voting config exclusions. + description: Clears any cluster voting configuration exclusions. externalDocs: url: https://opensearch.org/docs/latest parameters: @@ -526,13 +526,13 @@ components: index: $ref: '../schemas/_common.yaml#/components/schemas/IndexName' primary: - description: If `true`, returns explanation for the primary shard for the given shard ID. + description: When `true`, returns a routing explanation for the primary shard based on the node ID. type: boolean shard: description: Specifies the ID of the shard that you would like an explanation for. type: integer format: int32 - description: The index, shard, and primary flag to explain. Empty means 'explain the first unassigned shard' + description: The index, shard, and primary flag for which to generate an explanation. Leave this empty to generate an explanation for the first unassigned shard. cluster.put_component_template: content: application/json: @@ -541,10 +541,9 @@ components: properties: allow_auto_create: description: |- - This setting overrides the value of the `action.auto_create_index` cluster setting. - If set to `true` in a template, then indexes can be automatically created using that - template even if auto-creation of indexes is disabled using `actions.auto_create_index`. - If set to `false` then data streams matching the template must always be explicitly created. + This setting overrides the `action.auto_create_index` cluster setting. + When set to `true` in a component template, indexes are automatically created using that + template. When set to `false`, data streams matching the component template must always be explicitly created. type: boolean template: $ref: '../schemas/indices._common.yaml#/components/schemas/IndexState' @@ -554,7 +553,7 @@ components: $ref: '../schemas/_common.yaml#/components/schemas/Metadata' required: - template - description: The template definition + description: The template definition. required: true cluster.put_settings: content: @@ -568,7 +567,7 @@ components: transient: type: object additionalProperties: {} - description: The settings to be updated. Can be either `transient` or `persistent` (survives cluster restart). + description: The cluster settings to update. required: true cluster.reroute: content: @@ -577,7 +576,7 @@ components: type: object properties: commands: - description: Defines the commands to perform. + description: Defines the reroute commands to perform, either `move`, `cancel`, or `allocate`. type: array items: $ref: '../schemas/cluster.reroute.yaml#/components/schemas/Command' @@ -786,9 +785,8 @@ components: $ref: '../schemas/cluster.reroute.yaml#/components/schemas/RerouteExplanation' state: description: |- - There aren't any guarantees on the output/structure of the raw cluster state. - Here you will find the internal representation of the cluster, which can - differ from the external representation. + Shows the internal representation of the structure, which can + differ from the external representation. cluster.state@200: content: application/json: @@ -802,22 +800,22 @@ components: - type: object properties: cluster_name: - description: Name of the cluster, based on the Cluster name setting setting. + description: The name of the cluster. $ref: '../schemas/_common.yaml#/components/schemas/Name' cluster_uuid: - description: Unique identifier for the cluster. + description: The unique identifier of the cluster. $ref: '../schemas/_common.yaml#/components/schemas/Uuid' indices: - description: Contains statistics about indexes with shards assigned to selected nodes. + description: Displays statistics about indexes in the cluster. $ref: '../schemas/cluster.stats.yaml#/components/schemas/ClusterIndices' nodes: - description: Contains statistics about nodes selected by the request's node filters. + description: Displays statistics about nodes selected by the request's node filters. $ref: '../schemas/cluster.stats.yaml#/components/schemas/ClusterNodes' status: - description: Health status of the cluster, based on the state of its primary and replica shards. + description: The health status of the cluster, based on the state of its primary and replica shards. $ref: '../schemas/_common.yaml#/components/schemas/HealthStatus' timestamp: - description: Unix timestamp, in milliseconds, for the last time the cluster statistics were refreshed. + description: The Unix timestamp, in milliseconds, indicating when any cluster statistics were last refreshed. $ref: '../schemas/_common.yaml#/components/schemas/EpochTimeUnitMillis' required: - cluster_name @@ -828,7 +826,7 @@ components: cluster.allocation_explain::query.include_disk_info: in: query name: include_disk_info - description: If `true`, returns information about disk usage and shard sizes. + description: When `true`, returns information about disk usage and shard sizes. schema: type: boolean default: false @@ -836,7 +834,7 @@ components: cluster.allocation_explain::query.include_yes_decisions: in: query name: include_yes_decisions - description: If `true`, returns YES decisions in explanation. + description: When `true`, returns any `YES` decisions in the allocation explanation. schema: type: boolean default: false @@ -845,8 +843,8 @@ components: in: path name: name description: |- - Name of the component template to delete. - Wildcard (*) expressions are supported. + The name of the component template to delete. + Supports wildcard (*) expressions. required: true schema: $ref: '../schemas/_common.yaml#/components/schemas/Name' @@ -861,9 +859,6 @@ components: cluster.delete_component_template::query.master_timeout: in: query name: master_timeout - description: |- - 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. deprecated: true schema: $ref: '../schemas/_common.yaml#/components/schemas/Duration' @@ -873,9 +868,6 @@ components: cluster.delete_component_template::query.timeout: in: query name: timeout - description: |- - Period to wait for a response. - If no response is received before the timeout expires, the request fails and returns an error. schema: $ref: '../schemas/_common.yaml#/components/schemas/Duration' style: form @@ -885,8 +877,8 @@ components: description: |- Specifies whether to wait for all excluded nodes to be removed from the cluster before clearing the voting configuration exclusions list. - Defaults to true, meaning that all excluded nodes must be removed from - the cluster before this API takes any action. If set to `false` then the + When `true`, all excluded nodes are removed from + the cluster before this API takes any action. When `false`, the voting configuration exclusions list is cleared even if some excluded nodes are still in the cluster. schema: @@ -897,7 +889,7 @@ components: in: path name: name description: |- - Name of the component template to check existence of. + The name of the component template. Wildcard (*) expressions are supported. required: true schema: @@ -906,7 +898,6 @@ components: cluster.exists_component_template::query.cluster_manager_timeout: name: cluster_manager_timeout in: query - description: Operation timeout for connection to cluster-manager node. schema: $ref: '../schemas/_common.yaml#/components/schemas/Duration' x-version-added: '2.0' @@ -914,8 +905,8 @@ components: in: query name: local description: |- - If `true`, the request retrieves information from the local node only. - Defaults to false, which means information is retrieved from the cluster-manager node. + When `true`, the request retrieves information from the local node only. + When `false, information is retrieved from the cluster manager node. schema: type: boolean default: false @@ -923,10 +914,6 @@ components: cluster.exists_component_template::query.master_timeout: in: query name: master_timeout - description: |- - 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. deprecated: true schema: $ref: '../schemas/_common.yaml#/components/schemas/Duration' @@ -937,7 +924,7 @@ components: in: path name: name description: |- - Name of the component template to retrieve. + The name of the component template to retrieve. Wildcard (`*`) expressions are supported. required: true schema: @@ -946,7 +933,6 @@ components: cluster.get_component_template::query.cluster_manager_timeout: name: cluster_manager_timeout in: query - description: Operation timeout for connection to cluster-manager node. schema: $ref: '../schemas/_common.yaml#/components/schemas/Duration' x-version-added: '2.0' @@ -962,8 +948,8 @@ components: in: query name: local description: |- - If `true`, the request retrieves information from the local node only. - If `false`, information is retrieved from the cluster-manager node. + When `true`, the request retrieves information from the local node only. + When `false`, information is retrieved from the cluster manager node. schema: type: boolean default: false @@ -971,9 +957,6 @@ components: cluster.get_component_template::query.master_timeout: in: query name: master_timeout - description: |- - 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. deprecated: true schema: $ref: '../schemas/_common.yaml#/components/schemas/Duration' @@ -983,22 +966,21 @@ components: cluster.get_decommission_awareness::path.awareness_attribute_name: name: awareness_attribute_name in: path - description: Awareness attribute name. + description: The name of the awareness attribute. schema: type: string - description: Awareness attribute name. + description: The name of the awareness attribute. required: true cluster.get_settings::query.cluster_manager_timeout: name: cluster_manager_timeout in: query - description: Operation timeout for connection to cluster-manager node. schema: $ref: '../schemas/_common.yaml#/components/schemas/Duration' x-version-added: '2.0' cluster.get_settings::query.flat_settings: in: query name: flat_settings - description: If `true`, returns settings in flat format. + description: When `true`, returns cluster settings in a flat format. schema: type: boolean default: false @@ -1006,7 +988,7 @@ components: cluster.get_settings::query.include_defaults: in: query name: include_defaults - description: If `true`, returns default cluster settings from the local node. + description: When `true`, returns default cluster settings from the local node. schema: type: boolean default: false @@ -1014,9 +996,6 @@ components: cluster.get_settings::query.master_timeout: in: query name: master_timeout - description: |- - 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. deprecated: true schema: $ref: '../schemas/_common.yaml#/components/schemas/Duration' @@ -1026,24 +1005,20 @@ components: cluster.get_settings::query.timeout: in: query name: timeout - description: |- - Period to wait for a response. - If no response is received before the timeout expires, the request fails and returns an error. schema: $ref: '../schemas/_common.yaml#/components/schemas/Duration' style: form cluster.get_weighted_routing::path.attribute: name: attribute in: path - description: Awareness attribute name. + description: The name of the awareness attribute. schema: type: string - description: Awareness attribute name. + description: The name of the awareness attribute. required: true cluster.health::path.index: in: path name: index - description: Comma-separated list of data streams, indexes, and index aliases used to limit the request. Wildcard expressions (*) are supported. To target all data streams and indexes in a cluster, omit this parameter or use `_all` or `*`. required: true schema: $ref: '../schemas/_common.yaml#/components/schemas/Indices' @@ -1051,35 +1026,33 @@ components: cluster.health::query.awareness_attribute: name: awareness_attribute in: query - description: The awareness attribute for which the health is required. + description: The name of the awareness attribute for which to return the cluster health status (for example, `zone`). Applicable only if `level` is set to `awareness_attributes`. schema: type: string - description: The awareness attribute for which the health is required. + description: The name of the awareness attribute for which to return the cluster health status (for example, `zone`). Applicable only if `level` is set to `awareness_attributes`. cluster.health::query.cluster_manager_timeout: name: cluster_manager_timeout in: query - description: Operation timeout for connection to cluster-manager node. schema: $ref: '../schemas/_common.yaml#/components/schemas/Duration' x-version-added: '2.0' cluster.health::query.expand_wildcards: in: query name: expand_wildcards - description: Whether to expand wildcard expression to concrete indexes that are open, closed or both. schema: $ref: '../schemas/_common.yaml#/components/schemas/ExpandWildcards' style: form cluster.health::query.level: in: query name: level - description: Can be one of cluster, indexes or shards. Controls the details level of the health information returned. schema: $ref: '../schemas/cluster.health.yaml#/components/schemas/Level' + default: cluster style: form cluster.health::query.local: in: query name: local - description: If `true`, the request retrieves information from the local node only. Defaults to false, which means information is retrieved from the cluster-manager node. + description: Whether to return information from the local node only instead of from the cluster manager node. schema: type: boolean default: false @@ -1087,7 +1060,6 @@ components: cluster.health::query.master_timeout: in: query name: master_timeout - description: 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. deprecated: true schema: $ref: '../schemas/_common.yaml#/components/schemas/Duration' @@ -1097,42 +1069,40 @@ components: cluster.health::query.timeout: in: query name: timeout - description: Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error. schema: $ref: '../schemas/_common.yaml#/components/schemas/Duration' style: form cluster.health::query.wait_for_active_shards: in: query name: wait_for_active_shards - description: A number controlling to how many active shards to wait for, all to wait for all shards in the cluster to be active, or 0 to not wait. schema: $ref: '../schemas/_common.yaml#/components/schemas/WaitForActiveShards' style: form cluster.health::query.wait_for_events: in: query name: wait_for_events - description: Can be one of immediate, urgent, high, normal, low, languid. Wait until all currently queued events with the given priority are processed. schema: $ref: '../schemas/_common.yaml#/components/schemas/WaitForEvents' style: form cluster.health::query.wait_for_no_initializing_shards: in: query name: wait_for_no_initializing_shards - description: A Boolean value which controls whether to wait (until the timeout provided) for the cluster to have no shard initializations. Defaults to false, which means it will not wait for initializing shards. + description: Whether to wait until there are no initializing shards in the cluster. schema: type: boolean + default: false style: form cluster.health::query.wait_for_no_relocating_shards: in: query name: wait_for_no_relocating_shards - description: A Boolean value which controls whether to wait (until the timeout provided) for the cluster to have no shard relocations. Defaults to false, which means it will not wait for relocating shards. + description: Whether to wait until there are no relocating shards in the cluster. schema: type: boolean style: form cluster.health::query.wait_for_nodes: in: query name: wait_for_nodes - description: The request waits until the specified number N of nodes is available. It also accepts >=N, <=N, >N and =N`, `<=N`, `>N`, and ` yellow > red. By default, will not wait for any status. + description: Waits until the cluster health reaches the specified status or better. schema: $ref: '../schemas/_common.yaml#/components/schemas/HealthStatus' style: form cluster.pending_tasks::query.cluster_manager_timeout: name: cluster_manager_timeout in: query - description: Operation timeout for connection to cluster-manager node. schema: $ref: '../schemas/_common.yaml#/components/schemas/Duration' x-version-added: '2.0' @@ -1156,8 +1125,8 @@ components: in: query name: local description: |- - If `true`, the request retrieves information from the local node only. - If `false`, information is retrieved from the cluster-manager node. + When `true`, the request retrieves information from the local node only. + When `false`, information is retrieved from the cluster manager node. schema: type: boolean default: false @@ -1165,9 +1134,6 @@ components: cluster.pending_tasks::query.master_timeout: in: query name: master_timeout - description: |- - 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. deprecated: true schema: $ref: '../schemas/_common.yaml#/components/schemas/Duration' @@ -1178,8 +1144,8 @@ components: in: query name: node_ids description: |- - A comma-separated list of the persistent ids of the nodes to exclude - from the voting configuration. If specified, you may not also specify `node_names`. + A comma-separated list of node IDs to exclude + from the voting configuration. When using this setting, you cannot also specify `node_names`. schema: $ref: '../schemas/_common.yaml#/components/schemas/Ids' style: form @@ -1187,8 +1153,8 @@ components: in: query name: node_names description: |- - A comma-separated list of the names of the nodes to exclude from the - voting configuration. If specified, you may not also specify `node_ids`. + A comma-separated list of node names to exclude from the + voting configuration. When using this setting, you cannot also specify `node_ids`. schema: $ref: '../schemas/_common.yaml#/components/schemas/Names' style: form @@ -1198,7 +1164,7 @@ components: description: |- When adding a voting configuration exclusion, the API waits for the specified nodes to be excluded from the voting configuration before - returning. If the timeout expires before the appropriate condition + returning a response. If the timeout expires before the appropriate condition is satisfied, the request fails and returns an error. schema: $ref: '../schemas/_common.yaml#/components/schemas/Duration' @@ -1207,11 +1173,11 @@ components: in: path name: name description: |- - Name of the component template to create. + 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 Agent uses these templates to configure backing indexes for its data streams. - If you use OpenSearch Agent and want to overwrite one of these templates, set the `version` for your replacement template higher than the current version. - If you don't use OpenSearch Agent and want to disable all built-in component and index templates, set `stack.templates.enabled` to `false` using the cluster update settings API. + 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. required: true schema: $ref: '../schemas/_common.yaml#/components/schemas/Name' @@ -1219,14 +1185,13 @@ components: cluster.put_component_template::query.cluster_manager_timeout: name: cluster_manager_timeout in: query - description: Operation timeout for connection to cluster-manager node. schema: $ref: '../schemas/_common.yaml#/components/schemas/Duration' x-version-added: '2.0' cluster.put_component_template::query.create: in: query name: create - description: If `true`, this request cannot replace or update existing component templates. + description: When `true`, this request cannot replace or update existing component templates. schema: type: boolean default: false @@ -1234,9 +1199,6 @@ components: cluster.put_component_template::query.master_timeout: in: query name: master_timeout - description: |- - 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. deprecated: true schema: $ref: '../schemas/_common.yaml#/components/schemas/Duration' @@ -1246,36 +1208,34 @@ components: cluster.put_component_template::query.timeout: name: timeout in: query - description: Operation timeout. schema: $ref: '../schemas/_common.yaml#/components/schemas/Duration' cluster.put_decommission_awareness::path.awareness_attribute_name: name: awareness_attribute_name in: path - description: Awareness attribute name. + description: The name of the awareness attribute. schema: type: string - description: Awareness attribute name. + description: The name of the awareness attribute. required: true cluster.put_decommission_awareness::path.awareness_attribute_value: name: awareness_attribute_value in: path - description: Awareness attribute value. + description: The value of the awareness attribute. schema: type: string - description: Awareness attribute value. + description: The value of the awareness attribute. required: true cluster.put_settings::query.cluster_manager_timeout: name: cluster_manager_timeout in: query - description: Operation timeout for connection to cluster-manager node. schema: $ref: '../schemas/_common.yaml#/components/schemas/Duration' x-version-added: '2.0' cluster.put_settings::query.flat_settings: in: query name: flat_settings - description: Return settings in flat format. + description: Returns settings in a flat format. schema: type: boolean default: false @@ -1283,7 +1243,6 @@ components: cluster.put_settings::query.master_timeout: in: query name: master_timeout - description: Explicit operation timeout for connection to cluster-manager node deprecated: true schema: $ref: '../schemas/_common.yaml#/components/schemas/Duration' @@ -1293,43 +1252,40 @@ components: cluster.put_settings::query.timeout: in: query name: timeout - description: Explicit operation timeout schema: $ref: '../schemas/_common.yaml#/components/schemas/Duration' style: form cluster.put_weighted_routing::path.attribute: name: attribute in: path - description: Awareness attribute name. + description: The name of the awareness attribute. schema: type: string - description: Awareness attribute name. + description: The name of the awareness attribute. required: true cluster.reroute::query.cluster_manager_timeout: name: cluster_manager_timeout in: query - description: Operation timeout for connection to cluster-manager node. schema: $ref: '../schemas/_common.yaml#/components/schemas/Duration' x-version-added: '2.0' cluster.reroute::query.dry_run: in: query name: dry_run - description: If `true`, then the request simulates the operation only and returns the resulting state. + description: When `true`, the request simulates the operation and returns the resulting state. schema: type: boolean style: form cluster.reroute::query.explain: in: query name: explain - description: If `true`, then the response contains an explanation of why the commands can or cannot be executed. + description: When `true`, the response contains an explanation of why certain commands can or cannot be executed. schema: type: boolean style: form cluster.reroute::query.master_timeout: in: query name: master_timeout - description: 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. deprecated: true schema: $ref: '../schemas/_common.yaml#/components/schemas/Duration' @@ -1350,21 +1306,19 @@ components: cluster.reroute::query.retry_failed: in: query name: retry_failed - description: If `true`, then retries allocation of shards that are blocked due to too many subsequent allocation failures. + description: When `true`, retries shard allocation if it was blocked because of too many subsequent failures. schema: type: boolean style: form cluster.reroute::query.timeout: in: query name: timeout - description: Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error. schema: $ref: '../schemas/_common.yaml#/components/schemas/Duration' style: form cluster.state::path.index: in: path name: index - description: A comma-separated list of index names; use `_all` or empty string to perform the operation on all indexes required: true schema: $ref: '../schemas/_common.yaml#/components/schemas/Indices' @@ -1372,7 +1326,7 @@ components: cluster.state::path.metric: in: path name: metric - description: Limit the information returned to the specified metrics + description: Limits the information returned to only the specified metrics. required: true schema: type: array @@ -1382,28 +1336,26 @@ components: cluster.state::query.allow_no_indices: in: query name: allow_no_indices - description: Whether to ignore if a wildcard indexes expression resolves into no concrete indexes. (This includes `_all` string or when no indexes have been specified) + description: 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. schema: type: boolean style: form cluster.state::query.cluster_manager_timeout: name: cluster_manager_timeout in: query - description: Operation timeout for connection to cluster-manager node. schema: $ref: '../schemas/_common.yaml#/components/schemas/Duration' x-version-added: '2.0' cluster.state::query.expand_wildcards: in: query name: expand_wildcards - description: Whether to expand wildcard expression to concrete indexes that are open, closed or both. schema: $ref: '../schemas/_common.yaml#/components/schemas/ExpandWildcards' style: form cluster.state::query.flat_settings: in: query name: flat_settings - description: Return settings in flat format. + description: Returns settings in a flat format. schema: type: boolean default: false @@ -1411,14 +1363,14 @@ components: cluster.state::query.ignore_unavailable: in: query name: ignore_unavailable - description: Whether specified concrete indexes should be ignored when unavailable (missing or closed) + description: Whether the specified concrete indexes should be ignored when unavailable (missing or closed). schema: type: boolean style: form cluster.state::query.local: in: query name: local - description: Return local information, do not retrieve the state from cluster-manager node. + description: Whether to return information from the local node only instead of from the cluster manager node. schema: type: boolean default: false @@ -1426,7 +1378,6 @@ components: cluster.state::query.master_timeout: in: query name: master_timeout - description: Specify timeout for connection to cluster manager. deprecated: true schema: $ref: '../schemas/_common.yaml#/components/schemas/Duration' @@ -1450,7 +1401,7 @@ components: cluster.stats::path.index_metric: in: path name: index_metric - description: Limit the information returned for indexes metric to the specific index metrics. It can be used only if indexes (or all) metric is specified. + description: A comma-separated list of index metric groups, for example, `docs,store`. required: true schema: type: array @@ -1471,7 +1422,6 @@ components: cluster.stats::path.node_id: in: path name: node_id - description: Comma-separated list of node filters used to limit returned information. Defaults to all nodes in the cluster. required: true schema: $ref: '../schemas/_common.yaml#/components/schemas/NodeIds' @@ -1479,7 +1429,7 @@ components: cluster.stats::query.flat_settings: in: query name: flat_settings - description: If `true`, returns settings in flat format. + description: When `true`, returns settings in a flat format. schema: type: boolean default: false @@ -1488,7 +1438,7 @@ components: in: query name: timeout description: |- - Period to wait for each node to respond. + 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. schema: diff --git a/spec/schemas/_common.yaml b/spec/schemas/_common.yaml index 516d3f95..14baf70d 100644 --- a/spec/schemas/_common.yaml +++ b/spec/schemas/_common.yaml @@ -782,6 +782,7 @@ components: - 'true' - wait_for WaitForActiveShards: + description: Waits until the specified number of shards is active before returning a response. Use `all` for all shards. oneOf: - title: count type: integer @@ -821,6 +822,7 @@ components: items: $ref: '#/components/schemas/Name' NodeIds: + description: A comma-separated list of node IDs used to filter results. Supports [node filters](https://opensearch.org/docs/latest/api-reference/nodes-apis/index/#node-filters). oneOf: - $ref: '#/components/schemas/NodeId' - type: array @@ -1049,12 +1051,14 @@ components: ulong: type: number Level: + description: Specifies the level of detail of the returned information. type: string enum: - cluster - indices - shards WaitForEvents: + description: Waits until all currently queued events with the given priority are processed. type: string enum: - high