---
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/v9/operation/operation-rank-eval
resource: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v9/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/v9/authentication#apikeyauth)
- [Basic auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v9/authentication#basicauth)
- [Bearer auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v9/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`

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

## Query String Parameters

- `allow_no_indices` (boolean · default: true)
  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 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 `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 SearchType)
  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` ([] 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/v9/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)
            )
        )
        .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
      }
    }
  }
)
```