From 0605aec82fca2673ded1a138da113cfc4abdfc45 Mon Sep 17 00:00:00 2001 From: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> Date: Fri, 25 Oct 2024 11:00:02 -0500 Subject: [PATCH] [Docs]: Update rest of core parameter descriptions (#623) * [Docs]: Update rest of core parameter descriptions Signed-off-by: Archer * Apply suggestions from code review Co-authored-by: Nathan Bower Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> * Update spec/schemas/_core.reindex_rethrottle.yaml Co-authored-by: Nathan Bower 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 Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> --------- Signed-off-by: Archer Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> Co-authored-by: Nathan Bower --- spec/schemas/_core.reindex.yaml | 2 +- spec/schemas/_core.reindex_rethrottle.yaml | 8 ++-- .../_core.scripts_painless_execute.yaml | 2 +- spec/schemas/_core.search.yaml | 46 +++++++++---------- spec/schemas/_core.termvectors.yaml | 10 ++-- 5 files changed, 34 insertions(+), 34 deletions(-) diff --git a/spec/schemas/_core.reindex.yaml b/spec/schemas/_core.reindex.yaml index fc4a1ae2e..eaa2c1579 100644 --- 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 index 1fadb4aa0..6275fef00 100644 --- 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 index 5997842ff..8aca44805 100644 --- 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 index a9d1f9077..ab84bebc0 100644 --- 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,10 +639,10 @@ 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 @@ -650,7 +650,7 @@ components: 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 `` and `` 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 `` and `` 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 index 7cca65878..d7a309b9a 100644 --- 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.