Merge branch 'main' into workspace_privacy

.github/vale/styles/Vocab/OpenSearch/Products/accept.txt

@@ -99,4 +99,5 @@ Tribuo
 VisBuilder
 Winlogbeat
 XGBoost
+Zipf
 Zstandard

.github/vale/styles/Vocab/OpenSearch/Words/reject.txt

@@ -1 +1 @@
-
+[Aa]ss

FORMATTING_GUIDE.md

@@ -399,6 +399,12 @@ Some Markdown paragraph. Here's a formula:
 And back to Markdown.
 ```
 
+Alternatively, you can use double dollar signs (`$$`) for both display and inline math directly in Markdown:
+
+```
+The probability of selecting pair $$i$$ is proportional to $$1 \over i^\alpha$$.
+```
+
 ## Tables
 
 Markdown table columns are automatically sized, and there is no need to specify a different number of dashes in the formatting. 

_api-reference/snapshots/restore-snapshot.md

@@ -22,7 +22,7 @@ If open indexes with the same name that you want to restore already exist in the
 ## Endpoints
 
 ```json
-GET _snapshot/<repository>/<snapshot>/
+POST _snapshot/<repository>/<snapshot>/_restore
 ```
 
 ## Path parameters

_benchmark/user-guide/optimizing-benchmarks/randomizing-queries.md

@@ -1,9 +1,10 @@
 ---
 layout: default
-title: Running randomized workloads
+title: Randomizing queries
 nav_order: 160
 parent: Optimizing benchmarks
 grand_parent: User guide
+has_math: true
 ---
 
 # Randomizing queries
@@ -29,15 +30,13 @@ For example, changing `"gte"` and `"lt"` in the following `nyc_taxis` operation
 }
 ```
 
-
-You can't completely randomize the values because the cache would not get any hits. To get cache hits, the cache must sometimes encounter the same values. To account for the same values while randomizing, OpenSearch Benchmark generates a number `N` of value pairs for each randomized operation at the beginning of the benchmark. OpenSearch Benchmark stores these values in a saved list where each pair is assigned an index from `1` to `N`.
+You can't completely randomize the values because the cache would not get any hits. To get cache hits, the cache must sometimes encounter the same values. To account for the same values while randomizing, OpenSearch Benchmark generates a number $$N$$ of value pairs for each randomized operation at the beginning of the benchmark. OpenSearch Benchmark stores these values in a saved list where each pair is assigned an index from $$1$$ to $$N$$.
 
 Every time OpenSearch sends a query, OpenSearch Benchmark decides whether to use a pair of values from this saved list in the query. It does this a configurable fraction of the time, called _repeat frequency_ (`rf`). If OpenSearch has encountered the value pair before, this might cause a cache hit. For example, if `rf` = 0.7, the cache hit ratio could be up to 70%. This ratio could cause a hit, depending on the benchmark's duration and cache size. 
 
-OpenSearch Benchmark selects saved value pairs using the Zipf probability distribution, where the probability of selecting pair `i` is proportional to `1/i^α`. In this formula, `i` represents the index of the saved value pair, and `α` controls how concentrated the distribution is. This distribution reflects usage patterns observed in real caches. Pairs with lower `i` values (closer to `1`) are selected more frequently, while pairs with higher `i` values (closer to `N`) are selected less often.
-
-Otherwise, the other `1-rf` fraction of the time, a new random pair of values is generated. Because OpenSearch Benchmark has not encountered these value pairs before, the pairs should miss the cache.
+OpenSearch Benchmark selects saved value pairs using the Zipf probability distribution, where the probability of selecting pair $$i$$ is proportional to $$1 \over i^\alpha$$. In this formula, $$i$$ represents the index of the saved value pair, and $$\alpha$$ controls how concentrated the distribution is. This distribution reflects usage patterns observed in real caches. Pairs with lower $$i$$ values (closer to $$1$$) are selected more frequently, while pairs with higher $$i$$ values (closer to $$N$$) are selected less often.
 
