From 6eab9dd708b814344ede8bbc06ec75c82bb3d615 Mon Sep 17 00:00:00 2001 From: Joshua Adams Date: Wed, 9 Jul 2025 10:20:40 +0100 Subject: [PATCH 1/3] Add Cluster/Allocation/Explain Query Param Example Extends the documentation for the `cluster/allocation/explain` API after query parameter support was added in #129342. A second example request was provided with all four query parameters and an empty request body. --- .../cluster.allocation_explain.json | 16 ++++++ .../ClusterAllocationExplainRequest.ts | 1 + ...usterAllocationExplainRequestExample1.yaml | 2 +- ...usterAllocationExplainRequestExample2.yaml | 54 +++++++++++++++++++ 4 files changed, 72 insertions(+), 1 deletion(-) create mode 100644 specification/cluster/allocation_explain/examples/request/ClusterAllocationExplainRequestExample2.yaml diff --git a/specification/_json_spec/cluster.allocation_explain.json b/specification/_json_spec/cluster.allocation_explain.json index 5845751b8c..245a6ae2b1 100644 --- a/specification/_json_spec/cluster.allocation_explain.json +++ b/specification/_json_spec/cluster.allocation_explain.json @@ -19,6 +19,22 @@ ] }, "params": { + "current_node": { + "type": "string", + "description": "Specifies the node ID or the name of the node to only explain a shard that is currently located on the specified node" + }, + "index": { + "type": "IndexName", + "description": "Specifies the name of the index that you would like an explanation for" + }, + "primary": { + "type": "boolean", + "description": "If true, returns explanation for the primary shard for the given shard ID" + }, + "shard": { + "type": "integer", + "description": "Specifies the ID of the shard that you would like an explanation for" + }, "master_timeout": { "type": "time", "description": "Timeout for connection to master node" diff --git a/specification/cluster/allocation_explain/ClusterAllocationExplainRequest.ts b/specification/cluster/allocation_explain/ClusterAllocationExplainRequest.ts index 58fa55a931..8377d582e0 100644 --- a/specification/cluster/allocation_explain/ClusterAllocationExplainRequest.ts +++ b/specification/cluster/allocation_explain/ClusterAllocationExplainRequest.ts @@ -25,6 +25,7 @@ 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 via the request body, or via query parameters, but not via 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. diff --git a/specification/cluster/allocation_explain/examples/request/ClusterAllocationExplainRequestExample1.yaml b/specification/cluster/allocation_explain/examples/request/ClusterAllocationExplainRequestExample1.yaml index ef53821360..664c9012a3 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..9a55620252 --- /dev/null +++ b/specification/cluster/allocation_explain/examples/request/ClusterAllocationExplainRequestExample2.yaml @@ -0,0 +1,54 @@ +summary: Query Parameters +method_request: GET _cluster/allocation/explain +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: |- + {} +alternatives: + - language: Python + code: |- + resp = client.cluster.allocation_explain( + index="my-index-000001", + shard=0, + primary=False, + current_node="my-node", + ) + - language: JavaScript + code: |- + const response = await client.cluster.allocationExplain({ + index: "my-index-000001", + shard: 0, + primary: false, + current_node: "my-node", + }); + - language: Ruby + code: |- + response = client.cluster.allocation_explain( + index: "my-index-000001", + shard: 0, + primary: false, + current_node: "my-node", + body: {} + ) + - language: PHP + code: |- + $resp = $client->cluster()->allocationExplain([ + "index" => "my-index-000001", + "shard" => 0, + "primary" => false, + "current_node" => "my-node", + "body" => [], + ]); + - language: curl + code: + 'curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" + "$ELASTICSEARCH_URL/_cluster/allocation/explain?index="my-index-000001"&shard=0&primary=false¤t_node="my-node"' + - language: Java + code: | + client.cluster().allocationExplain(a -> a + .currentNode("my-node") + .index("my-index-000001") + .primary(false) + .shard(0) + ); From 695ac41e1c3ea1f72056a4bb7ca77b3461ef5ba7 Mon Sep 17 00:00:00 2001 From: Joshua Adams Date: Wed, 9 Jul 2025 10:36:33 +0100 Subject: [PATCH 2/3] make contrib Autogenerated output from running `make contrib` --- output/openapi/elasticsearch-openapi.json | 10 ++++- output/schema/schema.json | 39 +++++++++++++++++-- output/schema/validation-errors.json | 9 +++++ ...usterAllocationExplainRequestExample2.yaml | 3 +- 4 files changed, 54 insertions(+), 7 deletions(-) diff --git a/output/openapi/elasticsearch-openapi.json b/output/openapi/elasticsearch-openapi.json index 88f00f7017..0b31029143 100644 --- a/output/openapi/elasticsearch-openapi.json +++ b/output/openapi/elasticsearch-openapi.json @@ -4256,7 +4256,7 @@ "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 via the request body, or via query parameters, but not via 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" @@ -4289,7 +4289,7 @@ "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 via the request body, or via query parameters, but not via 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" @@ -120345,8 +120345,14 @@ }, "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 782e2dff77..6bd48fa2e1 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 via the request body, or via query parameters, but not via 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", @@ -120616,7 +120616,7 @@ } ] }, - "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 via the request body, or via query parameters, but not via 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": [ @@ -120647,7 +120647,40 @@ ], "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\" => [],\n]);", + "language": "PHP" + }, + { + "code": "curl -X GET -H \"Authorization: ApiKey $ELASTIC_API_KEY\" \"$ELASTICSEARCH_URL/_cluster/allocation/explain?index=\"my-index-000001\"&shard=0&primary=false¤t_node=\"my-node\"", + "language": "curl" + }, + { + "code": "client.cluster().allocationExplain(a -> a\n .currentNode(\"my-node\")\n .index(\"my-index-000001\")\n .primary(false)\n .shard(0)\n);\n", + "language": "Java" + } + ], + "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", + "summary": "Query Parameters", + "value": "{}" } }, "inherits": { @@ -120702,7 +120735,7 @@ } } ], - "specLocation": "cluster/allocation_explain/ClusterAllocationExplainRequest.ts#L25-L81" + "specLocation": "cluster/allocation_explain/ClusterAllocationExplainRequest.ts#L25-L82" }, { "kind": "interface", diff --git a/output/schema/validation-errors.json b/output/schema/validation-errors.json index b7074cf928..a51c867e39 100644 --- a/output/schema/validation-errors.json +++ b/output/schema/validation-errors.json @@ -7,6 +7,15 @@ ], "response": [] }, + "cluster.allocation_explain": { + "request": [ + "Request: missing json spec query parameter 'current_node'", + "Request: missing json spec query parameter 'index'", + "Request: missing json spec query parameter 'primary'", + "Request: missing json spec query parameter 'shard'" + ], + "response": [] + }, "create": { "request": [ "Request: query parameter 'if_primary_term' does not exist in the json spec", diff --git a/specification/cluster/allocation_explain/examples/request/ClusterAllocationExplainRequestExample2.yaml b/specification/cluster/allocation_explain/examples/request/ClusterAllocationExplainRequestExample2.yaml index 9a55620252..c3f6039348 100644 --- a/specification/cluster/allocation_explain/examples/request/ClusterAllocationExplainRequestExample2.yaml +++ b/specification/cluster/allocation_explain/examples/request/ClusterAllocationExplainRequestExample2.yaml @@ -41,8 +41,7 @@ alternatives: "body" => [], ]); - language: curl - code: - 'curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" + code: 'curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_cluster/allocation/explain?index="my-index-000001"&shard=0&primary=false¤t_node="my-node"' - language: Java code: | From c1a48405554451186c08d1574ee42cc3975ac825 Mon Sep 17 00:00:00 2001 From: Joshua Adams Date: Wed, 9 Jul 2025 11:00:38 +0100 Subject: [PATCH 3/3] Declare query parameters Declared the query parameters, ran make contrib and resolved the validation errors --- output/openapi/elasticsearch-openapi.json | 64 +++++++++++++++++++ output/schema/schema.json | 50 ++++++++++++++- output/schema/validation-errors.json | 9 --- output/typescript/types.ts | 4 ++ .../ClusterAllocationExplainRequest.ts | 16 +++++ 5 files changed, 133 insertions(+), 10 deletions(-) diff --git a/output/openapi/elasticsearch-openapi.json b/output/openapi/elasticsearch-openapi.json index 9ec900645e..72760e9036 100644 --- a/output/openapi/elasticsearch-openapi.json +++ b/output/openapi/elasticsearch-openapi.json @@ -4263,6 +4263,18 @@ }, "operationId": "cluster-allocation-explain", "parameters": [ + { + "$ref": "#/components/parameters/cluster.allocation_explain-current_node" + }, + { + "$ref": "#/components/parameters/cluster.allocation_explain-index" + }, + { + "$ref": "#/components/parameters/cluster.allocation_explain-primary" + }, + { + "$ref": "#/components/parameters/cluster.allocation_explain-shard" + }, { "$ref": "#/components/parameters/cluster.allocation_explain-include_disk_info" }, @@ -4296,6 +4308,18 @@ }, "operationId": "cluster-allocation-explain-1", "parameters": [ + { + "$ref": "#/components/parameters/cluster.allocation_explain-current_node" + }, + { + "$ref": "#/components/parameters/cluster.allocation_explain-index" + }, + { + "$ref": "#/components/parameters/cluster.allocation_explain-primary" + }, + { + "$ref": "#/components/parameters/cluster.allocation_explain-shard" + }, { "$ref": "#/components/parameters/cluster.allocation_explain-include_disk_info" }, @@ -111790,6 +111814,46 @@ }, "style": "simple" }, + "cluster.allocation_explain-current_node": { + "in": "query", + "name": "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.", + "deprecated": false, + "schema": { + "type": "string" + }, + "style": "form" + }, + "cluster.allocation_explain-index": { + "in": "query", + "name": "index", + "description": "Specifies 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-primary": { + "in": "query", + "name": "primary", + "description": "If true, returns explanation for the primary shard for the given shard ID.", + "deprecated": false, + "schema": { + "type": "boolean" + }, + "style": "form" + }, + "cluster.allocation_explain-shard": { + "in": "query", + "name": "shard", + "description": "Specifies the ID of the shard that you would like an explanation for.", + "deprecated": false, + "schema": { + "type": "number" + }, + "style": "form" + }, "cluster.allocation_explain-include_disk_info": { "in": "query", "name": "include_disk_info", diff --git a/output/schema/schema.json b/output/schema/schema.json index 0f94ad6f9e..14a9707fc3 100644 --- a/output/schema/schema.json +++ b/output/schema/schema.json @@ -120695,6 +120695,54 @@ }, "path": [], "query": [ + { + "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", + "required": false, + "type": { + "kind": "instance_of", + "type": { + "name": "string", + "namespace": "_builtins" + } + } + }, + { + "description": "Specifies 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": "If true, returns explanation for the primary shard for the given shard ID.", + "name": "primary", + "required": false, + "type": { + "kind": "instance_of", + "type": { + "name": "boolean", + "namespace": "_builtins" + } + } + }, + { + "description": "Specifies the ID of 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 information about disk usage and shard sizes.", "name": "include_disk_info", @@ -120735,7 +120783,7 @@ } } ], - "specLocation": "cluster/allocation_explain/ClusterAllocationExplainRequest.ts#L25-L82" + "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 a51c867e39..b7074cf928 100644 --- a/output/schema/validation-errors.json +++ b/output/schema/validation-errors.json @@ -7,15 +7,6 @@ ], "response": [] }, - "cluster.allocation_explain": { - "request": [ - "Request: missing json spec query parameter 'current_node'", - "Request: missing json spec query parameter 'index'", - "Request: missing json spec query parameter 'primary'", - "Request: missing json spec query parameter 'shard'" - ], - "response": [] - }, "create": { "request": [ "Request: query parameter 'if_primary_term' does not exist in the json spec", diff --git a/output/typescript/types.ts b/output/typescript/types.ts index 150a1509d5..39a06da961 100644 --- a/output/typescript/types.ts +++ b/output/typescript/types.ts @@ -9401,6 +9401,10 @@ export interface ClusterAllocationExplainNodeDiskUsage { } export interface ClusterAllocationExplainRequest extends RequestBase { + current_node?: string + index?: IndexName + primary?: boolean + shard?: integer include_disk_info?: boolean include_yes_decisions?: boolean master_timeout?: Duration diff --git a/specification/cluster/allocation_explain/ClusterAllocationExplainRequest.ts b/specification/cluster/allocation_explain/ClusterAllocationExplainRequest.ts index 8377d582e0..6cd679e36b 100644 --- a/specification/cluster/allocation_explain/ClusterAllocationExplainRequest.ts +++ b/specification/cluster/allocation_explain/ClusterAllocationExplainRequest.ts @@ -45,6 +45,22 @@ export interface Request extends RequestBase { } ] query_parameters: { + /** + * Specifies the node ID or the name of the node to only explain a shard that is currently located on the specified node. + */ + current_node?: string + /** + * Specifies the name of the index that you would like an explanation for. + */ + index?: IndexName + /** + * If true, returns explanation for the primary shard for the given shard ID. + */ + primary?: boolean + /** + * Specifies the ID of the shard that you would like an explanation for. + */ + shard?: integer /** * If true, returns information about disk usage and shard sizes. * @server_default false