diff --git a/docs/examples/languageExamples.json b/docs/examples/languageExamples.json index 73dedecac3..c4370d8881 100644 --- a/docs/examples/languageExamples.json +++ b/docs/examples/languageExamples.json @@ -16836,5 +16836,27 @@ "language": "Java", "code": "client.sql().query(q -> q\n .format(SqlFormat.Txt)\n .query(\"SELECT * FROM library ORDER BY page_count DESC LIMIT 5\")\n);\n" } + ], + "specification/cluster/allocation_explain/examples/request/ClusterAllocationExplainRequestExample2.yaml": [ + { + "language": "Python", + "code": "resp = client.cluster.allocation_explain(\n index=\"my-index-000001\",\n shard=\"0\",\n primary=False,\n current_node=\"my-node\",\n)" + }, + { + "language": "JavaScript", + "code": "const response = await client.cluster.allocationExplain({\n index: \"my-index-000001\",\n shard: 0,\n primary: \"false\",\n current_node: \"my-node\",\n});" + }, + { + "language": "Ruby", + "code": "response = client.cluster.allocation_explain(\n index: \"my-index-000001\",\n shard: \"0\",\n primary: \"false\",\n current_node: \"my-node\",\n body: {}\n)" + }, + { + "language": "PHP", + "code": "$resp = $client->cluster()->allocationExplain([\n \"index\" => \"my-index-000001\",\n \"shard\" => \"0\",\n \"primary\" => \"false\",\n \"current_node\" => \"my-node\",\n \"body\" => new ArrayObject([]),\n]);" + }, + { + "language": "curl", + "code": "curl -X GET -H \"Authorization: ApiKey $ELASTIC_API_KEY\" -H \"Content-Type: application/json\" -d '{}' \"$ELASTICSEARCH_URL/_cluster/allocation/explain?index=my-index-000001&shard=0&primary=false¤t_node=my-node\"" + } ] } \ No newline at end of file diff --git a/output/openapi/elasticsearch-openapi.json b/output/openapi/elasticsearch-openapi.json index 441003ddae..7091d45b23 100644 --- a/output/openapi/elasticsearch-openapi.json +++ b/output/openapi/elasticsearch-openapi.json @@ -4641,13 +4641,25 @@ "cluster" ], "summary": "Explain the shard allocations", - "description": "Get explanations for shard allocations in the cluster.\nFor unassigned shards, it provides an explanation for why the shard is unassigned.\nFor assigned shards, it provides an explanation for why the shard is remaining on its current node and has not moved or rebalanced to another node.\nThis API can be very useful when attempting to diagnose why a shard is unassigned or why a shard continues to remain on its current node when you might expect otherwise.\nRefer to the linked documentation for examples of how to troubleshoot allocation issues using this API.", + "description": "Get explanations for shard allocations in the cluster.\nThis API accepts the current_node, index, primary and shard parameters in the request body or in query parameters, but not in both at the same time.\nFor unassigned shards, it provides an explanation for why the shard is unassigned.\nFor assigned shards, it provides an explanation for why the shard is remaining on its current node and has not moved or rebalanced to another node.\nThis API can be very useful when attempting to diagnose why a shard is unassigned or why a shard continues to remain on its current node when you might expect otherwise.\nRefer to the linked documentation for examples of how to troubleshoot allocation issues using this API.", "externalDocs": { "url": "https://www.elastic.co/docs/troubleshoot/elasticsearch/cluster-allocation-api-examples", "x-previousVersionUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/8.18/cluster-allocation-explain.html" }, "operationId": "cluster-allocation-explain", "parameters": [ + { + "$ref": "#/components/parameters/cluster.allocation_explain-index" + }, + { + "$ref": "#/components/parameters/cluster.allocation_explain-shard" + }, + { + "$ref": "#/components/parameters/cluster.allocation_explain-primary" + }, + { + "$ref": "#/components/parameters/cluster.allocation_explain-current_node" + }, { "$ref": "#/components/parameters/cluster.allocation_explain-include_disk_info" }, @@ -4679,13 +4691,25 @@ "cluster" ], "summary": "Explain the shard allocations", - "description": "Get explanations for shard allocations in the cluster.\nFor unassigned shards, it provides an explanation for why the shard is unassigned.\nFor assigned shards, it provides an explanation for why the shard is remaining on its current node and has not moved or rebalanced to another node.\nThis API can be very useful when attempting to diagnose why a shard is unassigned or why a shard continues to remain on its current node when you might expect otherwise.\nRefer to the linked documentation for examples of how to troubleshoot allocation issues using this API.", + "description": "Get explanations for shard allocations in the cluster.\nThis API accepts the current_node, index, primary and shard parameters in the request body or in query parameters, but not in both at the same time.\nFor unassigned shards, it provides an explanation for why the shard is unassigned.\nFor assigned shards, it provides an explanation for why the shard is remaining on its current node and has not moved or rebalanced to another node.\nThis API can be very useful when attempting to diagnose why a shard is unassigned or why a shard continues to remain on its current node when you might expect otherwise.\nRefer to the linked documentation for examples of how to troubleshoot allocation issues using this API.", "externalDocs": { "url": "https://www.elastic.co/docs/troubleshoot/elasticsearch/cluster-allocation-api-examples", "x-previousVersionUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/8.18/cluster-allocation-explain.html" }, "operationId": "cluster-allocation-explain-1", "parameters": [ + { + "$ref": "#/components/parameters/cluster.allocation_explain-index" + }, + { + "$ref": "#/components/parameters/cluster.allocation_explain-shard" + }, + { + "$ref": "#/components/parameters/cluster.allocation_explain-primary" + }, + { + "$ref": "#/components/parameters/cluster.allocation_explain-current_node" + }, { "$ref": "#/components/parameters/cluster.allocation_explain-include_disk_info" }, @@ -116279,6 +116303,46 @@ }, "style": "simple" }, + "cluster.allocation_explain-index": { + "in": "query", + "name": "index", + "description": "The name of the index that you would like an explanation for.", + "deprecated": false, + "schema": { + "$ref": "#/components/schemas/_types.IndexName" + }, + "style": "form" + }, + "cluster.allocation_explain-shard": { + "in": "query", + "name": "shard", + "description": "An identifier for the shard that you would like an explanation for.", + "deprecated": false, + "schema": { + "type": "number" + }, + "style": "form" + }, + "cluster.allocation_explain-primary": { + "in": "query", + "name": "primary", + "description": "If true, returns an explanation for the primary shard for the specified shard ID.", + "deprecated": false, + "schema": { + "type": "boolean" + }, + "style": "form" + }, + "cluster.allocation_explain-current_node": { + "in": "query", + "name": "current_node", + "description": "Explain a shard only if it is currently located on the specified node name or node ID.", + "deprecated": false, + "schema": { + "$ref": "#/components/schemas/_types.NodeId" + }, + "style": "form" + }, "cluster.allocation_explain-include_disk_info": { "in": "query", "name": "include_disk_info", @@ -124831,27 +124895,32 @@ "schema": { "type": "object", "properties": { - "current_node": { - "description": "Specifies the node ID or the name of the node to only explain a shard that is currently located on the specified node.", - "type": "string" - }, "index": { "$ref": "#/components/schemas/_types.IndexName" }, + "shard": { + "description": "An identifier for the shard that you would like an explanation for.", + "type": "number" + }, "primary": { - "description": "If true, returns explanation for the primary shard for the given shard ID.", + "description": "If true, returns an explanation for the primary shard for the specified shard ID.", "type": "boolean" }, - "shard": { - "description": "Specifies the ID of the shard that you would like an explanation for.", - "type": "number" + "current_node": { + "$ref": "#/components/schemas/_types.NodeId" } } }, "examples": { "ClusterAllocationExplainRequestExample1": { + "summary": "All parameters in the request body", "description": "Run `GET _cluster/allocation/explain` to get an explanation for a shard's current allocation.", "value": "{\n \"index\": \"my-index-000001\",\n \"shard\": 0,\n \"primary\": false,\n \"current_node\": \"my-node\"\n}" + }, + "ClusterAllocationExplainRequestExample2": { + "summary": "Query Parameters", + "description": "Run `GET _cluster/allocation/explain?index=my-index-000001&shard=0&primary=false¤t_node=my-node` to get an explanation for a shard's current allocation. No parameters are required in the request body\n", + "value": "{}" } } } diff --git a/output/schema/schema.json b/output/schema/schema.json index e189bc5736..0271bdc357 100644 --- a/output/schema/schema.json +++ b/output/schema/schema.json @@ -2371,7 +2371,7 @@ "stability": "stable" } }, - "description": "Explain the shard allocations.\nGet explanations for shard allocations in the cluster.\nFor unassigned shards, it provides an explanation for why the shard is unassigned.\nFor assigned shards, it provides an explanation for why the shard is remaining on its current node and has not moved or rebalanced to another node.\nThis API can be very useful when attempting to diagnose why a shard is unassigned or why a shard continues to remain on its current node when you might expect otherwise.\nRefer to the linked documentation for examples of how to troubleshoot allocation issues using this API.", + "description": "Explain the shard allocations.\nGet explanations for shard allocations in the cluster.\nThis API accepts the current_node, index, primary and shard parameters in the request body or in query parameters, but not in both at the same time.\nFor unassigned shards, it provides an explanation for why the shard is unassigned.\nFor assigned shards, it provides an explanation for why the shard is remaining on its current node and has not moved or rebalanced to another node.\nThis API can be very useful when attempting to diagnose why a shard is unassigned or why a shard continues to remain on its current node when you might expect otherwise.\nRefer to the linked documentation for examples of how to troubleshoot allocation issues using this API.", "docId": "cluster-allocation-explain", "docTag": "cluster", "docUrl": "https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-allocation-explain", @@ -120647,31 +120647,31 @@ "kind": "properties", "properties": [ { - "description": "Specifies the node ID or the name of the node to only explain a shard that is currently located on the specified node.", - "name": "current_node", + "description": "The name of the index that you would like an explanation for.", + "name": "index", "required": false, "type": { "kind": "instance_of", "type": { - "name": "string", - "namespace": "_builtins" + "name": "IndexName", + "namespace": "_types" } } }, { - "description": "Specifies the name of the index that you would like an explanation for.", - "name": "index", + "description": "An identifier for the shard that you would like an explanation for.", + "name": "shard", "required": false, "type": { "kind": "instance_of", "type": { - "name": "IndexName", + "name": "integer", "namespace": "_types" } } }, { - "description": "If true, returns explanation for the primary shard for the given shard ID.", + "description": "If true, returns an explanation for the primary shard for the specified shard ID.", "name": "primary", "required": false, "type": { @@ -120683,20 +120683,20 @@ } }, { - "description": "Specifies the ID of the shard that you would like an explanation for.", - "name": "shard", + "description": "Explain a shard only if it is currently located on the specified node name or node ID.", + "name": "current_node", "required": false, "type": { "kind": "instance_of", "type": { - "name": "integer", + "name": "NodeId", "namespace": "_types" } } } ] }, - "description": "Explain the shard allocations.\nGet explanations for shard allocations in the cluster.\nFor unassigned shards, it provides an explanation for why the shard is unassigned.\nFor assigned shards, it provides an explanation for why the shard is remaining on its current node and has not moved or rebalanced to another node.\nThis API can be very useful when attempting to diagnose why a shard is unassigned or why a shard continues to remain on its current node when you might expect otherwise.\nRefer to the linked documentation for examples of how to troubleshoot allocation issues using this API.", + "description": "Explain the shard allocations.\nGet explanations for shard allocations in the cluster.\nThis API accepts the current_node, index, primary and shard parameters in the request body or in query parameters, but not in both at the same time.\nFor unassigned shards, it provides an explanation for why the shard is unassigned.\nFor assigned shards, it provides an explanation for why the shard is remaining on its current node and has not moved or rebalanced to another node.\nThis API can be very useful when attempting to diagnose why a shard is unassigned or why a shard continues to remain on its current node when you might expect otherwise.\nRefer to the linked documentation for examples of how to troubleshoot allocation issues using this API.", "examples": { "ClusterAllocationExplainRequestExample1": { "alternatives": [ @@ -120727,7 +120727,36 @@ ], "description": "Run `GET _cluster/allocation/explain` to get an explanation for a shard's current allocation.", "method_request": "GET _cluster/allocation/explain", + "summary": "All parameters in the request body", "value": "{\n \"index\": \"my-index-000001\",\n \"shard\": 0,\n \"primary\": false,\n \"current_node\": \"my-node\"\n}" + }, + "ClusterAllocationExplainRequestExample2": { + "alternatives": [ + { + "code": "resp = client.cluster.allocation_explain(\n index=\"my-index-000001\",\n shard=\"0\",\n primary=False,\n current_node=\"my-node\",\n)", + "language": "Python" + }, + { + "code": "const response = await client.cluster.allocationExplain({\n index: \"my-index-000001\",\n shard: 0,\n primary: \"false\",\n current_node: \"my-node\",\n});", + "language": "JavaScript" + }, + { + "code": "response = client.cluster.allocation_explain(\n index: \"my-index-000001\",\n shard: \"0\",\n primary: \"false\",\n current_node: \"my-node\",\n body: {}\n)", + "language": "Ruby" + }, + { + "code": "$resp = $client->cluster()->allocationExplain([\n \"index\" => \"my-index-000001\",\n \"shard\" => \"0\",\n \"primary\" => \"false\",\n \"current_node\" => \"my-node\",\n \"body\" => new ArrayObject([]),\n]);", + "language": "PHP" + }, + { + "code": "curl -X GET -H \"Authorization: ApiKey $ELASTIC_API_KEY\" -H \"Content-Type: application/json\" -d '{}' \"$ELASTICSEARCH_URL/_cluster/allocation/explain?index=my-index-000001&shard=0&primary=false¤t_node=my-node\"", + "language": "curl" + } + ], + "description": "Run `GET _cluster/allocation/explain?index=my-index-000001&shard=0&primary=false¤t_node=my-node` to get an explanation for a shard's current allocation. No parameters are required in the request body\n", + "method_request": "GET _cluster/allocation/explain?index=my-index-000001&shard=0&primary=false¤t_node=my-node", + "summary": "Query Parameters", + "value": "{}" } }, "inherits": { @@ -120742,6 +120771,54 @@ }, "path": [], "query": [ + { + "description": "The name of the index that you would like an explanation for.", + "name": "index", + "required": false, + "type": { + "kind": "instance_of", + "type": { + "name": "IndexName", + "namespace": "_types" + } + } + }, + { + "description": "An identifier for the shard that you would like an explanation for.", + "name": "shard", + "required": false, + "type": { + "kind": "instance_of", + "type": { + "name": "integer", + "namespace": "_types" + } + } + }, + { + "description": "If true, returns an explanation for the primary shard for the specified shard ID.", + "name": "primary", + "required": false, + "type": { + "kind": "instance_of", + "type": { + "name": "boolean", + "namespace": "_builtins" + } + } + }, + { + "description": "Explain a shard only if it is currently located on the specified node name or node ID.", + "name": "current_node", + "required": false, + "type": { + "kind": "instance_of", + "type": { + "name": "NodeId", + "namespace": "_types" + } + } + }, { "description": "If true, returns information about disk usage and shard sizes.", "name": "include_disk_info", @@ -120782,7 +120859,7 @@ } } ], - "specLocation": "cluster/allocation_explain/ClusterAllocationExplainRequest.ts#L25-L81" + "specLocation": "cluster/allocation_explain/ClusterAllocationExplainRequest.ts#L25-L98" }, { "kind": "interface", diff --git a/output/schema/validation-errors.json b/output/schema/validation-errors.json index 1d9e8addf1..4ac54d965a 100644 --- a/output/schema/validation-errors.json +++ b/output/schema/validation-errors.json @@ -1,14 +1,5 @@ { "endpointErrors": { - "cluster.allocation_explain": { - "request": [ - "Request: missing json spec query parameter 'index'", - "Request: missing json spec query parameter 'shard'", - "Request: missing json spec query parameter 'primary'", - "Request: missing json spec query parameter 'current_node'" - ], - "response": [] - }, "msearch": { "request": [ "Request: query parameter 'allow_no_indices' does not exist in the json spec", diff --git a/output/typescript/types.ts b/output/typescript/types.ts index 5de35d3bc2..b04b6c809f 100644 --- a/output/typescript/types.ts +++ b/output/typescript/types.ts @@ -9405,14 +9405,18 @@ export interface ClusterAllocationExplainNodeDiskUsage { } export interface ClusterAllocationExplainRequest extends RequestBase { + index?: IndexName + shard?: integer + primary?: boolean + current_node?: NodeId include_disk_info?: boolean include_yes_decisions?: boolean master_timeout?: Duration body?: { - current_node?: string index?: IndexName - primary?: boolean shard?: integer + primary?: boolean + current_node?: NodeId } } diff --git a/specification/cluster/allocation_explain/ClusterAllocationExplainRequest.ts b/specification/cluster/allocation_explain/ClusterAllocationExplainRequest.ts index 58fa55a931..50cda8f211 100644 --- a/specification/cluster/allocation_explain/ClusterAllocationExplainRequest.ts +++ b/specification/cluster/allocation_explain/ClusterAllocationExplainRequest.ts @@ -18,13 +18,14 @@ */ import { RequestBase } from '@_types/Base' -import { IndexName } from '@_types/common' +import { IndexName, NodeId } from '@_types/common' import { integer } from '@_types/Numeric' import { Duration } from '@_types/Time' /** * Explain the shard allocations. * Get explanations for shard allocations in the cluster. + * This API accepts the current_node, index, primary and shard parameters in the request body or in query parameters, but not in both at the same time. * For unassigned shards, it provides an explanation for why the shard is unassigned. * For assigned shards, it provides an explanation for why the shard is remaining on its current node and has not moved or rebalanced to another node. * This API can be very useful when attempting to diagnose why a shard is unassigned or why a shard continues to remain on its current node when you might expect otherwise. @@ -44,6 +45,22 @@ export interface Request extends RequestBase { } ] query_parameters: { + /** + * The name of the index that you would like an explanation for. + */ + index?: IndexName + /** + * An identifier for the shard that you would like an explanation for. + */ + shard?: integer + /** + * If true, returns an explanation for the primary shard for the specified shard ID. + */ + primary?: boolean + /** + * Explain a shard only if it is currently located on the specified node name or node ID. + */ + current_node?: NodeId /** * If true, returns information about disk usage and shard sizes. * @server_default false @@ -62,20 +79,20 @@ export interface Request extends RequestBase { } body: { /** - * Specifies the node ID or the name of the node to only explain a shard that is currently located on the specified node. + * The name of the index that you would like an explanation for. */ - current_node?: string + index?: IndexName /** - * Specifies the name of the index that you would like an explanation for. + * An identifier for the shard that you would like an explanation for. */ - index?: IndexName + shard?: integer /** - * If true, returns explanation for the primary shard for the given shard ID. + * If true, returns an explanation for the primary shard for the specified shard ID. */ primary?: boolean /** - * Specifies the ID of the shard that you would like an explanation for. + * Explain a shard only if it is currently located on the specified node name or node ID. */ - shard?: integer + current_node?: NodeId } } diff --git a/specification/cluster/allocation_explain/examples/request/ClusterAllocationExplainRequestExample1.yaml b/specification/cluster/allocation_explain/examples/request/ClusterAllocationExplainRequestExample1.yaml index c3ef492eb9..6da3e20091 100644 --- a/specification/cluster/allocation_explain/examples/request/ClusterAllocationExplainRequestExample1.yaml +++ b/specification/cluster/allocation_explain/examples/request/ClusterAllocationExplainRequestExample1.yaml @@ -1,4 +1,4 @@ -# summary: +summary: All parameters in the request body method_request: GET _cluster/allocation/explain description: Run `GET _cluster/allocation/explain` to get an explanation for a shard's current allocation. # type: request diff --git a/specification/cluster/allocation_explain/examples/request/ClusterAllocationExplainRequestExample2.yaml b/specification/cluster/allocation_explain/examples/request/ClusterAllocationExplainRequestExample2.yaml new file mode 100644 index 0000000000..2be7412ad2 --- /dev/null +++ b/specification/cluster/allocation_explain/examples/request/ClusterAllocationExplainRequestExample2.yaml @@ -0,0 +1,8 @@ +summary: Query Parameters +method_request: GET _cluster/allocation/explain?index=my-index-000001&shard=0&primary=false¤t_node=my-node +description: > + Run `GET _cluster/allocation/explain?index=my-index-000001&shard=0&primary=false¤t_node=my-node` to get an explanation for a + shard's current allocation. No parameters are required in the request body +# type: request +value: |- + {}