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

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 are query_then_fetch or dfs_query_then_fetch.

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
  
  The search request’s ID, used to group result details later.
- request object
  
  The query being evaluated.
  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
  
  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
  
  The search template Id
- params object
  
  The search template parameters.
  Hide params attribute Show params attribute object
  
  * object Additional properties
metric object

Definition of the evaluation metric to calculate.
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
  
  hit object Required
  
  rating number | string | null
  
  One of:
  number-1 number string-2 string | null
  
  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
    }
  }
}

Evaluate ranked search results Generally available; Added in 6.2.0

Required authorization

Path parameters

Query parameters

Body Required

Responses

rating number | string | null