[8.19] Adding specification for the new data stream settings APIs (#4416)

specification/_doc_ids/table.csv

@@ -315,13 +315,15 @@ indices-exists,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/
 indices-flush,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/indices-flush.html,,
 indices-forcemerge,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/indices-forcemerge.html,,
 indices-get-alias,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/indices-get-alias.html,,
+indices-get-data-stream-settings,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/indices-get-data-stream-settings.html,,
 indices-get-field-mapping,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/indices-get-field-mapping.html,,
 indices-get-index,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/indices-get-index.html,,
 indices-get-mapping,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/indices-get-mapping.html,,
 indices-get-settings,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/indices-get-settings.html,,
 indices-get-template,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/indices-get-template.html,,
 indices-get-template-v1,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/indices-get-template-v1.html,,
 indices-open-close,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/indices-open-close.html,,
+indices-put-data-stream-settings,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/indices-put-data-stream-settings.html,,
 indices-put-mapping,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/indices-put-mapping.html,,
 indices-recovery,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/indices-recovery.html,,
 indices-refresh,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/indices-refresh.html,,

specification/_json_spec/indices.put_data_stream_settings.json

@@ -31,7 +31,8 @@
       },
       "timeout": {
         "type": "time",
-        "description": "Period to wait for a response"
+        "description": "Period to wait for a response",
+        "default": "30s"
       },
       "master_timeout": {
         "type": "time",

specification/indices/_types/DataStream.ts

@@ -28,6 +28,7 @@ import {
 } from '@_types/common'
 import { integer } from '@_types/Numeric'
 import { DataStreamLifecycleWithRollover } from '@indices/_types/DataStreamLifecycle'
+import { IndexSettings } from '@indices/_types/IndexSettings'
 
 enum ManagedBy {
   ilm = 'Index Lifecycle Management',
@@ -104,6 +105,11 @@ export class DataStream {
    * If `true`, the next write to this data stream will trigger a rollover first and the document will be indexed in the new backing index. If the rollover fails the indexing request will fail too.
    */
   rollover_on_write: boolean
+  /**
+   * The settings specific to this data stream that will take precedence over the settings in the matching index
+   * template.
+   */
+  settings: IndexSettings
   /**
    * Health status of the data stream.
    * This health status is based on the state of the primary and replica shards of the stream’s backing indices.

specification/indices/get_data_stream_settings/IndicesGetDataStreamSettingsRequest.ts

@@ -0,0 +1,57 @@
+/*
+ * 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.
+ */
+
+import { RequestBase } from '@_types/Base'
+import { Indices } from '@_types/common'
+import { Duration } from '@_types/Time'
+
+/**
+ * Get data stream settings.
+ *
+ * Get setting information for one or more data streams.
+ * @rest_spec_name indices.get_data_stream_settings
+ * @availability stack stability=stable visibility=public
+ * @availability serverless stability=stable visibility=public
+ * @index_privileges view_index_metadata
+ * @doc_id indices-get-data-stream-settings
+ * @doc_tag data stream
+ */
+export interface Request extends RequestBase {
+  urls: [
+    {
+      path: '/_data_stream/{name}/_settings'
+      methods: ['GET']
+    }
+  ]
+  path_parts: {
+    /**
+     * A comma-separated list of data streams or data stream patterns. Supports wildcards (`*`).
+     */
+    name: Indices
+  }
+  query_parameters: {
+    /**
+     * The period to wait for a connection to the master node. If no response is
+     * received before the timeout expires, the request fails and returns an
+     * error.
+     * @server_default 30s
+     */
+    master_timeout?: Duration
+  }
+}

specification/indices/get_data_stream_settings/IndicesGetDataStreamSettingsResponse.ts

@@ -0,0 +1,39 @@
+/*
+ * 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.
+ */
+
+import { IndexSettings } from '@indices/_types/IndexSettings'
+
+export class Response {
+  /** @codegen_name data_stream_settings */
+  body: {
+    data_streams: Array<DataStreamSettings>
+  }
+}
+
+export class DataStreamSettings {
+  /** The name of the data stream. */
+  name: string
+  /** The settings specific to this data stream */
+  settings: IndexSettings
+  /**
+   * The settings specific to this data stream merged with the settings from its template. These `effective_settings`
+   * are the settings that will be used when a new index is created for this data stream.
+   */
+  effective_settings: IndexSettings
+}

specification/indices/get_data_stream_settings/examples/200_response/IndicesGetDataStreamSettingsResponseExample1.yaml

@@ -0,0 +1,32 @@
+summary: Get data stream settings on a data stream
+description: >
+  This is a response to `GET /_data_stream/my-data-stream/_settings` where my-data-stream that has two settings set. The
+  `effective_settings` field shows additional settings that are pulled from its template.
+# type: response
+# response_code: 200
+value: |-
+  {
+    "data_streams": [
+      {
+        "name": "my-data-stream",
+        "settings": {
+          "index": {
+            "lifecycle": {
+              "name": "new-test-policy"
+            },
+            "number_of_shards": "11"
+          }
+        },
+        "effective_settings": {
+          "index": {
+            "lifecycle": {
+              "name": "new-test-policy"
+            },
+            "mode": "standard",
+            "number_of_shards": "11",
+            "number_of_replicas": "0"
+          }
+        }
+      }
+    ]
+  }

specification/indices/put_data_stream_settings/IndicesPutDataStreamSettingsRequest.ts

@@ -0,0 +1,77 @@
+/*
+ * 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.
+ */
+
+import { RequestBase } from '@_types/Base'
+import { Indices } from '@_types/common'
+import { Duration } from '@_types/Time'
+import { IndexSettings } from '@indices/_types/IndexSettings'
+
+/**
+ * Update data stream settings.
+ *
+ * This API can be used to override settings on specific data streams. These overrides will take precedence over what
+ * is specified in the template that the data stream matches. To prevent your data stream from getting into an invalid state,
+ * only certain settings are allowed. If possible, the setting change is applied to all
+ * backing indices. Otherwise, it will be applied when the data stream is next rolled over.
+ * @rest_spec_name indices.put_data_stream_settings
+ * @availability stack stability=stable visibility=public
+ * @availability serverless stability=stable visibility=public
+ * @index_privileges manage
+ * @doc_id indices-put-data-stream-settings
+ * @doc_tag data stream
+ */
+export interface Request extends RequestBase {
+  urls: [
+    {
+      path: '/_data_stream/{name}/_settings'
+      methods: ['PUT']
+    }
+  ]
+  path_parts: {
+    /**
+     * A comma-separated list of data streams or data stream patterns.
+     */
+    name: Indices
+  }
+  query_parameters: {
+    /**
+     * If `true`, the request does not actually change the settings on any data streams or indices. Instead, it
+     * simulates changing the settings and reports back to the user what would have happened had these settings
+     * actually been applied.
+     * @server_default false
+     */
+    dry_run?: boolean
+    /**
+     * The period to wait for a connection to the master node. If no response is
+     * received before the timeout expires, the request fails and returns an
+     * error.
+     * @server_default 30s
+     */
+    master_timeout?: Duration
+    /**
+     *  The period to wait for a response. If no response is received before the
+     *  timeout expires, the request fails and returns an error.
+     * @server_default 30s
+     */
+    timeout?: Duration
+  }
+  /** Settings to be applied to the data stream.
+   * @codegen_name settings */
+  body: IndexSettings
+}