[Docs] Add rank_eval size parameter k
The rank_eval documentation was missing an explanation of the parameter
`k` that controls the number of top hits that are used in the ranking evaluation.
Closes
[[search-rank-eval]]
== Ranking Evaluation API
+experimental[The ranking evaluation API is experimental and may be changed or removed completely in a future release,
+as well as change in non-backwards compatible ways on minor versions updates. Elastic will take a best effort
+approach to fix any issues, but experimental features are not subject to the support SLA of official GA features.]
+
The ranking evaluation API allows to evaluate the quality of ranked search
results over a set of typical search queries. Given this set of queries and a
list or manually rated documents, the `_rank_eval` endpoint calculates and
returns typical information retrieval metrics like _mean reciprocal rank_,
_precision_ or _discounted cumulative gain_.
-experimental[The ranking evaluation API is new and may change in non-backwards compatible ways in the future, even on minor versions updates.]
-
[float]
=== Overview
@@ -41,7 +43,7 @@ GET /my_index/_rank_eval
{
"requests": [ ... ], <1>
"metric": { <2>
- "reciprocal_rank": { ... } <3>
+ "mean_reciprocal_rank": { ... } <3>
}
}
------------------------------
@@ -162,6 +164,7 @@ GET /twitter/_rank_eval
}],
"metric": {
"precision": {
+ "k" : 20,
"relevant_rating_threshold": 1,
"ignore_unlabeled": false
}
@@ -176,7 +179,9 @@ The `precision` metric takes the following optional parameters
[cols="<,<",options="header",]
|=======================================================================
|Parameter |Description
-|`relevant_rating_threshold` |Sets the rating threshold above which documents are considered to be
+|`k` |sets the maximum number of documents retrieved per query. This value will act in place of the usual `size` parameter
+in the query. Defaults to 10.
+|`relevant_rating_threshold` |sets the rating threshold above which documents are considered to be
"relevant". Defaults to `1`.
|`ignore_unlabeled` |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.
@@ -202,6 +207,7 @@ GET /twitter/_rank_eval
}],
"metric": {
"mean_reciprocal_rank": {
+ "k" : 20,
"relevant_rating_threshold" : 1
}
}
@@ -215,6 +221,8 @@ The `mean_reciprocal_rank` metric takes the following optional parameters
[cols="<,<",options="header",]
|=======================================================================
|Parameter |Description
+|`k` |sets the maximum number of documents retrieved per query. This value will act in place of the usual `size` parameter
+in the query. Defaults to 10.
|`relevant_rating_threshold` |Sets the rating threshold above which documents are considered to be
"relevant". Defaults to `1`.
|=======================================================================
@@ -238,6 +246,7 @@ GET /twitter/_rank_eval
}],
"metric": {
"dcg": {
+ "k" : 20,
"normalize": false
}
}
@@ -251,6 +260,8 @@ The `dcg` metric takes the following optional parameters:
[cols="<,<",options="header",]
|=======================================================================
|Parameter |Description
+|`k` |sets the maximum number of documents retrieved per query. This value will act in place of the usual `size` parameter
+in the query. Defaults to 10.
|`normalize` | If set to `true`, this metric will calculate the https://en.wikipedia.org/wiki/Discounted_cumulative_gain#Normalized_DCG[Normalized DCG].
|=======================================================================
