[Docs]: Update rest of core parameter descriptions (#623)

* [Docs]: Update rest of core parameter descriptions Signed-off-by: Archer <naarcha@amazon.com> * Apply suggestions from code review Co-authored-by: Nathan Bower <nbower@amazon.com> Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> * Update spec/schemas/_core.reindex_rethrottle.yaml Co-authored-by: Nathan Bower <nbower@amazon.com> Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> * Apply suggestions from code review Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> * Apply suggestions from code review Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> * Update spec/schemas/_core.search.yaml Co-authored-by: Nathan Bower <nbower@amazon.com> Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> --------- Signed-off-by: Archer <naarcha@amazon.com> Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> Co-authored-by: Nathan Bower <nbower@amazon.com>
opensearch-project · Oct 25, 2024 · 0605aec · 0605aec
1 parent 86e4789
commit 0605aec
Show file tree

Hide file tree

Showing 5 changed files with 34 additions and 34 deletions.
diff --git a/spec/schemas/_core.reindex.yaml b/spec/schemas/_core.reindex.yaml
@@ -34,7 +34,7 @@ components:
         size:
           description: |-
             The number of documents to index per batch.
-            Use when indexing from remote to ensure that the batches fit within the on-heap buffer, which defaults to a maximum size of 100 MB.
+            Use the `size` setting when indexing from a remote cluster. This ensures that batches fit in the on-heap buffer. The buffer defaults to a maximum size of `100MB`.
           type: number
         slice:
           $ref: '_common.yaml#/components/schemas/SlicedScroll'

diff --git a/spec/schemas/_core.reindex_rethrottle.yaml b/spec/schemas/_core.reindex_rethrottle.yaml
@@ -55,7 +55,7 @@ components:
       type: object
       properties:
         batches:
-          description: The number of scroll responses pulled back by the reindex.
+          description: The number of scroll responses shown by the reindex.
           type: number
         created:
           description: The number of documents that were successfully created.
@@ -64,10 +64,10 @@ components:
           description: The number of documents that were successfully deleted.
           type: number
         noops:
-          description: The number of documents that were ignored because the script used for the reindex returned a `noop` value for `ctx.op`.
+          description: The number of documents that were ignored because the script used for the reindex operation returned a `noop` value for `ctx.op`.
           type: number
         requests_per_second:
-          description: The number of requests per second effectively executed during the reindex.
+          description: The number of successful requests per second during the reindex operation.
           type: number
         retries:
           $ref: '_common.yaml#/components/schemas/Retries'
@@ -83,7 +83,7 @@ components:
           description: The number of documents that were successfully processed.
           type: number
         updated:
-          description: The number of documents that were successfully updated, for example, a document with same ID already existed prior to reindex updating it.
+          description: The number of documents that were successfully updated.
           type: number
         version_conflicts:
           description: The number of version conflicts that reindex hits.

diff --git a/spec/schemas/_core.scripts_painless_execute.yaml b/spec/schemas/_core.scripts_painless_execute.yaml
@@ -10,7 +10,7 @@ components:
       type: object
       properties:
         document:
-          description: Document that's temporarily indexed in-memory and accessible from the script.
+          description: A document temporarily indexed in-memory and accessible from the Painless script.
           type: object
         index:
           $ref: '_common.yaml#/components/schemas/IndexName'

diff --git a/spec/schemas/_core.search.yaml b/spec/schemas/_core.search.yaml
@@ -10,7 +10,7 @@ components:
       type: object
       properties:
         total:
-          description: Total hit count information, present only if `track_total_hits` wasn't `false` in the search request.
+          description: The total number of hits, present only if `track_total_hits` is not set to `false` in the search request.
           oneOf:
             - $ref: '#/components/schemas/TotalHits'
             - type: integer
@@ -639,18 +639,18 @@ components:
         - text
     TrackHits:
       description: |-
-        Number of hits matching the query to count accurately. If true, the exact
-        number of hits is returned at the cost of some performance. If false, the
+        The number of hits matching the query. When `true`, the exact
+        number of hits is returned at the cost of some performance. When `false`, the
         response does not include the total number of hits matching the query.
-        Defaults to 10,000 hits.
+        Default is `10,000` hits.
       oneOf:
         - type: boolean
         - type: integer
           format: int32
     SourceConfigParam:
       description: |-
         Defines how to fetch a source. Fetching can be disabled entirely, or the source can be filtered.
-        Used as a query parameter along with the `_source_includes` and `_source_excludes` parameters.
+        Use this setting with the `_source_includes` and `_source_excludes` parameters.
       oneOf:
         - type: boolean
         - $ref: '_common.yaml#/components/schemas/Fields'
@@ -664,7 +664,7 @@ components:
           type: integer
           format: int32
         from:
-          description: Inner hit starting document offset.
+          description: The inner hit that initiates document offset.
           type: integer
           format: int32
         collapse:
@@ -703,14 +703,14 @@ components:
         field:
           $ref: '_common.yaml#/components/schemas/Field'
         inner_hits:
-          description: The number of inner hits and their sort order
+          description: The number of inner hits and their sort order.
           oneOf:
             - $ref: '#/components/schemas/InnerHits'
             - type: array
               items:
                 $ref: '#/components/schemas/InnerHits'
         max_concurrent_group_searches:
-          description: The number of concurrent requests allowed to retrieve the inner_hits per group
+          description: The number of concurrent requests that are allowed to be retrieved by the `inner_hits` parameter per group.
           type: integer
       required:
         - field
@@ -761,7 +761,7 @@ components:
         boundary_scanner_locale:
           description: |-
             Controls which locale is used to search for sentence and word boundaries.
-            This parameter takes a form of a language tag, for example: `"en-US"`, `"fr-FR"`, `"ja-JP"`.
+            This parameter takes the form of a language tag, for example, `"en-US"`, `"fr-FR"`, or `"ja-JP"`.
           type: string
         force_source:
           deprecated: true
@@ -782,8 +782,8 @@ components:
         max_analyzed_offset:
           description: |-
             If set to a non-negative value, highlighting stops at this defined maximum limit.
-            The rest of the text is not processed, thus not highlighted and no error is returned
-            The `max_analyzed_offset` query setting does not override the `index.highlight.max_analyzed_offset` setting, which prevails when it's set to lower value than the query setting.
+            The rest of the text is not processed or highlighted, and no error is returned.
+            The `max_analyzed_offset` query setting does not override the `index.highlight.max_analyzed_offset` setting, which takes precedence when it is set to a lower value than the query setting.
           type: integer
           format: int32
         no_match_size:
@@ -793,10 +793,10 @@ components:
         number_of_fragments:
           description: |-
             The maximum number of fragments to return.
-            If the number of fragments is set to `0`, no fragments are returned.
-            Instead, the entire field contents are highlighted and returned.
-            This can be handy when you need to highlight short texts such as a title or address, but fragmentation is not required.
-            If `number_of_fragments` is `0`, `fragment_size` is ignored.
+            When the number of fragments is set to `0`, no fragments are returned.
+            Instead, the entirety of a field's contents are highlighted and returned.
+            This is useful when you need to highlight short texts, such as a title or address, in which fragmentation is not required.
+            If `number_of_fragments` is set to `0`, the `fragment_size` is ignored.
           type: integer
           format: int32
         options:
@@ -808,21 +808,21 @@ components:
         phrase_limit:
           description: |-
             Controls the number of matching phrases in a document that are considered.
-            Prevents the `fvh` highlighter from analyzing too many phrases and consuming too much memory.
-            When using `matched_fields`, `phrase_limit` phrases per matched field are considered. Raising the limit increases query time and consumes more memory.
-            Only supported by the `fvh` highlighter.
+            This prevents the `fvh` highlighter from analyzing too many phrases and consuming too much memory.
+            When using `matched_fields`, phrase-limited phrases per matched field are considered. Raising the limit increases the query time and consumes more memory.
+            This setting is only supported by the `fvh` highlighter.
           type: integer
           format: int32
         post_tags:
           description: |-
-            Use in conjunction with `pre_tags` to define the HTML tags to use for the highlighted text.
+            When used in conjunction with `pre_tags`, defines the HTML tags to use for the highlighted text.
             By default, highlighted text is wrapped in `<em>` and `</em>` tags.
           type: array
           items:
             type: string
         pre_tags:
           description: |-
-            Use in conjunction with `post_tags` to define the HTML tags to use for the highlighted text.
+            When used in conjunction with `post_tags`, defines the HTML tags to use for the highlighted text.
             By default, highlighted text is wrapped in `<em>` and `</em>` tags.
           type: array
           items:
@@ -899,11 +899,11 @@ components:
         rescore_query:
           $ref: '_common.query_dsl.yaml#/components/schemas/QueryContainer'
         query_weight:
-          description: Relative importance of the original query versus the rescore query.
+          description: The relative importance of the original query as compared to the rescore query.
           type: number
           format: float
         rescore_query_weight:
-          description: Relative importance of the rescore query versus the original query.
+          description: The relative importance of the rescore query as compared to the original query.
           type: number
           format: float
         score_mode:
@@ -922,7 +922,7 @@ components:
       type: object
       properties:
         text:
-          description: Global suggest text, to avoid repetition when the same text is used in several suggesters
+          description: The global suggest text, which avoids repetition when the same text is used in several suggesters.
           type: string
     PointInTimeReference:
       type: object

diff --git a/spec/schemas/_core.termvectors.yaml b/spec/schemas/_core.termvectors.yaml
@@ -11,21 +11,21 @@ components:
       properties:
         max_doc_freq:
           description: |-
-            Ignore words which occur in more than this many docs.
-            Defaults to unbounded.
+            Ignores words that appear in more than the specified number of documents.
+            Default is `unbounded`.
           type: number
         max_num_terms:
-          description: Maximum number of terms that must be returned per field.
+          description: The maximum number of terms that should be returned per field.
           type: number
         max_term_freq:
           description: |-
             Ignore words with more than this frequency in the source doc.
-            Defaults to unbounded.
+            Default is `unbounded`.
           type: number
         max_word_length:
           description: |-
             The maximum word length above which words will be ignored.
-            Defaults to unbounded.
+            Default is `unbounded`.
           type: number
         min_doc_freq:
           description: Ignore terms which do not occur in at least this many docs.