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

# Evaluate ranked search results


Availability: 6.2+

## Paths

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

- [Api key auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v8/authentication#apikeyauth)
- [Basic auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v8/authentication#basicauth)
- [Bearer auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v8/authentication#bearerauth)

#### Path Parameters

- `index` (union IndexName | [] IndexName) — 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.

## Required authorization

* Index privileges: `read`

## Query String Parameters

- `allow_no_indices` (boolean · default: true)
  If `false`, the request returns an error if any wildcard expression, index alias, or `_all` value targets only missing or closed indices. This behavior applies even if the request targets other open indices. For example, a request targeting `foo*,bar*` returns an error if an index starts with `foo` but no index starts with `bar`.
- `expand_wildcards` (string ExpandWildcards · default: open)
  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)
  If `true`, missing or closed indices are not included in the response.
- `search_type` (string)
  Search operation type

## Request Body

`application/json`

- `requests` ([] RankEvalRequestItem) — required
  A set of typical search requests, together with their provided ratings.
  - `id` (string Id) — required
    The search request’s ID, used to group result details later.
  - `request` ({} RankEvalQuery) — optional
    The query being evaluated.
    - `query` ({} QueryContainer) — required
      See [QueryContainer](https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v8/types/_types-query_dsl-querycontainer)
    - `size` (number) — optional
  - `ratings` ([] DocumentRating) — required
    List of document ratings
    - `_id` (string Id) — required
      The document ID.
    - `_index` (string IndexName) — 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 Id) — optional
    The search template Id
  - `params` (map string to object) — optional
    The search template parameters.
- `metric` ({} RankEvalMetric) — optional
  Definition of the evaluation metric to calculate.
  - `precision` ({} RankEvalMetricPrecision) — 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` ({} RankEvalMetricRecall) — 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` ({} RankEvalMetricMeanReciprocalRank) — 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` ({} RankEvalMetricDiscountedCumulativeGain) — 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` ({} RankEvalMetricExpectedReciprocalRank) — 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 RankEvalMetricDetail)
  The details section contains one entry for every query in the original requests section, keyed by the search request id
  Map values ({} RankEvalMetricDetail)
  - `metric_score` (number)
    The metric_score in the details section shows the contribution of this query to the global quality metric score
  - `unrated_docs` ([] UnratedDocument)
    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 Id)
    - `_index` (string IndexName)
  - `hits` ([] RankEvalHitItem)
    The hits section shows a grouping of the search results with their supplied ratings
    - `hit` ({} RankEvalHit)
      - `_id` (string Id)
      - `_index` (string IndexName)
      - `_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)
            )
        )
    )
);
```

#### 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
      }
    }
  }
)
```