Evaluate ranked search results

POST also GET /{index}/_rank_eval
POST also GET /_rank_eval

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

Required authorization

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

Path parameters

Query parameters

Request body

requests object[] required: A set of typical search requests, together with their provided ratings.
metric object: Definition of the evaluation metric to calculate.

Response

application/json

metric_score number required: The overall evaluation quality calculated by the defined metric
details map string to object required: The details section contains one entry for every query in the original requests section, keyed by the search request id
failures map string to object required

Examples

Request Console 1 / 8 languages

An example body for a GET /my-index-000001/_rank_eval request.

Console Kibana Dev Tools

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 Elasticsearch JavaScript Client

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 Elasticsearch Python Client

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 Shell

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 Elasticsearch Java Client

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# Elasticsearch .NET Client

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 Elasticsearch PHP Client

$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 Elasticsearch Ruby Client

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

Response

No example

Required authorization

Authentication

Path parameters

Query parameters

Request body { }

Response

Request body