---
type: api
title: Evaluate ranked search results
description: **All methods and paths for this operation:**
url: https://www.elastic.co/elastic/docs-builder/docs/4493/api/doc/elasticsearch/operation/operation-rank-eval
resource: https://www.elastic.co/elastic/docs-builder/docs/4493/api/doc/elasticsearch/operation/operation-rank-eval
products:
  - Elasticsearch
---

# Evaluate ranked search results


Availability: Generally available since 6.2

## Paths

- `POST` (also `GET`) `/{index}/_rank_eval`
- `POST` (also `GET`) `/_rank_eval`

#### Path parameters

- `index` (union string | string[]) — optional, leave it out to use `/_rank_eval`
  A  comma-separated list of data streams, indices, and index aliases used to limit the request.
Wildcard (`*`) expressions are supported.
To target all data streams and indices in a cluster, omit this parameter or use `_all` or `*`.

## Description

Evaluate the quality of ranked search results over a set of typical search queries.

[More about ranking evaluation](https://www.elastic.co/docs/reference/elasticsearch/rest-apis/search-rank-eval)

## Required authorization

- Index privileges: `read`

## Authentication

- Api key: `Authorization: <value>`
  Elasticsearch APIs support key-based authentication.
  You must create an API key and use the encoded value in the request header.
  For example:
  
  
  ```
  curl -X GET "${ES_URL}/_cat/indices?v=true" \
    -H "Authorization: ApiKey ${API_KEY}"
  ```
  
  To get API keys, use the `/_security/api_key` APIs.
- Basic: `Authorization: Basic <credentials>`
- Bearer: `Authorization: Bearer <token>`
  Elasticsearch APIs support the use of bearer tokens in the `Authorization` HTTP header to authenticate with the API.
  For examples, refer to [Token-based authentication services](https://www.elastic.co/docs/deploy-manage/users-roles/cluster-or-deployment-auth/token-based-authentication-services)

## Query string parameters

- `allow_no_indices` (boolean · default: true) — optional
  A setting that does two separate checks on the index expression.
If `false`, the request returns an error (1) if any wildcard expression
(including `_all` and `*`) resolves to zero matching indices or (2) if the
complete set of resolved indices, aliases or data streams is empty after all
expressions are evaluated. If `true`, index expressions that resolve to no
indices are allowed and the request returns an empty result.
- `expand_wildcards` (string · default: open) — optional
  Whether to expand wildcard expression to concrete indices that are open, closed or both.

Supported values include:
  - `all`: Match any data stream or index, including hidden ones.
  - `open`: Match open, non-hidden indices. Also matches any non-hidden data stream.
  - `closed`: Match closed, non-hidden indices. Also matches any non-hidden data stream. Data streams cannot be closed.
  - `hidden`: Match hidden data streams and hidden indices. Must be combined with `open`, `closed`, or `both`.
  - `none`: Wildcard expressions are not accepted.
  Values: `all`, `open`, `closed`, `hidden`, `none`
- `ignore_unavailable` (boolean · default: false) — optional
  If `false`, the request returns an error if it targets a concrete (non-wildcarded)
index, alias, or data stream that is missing, closed, or otherwise unavailable.
If `true`, unavailable concrete targets are silently ignored.
- `search_type` (enum) — optional
  Search operation type

Supported values include:
  - `query_then_fetch`: Documents are scored using local term and document frequencies for the shard. This is usually faster but less accurate.
  - `dfs_query_then_fetch`: Documents are scored using global term and document frequencies across all shards. This is usually slower but more accurate.
  Values: `query_then_fetch`, `dfs_query_then_fetch`

## Request body

`application/json`

- `requests` (object[]) — required
  A set of typical search requests, together with their provided ratings.
  - `id` (string) — required
    The search request’s ID, used to group result details later.
  - `request` (object) — optional
    The query being evaluated.
    - `query` ({} Query) — required
      See [Query](https://www.elastic.co/elastic/docs-builder/docs/4493/api/doc/elasticsearch/types/_types-query_dsl-querycontainer)
    - `size` (number) — optional
  - `ratings` (object[]) — required
    List of document ratings
    - `_id` (string) — required
      The document ID.
    - `_index` (string) — required
      The document’s index. For data streams, this should be the document’s backing index.
    - `rating` (number) — required
      The document’s relevance with regard to this search request.
  - `template_id` (string) — optional
    The search template Id
  - `params` (map string to object) — optional
    The search template parameters.
- `metric` (object) — optional
  Definition of the evaluation metric to calculate.
  - `precision` (object) — optional
    - `k` (number · default: 10) — optional
      Sets the maximum number of documents retrieved per query. This value will act in place of the usual size parameter in the query.
    - `relevant_rating_threshold` (number · default: 1) — optional
      Sets the rating threshold above which documents are considered to be "relevant".
    - `ignore_unlabeled` (boolean · default: false) — optional
      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.
  - `recall` (object) — optional
    - `k` (number · default: 10) — optional
      Sets the maximum number of documents retrieved per query. This value will act in place of the usual size parameter in the query.
    - `relevant_rating_threshold` (number · default: 1) — optional
      Sets the rating threshold above which documents are considered to be "relevant".
  - `mean_reciprocal_rank` (object) — optional
    - `k` (number · default: 10) — optional
      Sets the maximum number of documents retrieved per query. This value will act in place of the usual size parameter in the query.
    - `relevant_rating_threshold` (number · default: 1) — optional
      Sets the rating threshold above which documents are considered to be "relevant".
  - `dcg` (object) — optional
    - `k` (number · default: 10) — optional
      Sets the maximum number of documents retrieved per query. This value will act in place of the usual size parameter in the query.
    - `normalize` (boolean · default: false) — optional
      If set to true, this metric will calculate the Normalized DCG.
  - `expected_reciprocal_rank` (object) — optional
    - `k` (number · default: 10) — optional
      Sets the maximum number of documents retrieved per query. This value will act in place of the usual size parameter in the query.
    - `maximum_relevance` (number) — required
      The highest relevance grade used in the user-supplied relevance judgments.

## Response

`application/json`

- `metric_score` (number)
  The overall evaluation quality calculated by the defined metric
- `details` (map string to object)
  The details section contains one entry for every query in the original requests section, keyed by the search request id
  Map values (object)
  - `metric_score` (number)
    The metric_score in the details section shows the contribution of this query to the global quality metric score
  - `took` (number)
    The time in milliseconds it took to execute the search request for this query
  - `unrated_docs` (object[])
    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
    - `_id` (string)
    - `_index` (string)
  - `hits` (object[])
    The hits section shows a grouping of the search results with their supplied ratings
    - `hit` (object)
      - `_id` (string)
      - `_index` (string)
      - `_score` (number)
    - `rating` (union number | string) — nullable
  - `metric_details` (map string to string to object)
    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
- `failures` (map string to object)
## Code examples

#### Console

```console
POST /my-index-000001/_rank_eval
{
  "requests": [
    {
      "id": "JFK query",
      "request": { "query": { "match_all": {} } },
      "ratings": []
    } ],
  "metric": {
    "precision": {
      "k": 20,
      "relevant_rating_threshold": 1,
      "ignore_unlabeled": false
    }
  }
}
```

#### JavaScript

```javascript
const response = await client.rankEval({
  index: "my-index-000001",
  requests: [
    {
      id: "JFK query",
      request: {
        query: {
          match_all: {},
        },
      },
      ratings: [],
    },
  ],
  metric: {
    precision: {
      k: 20,
      relevant_rating_threshold: 1,
      ignore_unlabeled: false,
    },
  },
});
```

#### Python

```python
resp = client.rank_eval(
    index="my-index-000001",
    requests=[
        {
            "id": "JFK query",
            "request": {
                "query": {
                    "match_all": {}
                }
            },
            "ratings": []
        }
    ],
    metric={
        "precision": {
            "k": 20,
            "relevant_rating_threshold": 1,
            "ignore_unlabeled": False
        }
    },
)
```

#### curl

```curl
curl -X POST "$ELASTICSEARCH_URL/my-index-000001/_rank_eval" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "requests": [
      {
        "id": "JFK query",
        "request": {
          "query": {
            "match_all": {}
          }
        },
        "ratings": []
      }
    ],
    "metric": {
      "precision": {
        "k": 20,
        "relevant_rating_threshold": 1,
        "ignore_unlabeled": false
      }
    }
  }'
```

#### Java

```java
client.rankEval(r -> r
    .index("my-index-000001")
    .metric(m -> m
        .precision(p -> p
            .ignoreUnlabeled(false)
            .relevantRatingThreshold(1)
            .k(20)
        )
    )
    .requests(re -> re
        .id("JFK query")
        .request(req -> req
            .query(q -> q
                .matchAll(m -> m)
            )
        )
        .ratings(List.of())
    )
);
```

#### C#

```c#
var response = await client
    .RankEvalAsync(d1 => d1
        .Indices(new[] { "my-index-000001" })
        .Metric(d2 => d2
            .Precision(d3 => d3
                .IgnoreUnlabeled(false)
                .K(20)
                .RelevantRatingThreshold(1)
            )
        )
        .Requests(d2 => d2
            .Id("JFK query")
            .Ratings(new List<DocumentRating>())
            .Request(d3 => d3
                .Query(d4 => d4
                    .MatchAll()
                )
            )
        )
    );
```

#### PHP

```php
$resp = $client->rankEval([
    "index" => "my-index-000001",
    "body" => [
        "requests" => array(
            [
                "id" => "JFK query",
                "request" => [
                    "query" => [
                        "match_all" => new ArrayObject([]),
                    ],
                ],
                "ratings" => array(
                ),
            ],
        ),
        "metric" => [
            "precision" => [
                "k" => 20,
                "relevant_rating_threshold" => 1,
                "ignore_unlabeled" => false,
            ],
        ],
    ],
]);
```

#### Ruby

```ruby
response = client.rank_eval(
  index: "my-index-000001",
  body: {
    "requests": [
      {
        "id": "JFK query",
        "request": {
          "query": {
            "match_all": {}
          }
        },
        "ratings": []
      }
    ],
    "metric": {
      "precision": {
        "k": 20,
        "relevant_rating_threshold": 1,
        "ignore_unlabeled": false
      }
    }
  }
)
```