Evaluate ranked search results Generally available; Added in 6.2.0

POST /{index}/_rank_eval
Api key auth Basic auth Bearer auth

All methods and paths for this operation:

GET /_rank_eval

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

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

Required authorization

  • Index privileges: read

Path parameters

  • index string | array[string] Required

    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 *.

Query parameters

  • allow_no_indices boolean

    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 | array[string]

    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 are all, open, closed, hidden, or none.

  • ignore_unavailable boolean

    If true, missing or closed indices are not included in the response.

  • search_type string

    Search operation type

application/json

Body Required

  • requests array[object] Required

    A set of typical search requests, together with their provided ratings.

    Hide requests attributes Show requests attributes object
    • id string Required
    • request object
      Hide request attributes Show request attributes object
      • query object Required

        An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.

        External documentation
      • size number
    • ratings array[object] Required

      List of document ratings

      Hide ratings attributes Show ratings attributes object
      • _id string Required
      • _index string Required
      • rating number Required

        The document’s relevance with regard to this search request.

    • template_id string
    • params object

      The search template parameters.

      Hide params attribute Show params attribute object
      • * object Additional properties
  • metric object
    Hide metric attributes Show metric attributes object
    • precision object

      Precision at K (P@k)

      Hide precision attributes Show precision attributes object
      • k number

        Sets the maximum number of documents retrieved per query. This value will act in place of the usual size parameter in the query.

        Default value is 10.

      • relevant_rating_threshold number

        Sets the rating threshold above which documents are considered to be "relevant".

        Default value is 1.

      • ignore_unlabeled boolean

        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.

        Default value is false.

    • recall object

      Recall at K (R@k)

      Hide recall attributes Show recall attributes object
      • k number

        Sets the maximum number of documents retrieved per query. This value will act in place of the usual size parameter in the query.

        Default value is 10.

      • relevant_rating_threshold number

        Sets the rating threshold above which documents are considered to be "relevant".

        Default value is 1.

    • mean_reciprocal_rank object

      Mean Reciprocal Rank

      Hide mean_reciprocal_rank attributes Show mean_reciprocal_rank attributes object
      • k number

        Sets the maximum number of documents retrieved per query. This value will act in place of the usual size parameter in the query.

        Default value is 10.

      • relevant_rating_threshold number

        Sets the rating threshold above which documents are considered to be "relevant".

        Default value is 1.

    • dcg object

      Discounted cumulative gain (DCG)

      Hide dcg attributes Show dcg attributes object
      • k number

        Sets the maximum number of documents retrieved per query. This value will act in place of the usual size parameter in the query.

        Default value is 10.

      • normalize boolean

        If set to true, this metric will calculate the Normalized DCG.

        Default value is false.

    • expected_reciprocal_rank object

      Expected Reciprocal Rank (ERR)

      Hide expected_reciprocal_rank attributes Show expected_reciprocal_rank attributes object
      • k number

        Sets the maximum number of documents retrieved per query. This value will act in place of the usual size parameter in the query.

        Default value is 10.

      • maximum_relevance number Required

        The highest relevance grade used in the user-supplied relevance judgments.

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • metric_score number Required

      The overall evaluation quality calculated by the defined metric

    • details object Required

      The details section contains one entry for every query in the original requests section, keyed by the search request id

      Hide details attribute Show details attribute object
      • * object Additional properties
        Hide * attributes Show * attributes object
        • metric_score number Required

          The metric_score in the details section shows the contribution of this query to the global quality metric score

        • unrated_docs array[object] Required

          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

          Hide unrated_docs attributes Show unrated_docs attributes object
          • _id string Required
          • _index string Required
        • hits array[object] Required

          The hits section shows a grouping of the search results with their supplied ratings

          Hide hits attributes Show hits attributes object
        • metric_details object Required

          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

          Hide metric_details attribute Show metric_details attribute object
          • * object Additional properties
            Hide * attribute Show * attribute object
            • * object Additional properties
    • failures object Required
      Hide failures attribute Show failures attribute object
      • * object Additional properties
POST /{index}/_rank_eval 
GET /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 } } }
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 } }, )
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, }, }, });
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 } } } )
$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, ], ], ], ]);
curl -X GET -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}}}' "$ELASTICSEARCH_URL/my-index-000001/_rank_eval"
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) ) ) ) );
Request example
An example body for a `GET /my-index-000001/_rank_eval` request. 
{ "requests": [ { "id": "JFK query", "request": { "query": { "match_all": {} } }, "ratings": [] } ], "metric": { "precision": { "k": 20, "relevant_rating_threshold": 1, "ignore_unlabeled": false } } }