Adding specification for the get random sample and get random sample stats APIs

package.json

@@ -7,4 +7,4 @@
     "@stoplight/spectral-cli": "^6.14.2"
   },
   "version": "overlay"
-}
+}

specification/_doc_ids/table.csv

@@ -613,6 +613,7 @@ edit-query-rule-from-ui,https://www.elastic.co/docs/solutions/search/query-rules
 delete-query-rule-from-ui,https://www.elastic.co/docs/solutions/search/query-rules-ui#delete-a-rule,,Delete a rule from the Query Rules UI
 list-query-rules-in-ui,https://www.elastic.co/docs/solutions/search/query-rules-ui#accessing-the-query-rules-ui,,See rules and rulesets in Query Rules UI
 delete-query-ruleset-from-ui,https://www.elastic.co/docs/solutions/search/query-rules-ui#delete-a-ruleset,,Delete a ruleset from the Query Rules UI
+random_sample,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/ingest-random-sampling.html,,
 realtime,https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-get,https://www.elastic.co/guide/en/elasticsearch/reference/8.18/docs-get.html,
 redact-processor,https://www.elastic.co/docs/reference/enrich-processor/redact-processor,,
 regexp-syntax,https://www.elastic.co/docs/reference/query-languages/query-dsl/regexp-syntax,,

specification/_json_spec/indices.get_sample.json

@@ -5,7 +5,8 @@
       "description": "Get random sample of ingested data"
     },
     "stability": "experimental",
-    "visibility": "public",
+    "visibility": "feature_flag",
+    "feature_flag": "random_sampling",
     "headers": {
       "accept": ["application/json"]
     },

specification/indices/get_sample/GetRandomSampleRequest.ts

@@ -0,0 +1,44 @@
+/*
+ * 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 { IndexName } from '@_types/common'
+
+/**
+ * Request for a random sample of raw documents ingested into the given index or data stream.
+ *
+ * @rest_spec_name indices.get_sample
+ * @availability serverless visibility=feature_flag feature_flag=random_sampling since=9.3.0 stability=experimental
+ * @doc_id random_sample
+ * @doc_tag random_sample
+ */
+export interface Request extends RequestBase {
+  urls: [
+    {
+      path: '/{index}/_sample'
+      methods: ['GET']
+    }
+  ]
+  path_parts: {
+    /**
+     * Single index or data stream name. Wildcards are not supported.
+     */
+    index: IndexName
+  }
+}

specification/indices/get_sample/GetRandomSampleResponse.ts

@@ -0,0 +1,28 @@
+/*
+ * 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 { RawDocument } from './_types/RawDocument'
+
+/**
+ * Response type for the get_random_samples API.
+ * It reuses the standard SearchResponse structure.
+ */
+export class Response {
+  body: { sample: RawDocument[] }
+}

specification/indices/get_sample/_types/RawDocument.ts

@@ -0,0 +1,33 @@
+/*
+ * 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 { PropertyName } from '@_types/common'
+import { Property } from '@_types/mapping/Property'
+import { Dictionary } from '@spec_utils/Dictionary'
+
+export class RawDocument {
+  /**
+   * Name of the index for this raw document.
+   */
+  index: string
+  /**
+   * The original raw source.
+   */
+  source: Dictionary<PropertyName, Property>
+}

specification/indices/get_sample/examples/200_response/GetRandomSampleResponse1.yaml

@@ -0,0 +1,35 @@
+# summary: ''
+description: A successful response for retrieving the random sample for an index or data stream.
+# type: response
+# response_code: 200
+value: |-
+  {
+    "sample": [
+      {
+        "index": "logs",
+        "source": {
+          "@timestamp": "2099-11-15T13:12:00",
+          "message": "Node 0 message",
+          "user": {
+            "id": "kimchy"
+          },
+          "network": {
+            "name": "Guest"
+          }
+        }
+      },
+      {
+        "index": "logs",
+        "source": {
+          "@timestamp": "2079-11-15T13:12:00",
+          "message": "Node 1 message",
+          "user": {
+            "id": "kimchy"
+          },
+          "network": {
+            "name": "Guest"
+          }
+        }
+      }
+    ]
+  }

specification/indices/get_sample/examples/request/GetRandomSampleRequest1.yaml

@@ -0,0 +1 @@
+method_request: GET /my-index-000001/_sample

specification/indices/get_sample_stats/GetRandomSampleStatsRequest.ts

@@ -0,0 +1,44 @@
+/*
+ * 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 { IndexName } from '@_types/common'
+
+/**
+ * Request stats for a random sample of raw documents ingested into the given index or data stream.
+ *
+ * @rest_spec_name indices.get_sample_stats
+ * @availability serverless visibility=feature_flag feature_flag=random_sampling since=9.3.0 stability=experimental
+ * @doc_id random_sample
+ * @doc_tag random_sample
+ */
+export interface Request extends RequestBase {
+  urls: [
+    {
+      path: '/{index}/_sample/stats'
+      methods: ['GET']
+    }
+  ]
+  path_parts: {
+    /**
+     * Single index or data stream name. Wildcards are not supported.
+     */
+    index: IndexName
+  }
+}

specification/indices/get_sample_stats/GetRandomSampleStatsResponse.ts

@@ -0,0 +1,44 @@
+/*
+ * 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 { long } from '@_types/Numeric'
+import { Duration, DurationValue, UnitMillis } from '@_types/Time'
+
+/**
+ * Response type for the get_random_samples API.
+ * It reuses the standard SearchResponse structure.
+ */
+export class Response {
+  body: {
+    potential_samples: long
+    samples_rejected_for_max_samples_exceeded: long
+    samples_rejected_for_condition: long
+    samples_rejected_for_rate: long
+    samples_rejected_for_exception: long
+    samples_rejected_for_size: long
+    samples_accepted: long
+    time_sampling?: Duration
+    time_sampling_millis: DurationValue<UnitMillis>
+    time_evaluating_condition?: Duration
+    time_evaluating_condition_millis: DurationValue<UnitMillis>
+    time_compiling_condition?: Duration
+    time_compiling_condition_millis: DurationValue<UnitMillis>
+    last_exception?: string
+  }
+}

specification/indices/get_sample_stats/examples/200_response/GetRandomSampleStatsResponse1.yaml

@@ -0,0 +1,20 @@
+# summary: ''
+description: A successful response for retrieving the random sample stats for an index or data stream.
+# type: response
+# response_code: 200
+value: |-
+  {
+    "potential_samples": 2,
+    "samples_rejected_for_max_samples_exceeded": 0,
+    "samples_rejected_for_condition": 0,
+    "samples_rejected_for_rate": 0,
+    "samples_rejected_for_exception": 0,
+    "samples_rejected_for_size": 0,
+    "samples_accepted": 2,
+    "time_sampling": "415.7micros",
+    "time_sampling_millis": 0,
+    "time_evaluating_condition": "185.9micros",
+    "time_evaluating_condition_millis": 0,
+    "time_compiling_condition": "98.4micros",
+    "time_compiling_condition_millis": 0
+  }

specification/indices/get_sample_stats/examples/request/GetRandomSampleStatsRequest1.yaml

@@ -0,0 +1 @@
+method_request: GET /my-index-000001/_sample/stats