From 9c177fd09e5237e6ba2d3585d2f2b8e248edc0c1 Mon Sep 17 00:00:00 2001 From: Archer Date: Thu, 17 Oct 2024 14:28:11 -0500 Subject: [PATCH] [Docs] Descriptions for rank eval and mterm parameters Signed-off-by: Archer --- spec/schemas/_core.mtermvectors.yaml | 10 +++++----- spec/schemas/_core.rank_eval.yaml | 20 ++++++++++---------- 2 files changed, 15 insertions(+), 15 deletions(-) diff --git a/spec/schemas/_core.mtermvectors.yaml b/spec/schemas/_core.mtermvectors.yaml index 02b168921..ced45db7e 100644 --- a/spec/schemas/_core.mtermvectors.yaml +++ b/spec/schemas/_core.mtermvectors.yaml @@ -14,23 +14,23 @@ components: _index: $ref: '_common.yaml#/components/schemas/IndexName' doc: - description: An artificial document (a document not present in the index) for which you want to retrieve term vectors. + description: An artificial document for which you want to retrieve term vectors. type: object fields: $ref: '_common.yaml#/components/schemas/Fields' field_statistics: - description: When `true`, the response includes the document count, the sum of document frequencies, and the sum of term frequencies. + description: When `true`, the response includes the document count, the sum of the document frequencies, and the sum of the term frequencies. type: boolean filter: $ref: '_core.termvectors.yaml#/components/schemas/Filter' offsets: - description: When `true`, the response includes term offsets. + description: When `true`, the response includes the term offsets. type: boolean payloads: - description: When `true`, the response includes term payloads. + description: When `true`, the response includes the term payloads. type: boolean positions: - description: When `true`, the response includes term positions. + description: When `true`, the response includes the term positions. type: boolean routing: $ref: '_common.yaml#/components/schemas/Routing' diff --git a/spec/schemas/_core.rank_eval.yaml b/spec/schemas/_core.rank_eval.yaml index 4527f0c05..d5e1d6eb0 100644 --- a/spec/schemas/_core.rank_eval.yaml +++ b/spec/schemas/_core.rank_eval.yaml @@ -14,7 +14,7 @@ components: request: $ref: '#/components/schemas/RankEvalQuery' ratings: - description: List of document ratings + description: A list of document ratings. type: array items: $ref: '#/components/schemas/DocumentRating' @@ -45,7 +45,7 @@ components: _index: $ref: '_common.yaml#/components/schemas/IndexName' rating: - description: The document's relevance with regard to this search request. + description: The document's relevance with regard to the specified search request. type: number required: - _id @@ -70,7 +70,7 @@ components: - type: object properties: ignore_unlabeled: - description: Controls how unlabeled documents in the search results are counted. If set to true, unlabeled documents are ignored and neither count as relevant or irrelevant. Set to false (the default), they are treated as irrelevant. + description: Controls how unlabeled documents in the search results are counted. When `true`, unlabeled documents are ignored and do not count as relevant or irrelevant. When `false`, unlabeled documents are treated as irrelevant. type: boolean RankEvalMetricRatingThreshold: allOf: @@ -78,13 +78,13 @@ components: - type: object properties: relevant_rating_threshold: - description: Sets the rating threshold above which documents are considered to be "relevant". + description: Sets the rating threshold above which documents are considered to be relevant. type: number RankEvalMetricBase: type: object properties: k: - description: Sets the maximum number of documents retrieved per query. This value will act in place of the usual size parameter in the query. + description: Sets the maximum number of documents retrieved per query. This value replaces the usual `size` parameter in the query. type: number RankEvalMetricRecall: allOf: @@ -100,7 +100,7 @@ components: - type: object properties: normalize: - description: If set to true, this metric will calculate the Normalized DCG (https://en.wikipedia.org/wiki/Discounted_cumulative_gain#Normalized_DCG). + description: When `true`, this metric calculates the Normalized DCG (https://en.wikipedia.org/wiki/Discounted_cumulative_gain#Normalized_DCG). type: boolean RankEvalMetricExpectedReciprocalRank: allOf: @@ -116,20 +116,20 @@ components: type: object properties: metric_score: - description: The metric_score in the details section shows the contribution of this query to the global quality metric score + description: The `metric_score`, found in the `metric_details` section, shows the contribution of this query to the global quality metric score. type: number unrated_docs: - description: The unrated_docs section contains an _index and _id entry for each document in the search result for this query that didn't have a ratings value. This can be used to ask the user to supply ratings for these documents + description: The `unrated_docs` section contains an `_index` and `_id` entry for each document that didn't have a ratings value. This can be used to ask the user to supply ratings for these documents. type: array items: $ref: '#/components/schemas/UnratedDocument' hits: - description: The hits section shows a grouping of the search results with their supplied ratings + description: The `hits` section shows a grouping of the search results with their supplied ratings type: array items: $ref: '#/components/schemas/RankEvalHitItem' metric_details: - description: The metric_details give additional information about the calculated quality metric (e.g. how many of the retrieved documents were relevant). The content varies for each metric but allows for better interpretation of the results + description: The `metric_details` section gives additional information about the calculated quality metric, in other words, how many of the retrieved documents were relevant. The content varies for each metric but allows for better interpretation of the results. type: object additionalProperties: type: object