+The other $$1 -$$ `rf` fraction of the time, a new random pair of values is generated. Because OpenSearch Benchmark has not encountered these value pairs before, the pairs should miss the cache.
 
 ## Usage
 

spec-insert/lib/insert_arguments.rb

@@ -2,8 +2,8 @@
 
 # Doc Insert Arguments
 class InsertArguments
-  COLUMNS = %w[Parameter Description Required Type Default].freeze
-  DEFAULT_COLUMNS = %w[Parameter Type Description].freeze
+  COLUMNS = ['Parameter', 'Description', 'Required', 'Data type', 'Default'].freeze
+  DEFAULT_COLUMNS = ['Parameter', 'Data type', 'Description'].freeze
   attr_reader :raw
 
   # @param [Array<String>] lines the lines between <!-- doc_insert_start and -->

spec-insert/lib/renderers/parameter_table_renderer.rb

@@ -28,7 +28,7 @@ def row(param)
       'Parameter' => "`#{param.name}`#{' <br> _DEPRECATED_' if param.deprecated}",
       'Description' => description(param),
       'Required' => param.required ? 'Required' : nil,
-      'Type' => param.doc_type,
+      'Data type' => param.doc_type,
       'Default' => param.default.nil? ? nil : "`#{param.default}`"
     }
   end

spec-insert/lib/renderers/path_parameters.rb

@@ -8,7 +8,16 @@ class PathParameters < BaseMustacheRenderer
   self.template_file = "#{__dir__}/templates/path_parameters.mustache"
 
   def table
-    params = @action.arguments.select { |arg| arg.location == ArgLocation::PATH }
     ParameterTableRenderer.new(params, @args).render
   end
+
+  def optional
+    params.none?(&:required)
+  end
+
+  private
+
+  def params
+    @params ||= @action.arguments.select { |arg| arg.location == ArgLocation::PATH }
+  end
 end

spec-insert/lib/renderers/query_parameters.rb

@@ -8,8 +8,19 @@ class QueryParameters < BaseMustacheRenderer
   self.template_file = "#{__dir__}/templates/query_parameters.mustache"
 
   def table
-    params = @action.arguments.select { |arg| arg.location == ArgLocation::QUERY }
-    params += Parameter.global if @args.include_global
     ParameterTableRenderer.new(params, @args).render
   end
+
+  def optional
+    params.none?(&:required)
+  end
+
+  private
+
+  def params
+    return @params if defined?(@params)
+    @params = @action.arguments.select { |arg| arg.location == ArgLocation::QUERY }
+    @params += Parameter.global if @args.include_global
+    @params
+  end
 end

spec-insert/lib/renderers/templates/path_parameters.mustache

@@ -1,4 +1,7 @@
 {{^omit_header}}
 ## Path parameters
