From c2023741aa118200d5c2e51d61940f2b55923d83 Mon Sep 17 00:00:00 2001 From: Jeremy Dahlgren Date: Tue, 17 Jun 2025 09:16:08 -0400 Subject: [PATCH 1/3] Add GET snapshots state query parameter. Adds documentation for the SnapshotState enum and state query parameter added in elasticsearch PR #128635. --- output/openapi/elasticsearch-openapi.json | 20 ++++++++ output/schema/schema.json | 51 ++++++++++++++++++- output/schema/validation-errors.json | 6 --- output/typescript/types.ts | 3 ++ .../snapshot/_types/SnapshotState.ts | 31 +++++++++++ .../snapshot/get/SnapshotGetRequest.ts | 9 ++++ 6 files changed, 113 insertions(+), 7 deletions(-) create mode 100644 specification/snapshot/_types/SnapshotState.ts diff --git a/output/openapi/elasticsearch-openapi.json b/output/openapi/elasticsearch-openapi.json index a9ced01a15..8a529aa5cd 100644 --- a/output/openapi/elasticsearch-openapi.json +++ b/output/openapi/elasticsearch-openapi.json @@ -57286,6 +57286,16 @@ }, "style": "form" }, + { + "in": "query", + "name": "state", + "description": "Only return snapshots with a state found in the given comma-separated list of snapshot states.\nThe default is all snapshot states.", + "deprecated": false, + "schema": { + "$ref": "#/components/schemas/snapshot._types.SnapshotState" + }, + "style": "form" + }, { "in": "query", "name": "verbose", @@ -118985,6 +118995,16 @@ "failed_shard_count" ] }, + "snapshot._types.SnapshotState": { + "type": "string", + "enum": [ + "IN_PROGRESS", + "SUCCESS", + "FAILED", + "PARTIAL", + "INCOMPATIBLE" + ] + }, "snapshot.get.SnapshotResponseItem": { "type": "object", "properties": { diff --git a/output/schema/schema.json b/output/schema/schema.json index 930c3bfe80..abee582fb4 100644 --- a/output/schema/schema.json +++ b/output/schema/schema.json @@ -242184,6 +242184,36 @@ }, "specLocation": "snapshot/_types/SnapshotInfo.ts#L73-L93" }, + { + "kind": "enum", + "members": [ + { + "description": "The snapshot process has started.", + "name": "IN_PROGRESS" + }, + { + "description": "The snapshot process completed successfully.", + "name": "SUCCESS" + }, + { + "description": "The snapshot failed.", + "name": "FAILED" + }, + { + "description": "The snapshot was partially successful.", + "name": "PARTIAL" + }, + { + "description": "The snapshot is incompatible with the current version of the cluster.", + "name": "INCOMPATIBLE" + } + ], + "name": { + "name": "SnapshotState", + "namespace": "snapshot._types" + }, + "specLocation": "snapshot/_types/SnapshotState.ts#L20-L31" + }, { "kind": "interface", "name": { @@ -243801,6 +243831,25 @@ } } }, + { + "availability": { + "serverless": {}, + "stack": { + "since": "9.1.0" + } + }, + "description": "Only return snapshots with a state found in the given comma-separated list of snapshot states.\nThe default is all snapshot states.", + "name": "state", + "required": false, + "serverDefault": "All snapshot states", + "type": { + "kind": "instance_of", + "type": { + "name": "SnapshotState", + "namespace": "snapshot._types" + } + } + }, { "description": "If `true`, returns additional information about each snapshot such as the version of Elasticsearch which took the snapshot, the start and end times of the snapshot, and the number of shards snapshotted.\n\nNOTE: The parameters `size`, `order`, `after`, `from_sort_value`, `offset`, `slm_policy_filter`, and `sort` are not supported when you set `verbose=false` and the sort order for requests with `verbose=false` is undefined.", "name": "verbose", @@ -243815,7 +243864,7 @@ } } ], - "specLocation": "snapshot/get/SnapshotGetRequest.ts#L27-L158" + "specLocation": "snapshot/get/SnapshotGetRequest.ts#L28-L167" }, { "kind": "response", diff --git a/output/schema/validation-errors.json b/output/schema/validation-errors.json index c08c05427d..31a0442e64 100644 --- a/output/schema/validation-errors.json +++ b/output/schema/validation-errors.json @@ -119,12 +119,6 @@ ], "response": [] }, - "snapshot.get": { - "request": [ - "Request: missing json spec query parameter 'state'" - ], - "response": [] - }, "snapshot.repository_analyze": { "request": [ "Request: query parameter 'register_operation_count' does not exist in the json spec" diff --git a/output/typescript/types.ts b/output/typescript/types.ts index 23302d1b34..66e873ad55 100644 --- a/output/typescript/types.ts +++ b/output/typescript/types.ts @@ -21004,6 +21004,8 @@ export interface SnapshotSnapshotShardsStatus { export type SnapshotSnapshotSort = 'start_time' | 'duration' | 'name' | 'index_count' | 'repository' | 'shard_count' | 'failed_shard_count' +export type SnapshotSnapshotState = 'IN_PROGRESS' | 'SUCCESS' | 'FAILED' | 'PARTIAL' | 'INCOMPATIBLE' + export interface SnapshotSnapshotStats { incremental: SnapshotFileCountSnapshotStats start_time_in_millis: EpochTime @@ -21124,6 +21126,7 @@ export interface SnapshotGetRequest extends RequestBase { size?: integer slm_policy_filter?: Name sort?: SnapshotSnapshotSort + state?: SnapshotSnapshotState verbose?: boolean } diff --git a/specification/snapshot/_types/SnapshotState.ts b/specification/snapshot/_types/SnapshotState.ts new file mode 100644 index 0000000000..71373df66e --- /dev/null +++ b/specification/snapshot/_types/SnapshotState.ts @@ -0,0 +1,31 @@ +/* + * Licensed to Elasticsearch B.V. under one or more contributor + * license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright + * ownership. Elasticsearch B.V. licenses this file to you under + * the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +export enum SnapshotState { + /** The snapshot process has started. */ + IN_PROGRESS, + /** The snapshot process completed successfully. */ + SUCCESS, + /** The snapshot failed. */ + FAILED, + /** The snapshot was partially successful. */ + PARTIAL, + /** The snapshot is incompatible with the current version of the cluster. */ + INCOMPATIBLE +} diff --git a/specification/snapshot/get/SnapshotGetRequest.ts b/specification/snapshot/get/SnapshotGetRequest.ts index 69875f92b6..24e0506f1c 100644 --- a/specification/snapshot/get/SnapshotGetRequest.ts +++ b/specification/snapshot/get/SnapshotGetRequest.ts @@ -23,6 +23,7 @@ import { integer } from '@_types/Numeric' import { SortOrder } from '@_types/sort' import { Duration } from '@_types/Time' import { SnapshotSort } from '@snapshot/_types/SnapshotInfo' +import { SnapshotState } from '@snapshot/_types/SnapshotState' /** * Get snapshot information. @@ -147,6 +148,14 @@ export interface Request extends RequestBase { * @availability serverless */ sort?: SnapshotSort + /** + * Only return snapshots with a state found in the given comma-separated list of snapshot states. + * The default is all snapshot states. + * @server_default All snapshot states + * @availability stack since=9.1.0 + * @availability serverless + */ + state?: SnapshotState /** * If `true`, returns additional information about each snapshot such as the version of Elasticsearch which took the snapshot, the start and end times of the snapshot, and the number of shards snapshotted. * From 11640f2d4ea5cf7834a9414cabe251f5c1b64dbb Mon Sep 17 00:00:00 2001 From: Jeremy Dahlgren Date: Wed, 18 Jun 2025 10:00:56 -0400 Subject: [PATCH 2/3] Allow SnapshotState or SnapshotState[] --- specification/snapshot/get/SnapshotGetRequest.ts | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/specification/snapshot/get/SnapshotGetRequest.ts b/specification/snapshot/get/SnapshotGetRequest.ts index 24e0506f1c..e509a5e666 100644 --- a/specification/snapshot/get/SnapshotGetRequest.ts +++ b/specification/snapshot/get/SnapshotGetRequest.ts @@ -151,11 +151,10 @@ export interface Request extends RequestBase { /** * Only return snapshots with a state found in the given comma-separated list of snapshot states. * The default is all snapshot states. - * @server_default All snapshot states * @availability stack since=9.1.0 * @availability serverless */ - state?: SnapshotState + state?: SnapshotState | SnapshotState[] /** * If `true`, returns additional information about each snapshot such as the version of Elasticsearch which took the snapshot, the start and end times of the snapshot, and the number of shards snapshotted. * From 7a6809b3ba0518de0b9de874098fcb8df6258120 Mon Sep 17 00:00:00 2001 From: Jeremy Dahlgren Date: Wed, 18 Jun 2025 10:02:30 -0400 Subject: [PATCH 3/3] Regenerate output for updated SnapshotState definition --- output/openapi/elasticsearch-openapi.json | 12 +++++++++- output/schema/schema.json | 28 +++++++++++++++++------ output/typescript/types.ts | 2 +- 3 files changed, 33 insertions(+), 9 deletions(-) diff --git a/output/openapi/elasticsearch-openapi.json b/output/openapi/elasticsearch-openapi.json index 68e141f71c..9b11b62f4e 100644 --- a/output/openapi/elasticsearch-openapi.json +++ b/output/openapi/elasticsearch-openapi.json @@ -39612,7 +39612,17 @@ "description": "Only return snapshots with a state found in the given comma-separated list of snapshot states.\nThe default is all snapshot states.", "deprecated": false, "schema": { - "$ref": "#/components/schemas/snapshot._types.SnapshotState" + "oneOf": [ + { + "$ref": "#/components/schemas/snapshot._types.SnapshotState" + }, + { + "type": "array", + "items": { + "$ref": "#/components/schemas/snapshot._types.SnapshotState" + } + } + ] }, "style": "form" }, diff --git a/output/schema/schema.json b/output/schema/schema.json index 52637d42de..32c57b0d7a 100644 --- a/output/schema/schema.json +++ b/output/schema/schema.json @@ -245326,13 +245326,27 @@ "description": "Only return snapshots with a state found in the given comma-separated list of snapshot states.\nThe default is all snapshot states.", "name": "state", "required": false, - "serverDefault": "All snapshot states", "type": { - "kind": "instance_of", - "type": { - "name": "SnapshotState", - "namespace": "snapshot._types" - } + "kind": "union_of", + "items": [ + { + "kind": "instance_of", + "type": { + "name": "SnapshotState", + "namespace": "snapshot._types" + } + }, + { + "kind": "array_of", + "value": { + "kind": "instance_of", + "type": { + "name": "SnapshotState", + "namespace": "snapshot._types" + } + } + } + ] } }, { @@ -245349,7 +245363,7 @@ } } ], - "specLocation": "snapshot/get/SnapshotGetRequest.ts#L28-L167" + "specLocation": "snapshot/get/SnapshotGetRequest.ts#L28-L166" }, { "kind": "response", diff --git a/output/typescript/types.ts b/output/typescript/types.ts index c8305b4783..5b48b57bb7 100644 --- a/output/typescript/types.ts +++ b/output/typescript/types.ts @@ -21131,7 +21131,7 @@ export interface SnapshotGetRequest extends RequestBase { size?: integer slm_policy_filter?: Name sort?: SnapshotSnapshotSort - state?: SnapshotSnapshotState + state?: SnapshotSnapshotState | SnapshotSnapshotState[] verbose?: boolean }