opensearch-docs-cn/_api-reference/rank-eval.md

layout	title	nav_order
default	Ranking evaluation	60

Ranking evaluation

The rank eval endpoint allows you to evaluate the quality of ranked search results.

Path and HTTP methods

GET <index_name>/_rank_eval 
POST <index_name>/_rank_eval

Query parameters

Query parameters are optional.

Parameter	Data Type	Description
ignore_unavailable	Boolean	Defaults to false. When set to false the response body will return an error if an index is closed or missing.
allow_no_indices	Boolean	Defaults to true. When set to false the response body will return an error if a wildcard expression points to indexes that are closed or missing.
expand_wildcards	String	Expand wildcard expressions for indexes that are open, closed, hidden, none, or all.
search_type	String	Set search type to either query_then_fetch or dfs_query_then_fetch.

Request fields

The request body must contain at least one parameter.

Field Type	Description
id	Document or template ID.
requests	Set multiple search requests within the request field section.
ratings	Document relevance score.
k	The number of documents returned per query. Default is set to 10.
relevant_rating_threshold	The threshold at which documents are considered relevant. Default is set to 1.
normalize	Discounted cumulative gain will be calculated when set to true.
maximum_relevance	Sets the maximum relevance score when using the expected reciprocal rank metric.
ignore_unlabeled	Defaults to false. Unlabeled documents are ignored when set to true.
template_id	Template ID.
params	Parameters used in the template.

Sample request

GET shakespeare/_rank_eval
{
  "requests": [
    {
      "id": "books_query",                        
      "request": {                                              
          "query": { "match": { "text": "thou" } }
      },
      "ratings": [                                              
        { "_index": "shakespeare", "_id": "80", "rating": 0 },
        { "_index": "shakespeare", "_id": "115", "rating": 1 },
        { "_index": "shakespeare", "_id": "117", "rating": 2 }
      ]
    },
    {
      "id": "words_query",
      "request": {
        "query": { "match": { "text": "art" } }
      },
      "ratings": [
        { "_index": "shakespeare", "_id": "115", "rating": 2 }
      ]
    }
  ]
}

Sample response

{
  "rank_eval": {
    "metric_score": 0.7,
      "details": {
      "query_1": {                           
        "metric_score": 0.9,                      
        "unrated_docs": [                         
          {
            "_index": "shakespeare",
            "_id": "1234567"
          }, ...
        ],
        "hits": [
          {
            "hit": {                              
              "_index": "shakespeare",
              "_type": "page",
              "_id": "1234567",
              "_score": 5.123456789
            },
            "rating": 1
          }, ...
        ],
        "metric_details": {                       
          "precision": {
            "relevant_docs_retrieved": 3,
            "docs_retrieved": 6
          }
        }
      },
      "query_2": { [... ] }
    },
    "failures": { [... ] }
  }
}