+
+The following table lists the available path parameters.{{#optional}} All path parameters are optional.{{/optional}}
+
 {{/omit_header}}
 {{{table}}}

spec-insert/lib/renderers/templates/query_parameters.mustache

@@ -1,7 +1,7 @@
 {{^omit_header}}
 ## Query parameters
-{{#optional}}
-All query parameters are optional.
-{{/optional}}
+
+The following table lists the available query parameters.{{#optional}} All query parameters are optional.{{/optional}}
+
 {{/omit_header}}
 {{{table}}}

spec-insert/spec/_fixtures/expected_output/param_tables.md

@@ -5,7 +5,10 @@ api: search
 component: path_parameters
 -->
 ## Path parameters
-Parameter | Type | Description
+
+The following table lists the available path parameters. All path parameters are optional.
+
+Parameter | Data type | Description
 :--- | :--- | :---
 `index` | List or String | Comma-separated list of data streams, indexes, and aliases to search. Supports wildcards (`*`). To search all data streams and indexes, omit this parameter or use `*` or `_all`.
 <!-- spec_insert_end -->
@@ -17,15 +20,18 @@ api: search
 component: query_parameters
 include_global: true
 pretty: true
-columns: Type, Parameter, Description, Required, Default
+columns: Data type, Parameter, Description, Required, Default
 -->
 ## Query parameters
-| Type    | Parameter                 | Description                                                                                                                        | Required | Default |
-|:--------|:--------------------------|:-----------------------------------------------------------------------------------------------------------------------------------|:---------|:--------|
-| Boolean | `analyze_wildcard`        | If true, wildcard and prefix queries are analyzed. This parameter can only be used when the q query string parameter is specified. | Required | `false` |
-| String  | `analyzer`                | Analyzer to use for the query string. This parameter can only be used when the q query string parameter is specified.              |          |         |
-| Boolean | `pretty`                  | Whether to pretty format the returned JSON response.                                                                               |          |         |
-| Boolean | `human` <br> _DEPRECATED_ | _(Deprecated since 3.0: Use the `format` parameter instead.)_ Whether to return human readable values for statistics.              |          | `true`  |
+
+The following table lists the available query parameters.
+
+| Data type | Parameter                 | Description                                                                                                                        | Required | Default |
+|:----------|:--------------------------|:-----------------------------------------------------------------------------------------------------------------------------------|:---------|:--------|
+| Boolean   | `analyze_wildcard`        | If true, wildcard and prefix queries are analyzed. This parameter can only be used when the q query string parameter is specified. | Required | `false` |
+| String    | `analyzer`                | Analyzer to use for the query string. This parameter can only be used when the q query string parameter is specified.              |          |         |
+| Boolean   | `pretty`                  | Whether to pretty format the returned JSON response.                                                                               |          |         |
+| Boolean   | `human` <br> _DEPRECATED_ | _(Deprecated since 3.0: Use the `format` parameter instead.)_ Whether to return human readable values for statistics.              |          | `true`  |
 <!-- spec_insert_end -->
 
 Query Parameters Example with only Parameter and Description Columns
@@ -41,3 +47,20 @@ Parameter | Description
 `analyze_wildcard` | **(Required)** If true, wildcard and prefix queries are analyzed. This parameter can only be used when the q query string parameter is specified. _(Default: `false`)_
 `analyzer` | Analyzer to use for the query string. This parameter can only be used when the q query string parameter is specified.
 <!-- spec_insert_end -->
+
+Optional Params Text
+
+<!-- spec_insert_start
+api: cat.health
+component: query_parameters
+include_global: true
+-->
+## Query parameters
+
+The following table lists the available query parameters. All query parameters are optional.
+
+Parameter | Data type | Description
+:--- | :--- | :---
+`pretty` | Boolean | Whether to pretty format the returned JSON response.
+`human` <br> _DEPRECATED_ | Boolean | _(Deprecated since 3.0: Use the `format` parameter instead.)_ Whether to return human readable values for statistics. _(Default: `true`)_
+<!-- spec_insert_end -->

spec-insert/spec/_fixtures/input/param_tables.md

@@ -18,7 +18,7 @@ api: search
 component: query_parameters
 include_global: true
 pretty: true
-columns: Type, Parameter, Description, Required, Default
+columns: Data type, Parameter, Description, Required, Default
 -->
   THIS TEXT SHOULD BE REPLACED
 <!-- spec_insert_end -->
@@ -37,3 +37,12 @@ SHOULD
 BE
 REPLACED
 <!-- spec_insert_end -->
+
+Optional Params Text
+
+<!-- spec_insert_start
+api: cat.health
+component: query_parameters
+include_global: true
+-->
+<!-- spec_insert_end -->

spec-insert/spec/_fixtures/opensearch_spec.yaml

@@ -4,6 +4,13 @@ info:
   version: 1.0.0
   x-api-version: 2.16.0
 paths:
+  /_cat/health:
+    get:
+      operationId: cat_health.0
+      x-operation-group: cat.health
+      parameters:
+        - $ref: '#/components/parameters/_global___query.pretty'
+        - $ref: '#/components/parameters/_global___query.human'
   /_search:
     get:
       operationId: search.0