Evaluate kNN search settings

Auth

Estimate the recall and cost of approximate kNN search configurations on a dense_vector field against a more thorough baseline. The field must use the bbq_disk index type, and must not be inside a nested object.

Each knn_settings entry reports the mean recall of the baseline's top k, not of relevance judgments, plus included and excluded query counts and cost totals. A query is excluded from the mean recall when the candidate finds a document scoring above the baseline's lowest top k score. A baseline returning fewer than k hits fails that query, because recall at k is undefined. All configurations run against one point in time.

The default baseline uses a visit_percentage of 20 and a rescore_vector.oversample of 100. An exact full-precision baseline must be requested explicitly with allow_exact_baseline, and is limited to 100 million vector-by-query comparisons.

The request is refused when the search.knn_eval.enabled cluster setting or the index.knn_eval.enabled index setting is false.

Required authorization

Index privileges read view_index_metadata

Path parameters

index union string | string[] required

A comma-separated list of index names to search.

Query parameters

ignore_unavailable boolean · default: false

If false, the request returns an error if it targets a missing or closed index.

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.

expand_wildcards union oneOf · default: open

The type of index that wildcard patterns can match. It supports comma-separated values, such as open,hidden.

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
wait_for_completion boolean · default: true

If true, the request waits for the evaluation to complete. A large evaluation can run for minutes, and closing the connection, for example because of a client or proxy timeout, cancels it. If false, the request returns a task identifier, and stores the completed response for retrieval through the task management API.

Request body

field string required

The dense_vector field to evaluate.

k number required

The number of nearest neighbors to compute the recall for, from 1 to 1000.

query_source union oneOf required

The source of the query vectors.

One of: (determined by from)
from: docs

Samples the query vectors from the stored documents.

from enum required
Values: docs
size number required

The number of documents to sample, from 1 to 1000.

seed number

The seed of the sampling, to sample the same documents across requests.

baseline object

The settings of the search that the knn_settings entries are compared with. If not specified, it uses a visit_percentage of 20 and a rescore_vector.oversample of 100.

visit_percentage number

The percentage of postings to visit, from 0 to 100. 0 selects the automatic visit calculation.

num_candidates number

The number of nearest neighbor candidates to consider per shard. It can't be less than k, or more than 10000 (9999 with sampling).

rescore_vector object

The rescoring of the candidates. Only applies to quantized fields.

oversample number required

Applies the specified oversample factor to k on the approximate kNN search

exact boolean · default: false

If true, compares every vector at full precision. Only applies to the baseline, requires allow_exact_baseline, and can't be combined with other settings.

knn_settings object[] required

The kNN search settings to evaluate, from 1 to 32 unique entries.

visit_percentage number

The percentage of postings to visit, from 0 to 100. 0 selects the automatic visit calculation.

num_candidates number

The number of nearest neighbor candidates to consider per shard. It can't be less than k, or more than 10000 (9999 with sampling).

rescore_vector object

The rescoring of the candidates. Only applies to quantized fields.

oversample number required

Applies the specified oversample factor to k on the approximate kNN search

exact boolean · default: false

If true, compares every vector at full precision. Only applies to the baseline, requires allow_exact_baseline, and can't be combined with other settings.

allow_exact_baseline boolean · default: false

If true, the baseline can be exact. An exact baseline compares every vector at full precision, and can severely slow down other searches.

Response

application/json
query_source object

The source of the query vectors. Not returned when wait_for_completion is false.

from enum required

How the query vectors were chosen.

Values: docs vectors
baseline object

The settings of the baseline search. Not returned when wait_for_completion is false.

visit_percentage number

The percentage of postings to visit, from 0 to 100. 0 selects the automatic visit calculation.

num_candidates number

The number of nearest neighbor candidates to consider per shard. It can't be less than k, or more than 10000 (9999 with sampling).

rescore_vector object

The rescoring of the candidates. Only applies to quantized fields.

oversample number required

Applies the specified oversample factor to k on the approximate kNN search

exact boolean · default: false

If true, compares every vector at full precision. Only applies to the baseline, requires allow_exact_baseline, and can't be combined with other settings.

rescore_window_capped boolean · default: false

If true, the number of vectors to rescore exceeded the limit of 10000.

quantized_scores boolean · default: false

If true, the hits were not rescored, so their scores are estimates, and no query is excluded from the mean recall.

baseline_took_ms number

The time the baseline searches took, in milliseconds. Not returned when wait_for_completion is false.

baseline_vector_ops number

The number of vector operations of the baseline searches. Not returned when wait_for_completion is false.

baseline_vector_ops_kind enum

What baseline_vector_ops counts. Not returned when wait_for_completion is false.

Supported values include:

  • full_precision_scan: Full-precision comparisons across all the matching vectors.
  • quantized_visit_plus_rescore: Quantized visits plus full-precision rescoring.
Values: full_precision_scan quantized_visit_plus_rescore
results object[]

The results of each knn_settings entry, in the order of the request. Not returned when wait_for_completion is false.

knn_settings object required

The evaluated settings.

visit_percentage number

The percentage of postings to visit, from 0 to 100. 0 selects the automatic visit calculation.

num_candidates number

The number of nearest neighbor candidates to consider per shard. It can't be less than k, or more than 10000 (9999 with sampling).

rescore_vector object

The rescoring of the candidates. Only applies to quantized fields.

oversample number required

Applies the specified oversample factor to k on the approximate kNN search

exact boolean · default: false

If true, compares every vector at full precision. Only applies to the baseline, requires allow_exact_baseline, and can't be combined with other settings.

rescore_window_capped boolean · default: false

If true, the number of vectors to rescore exceeded the limit of 10000.

quantized_scores boolean · default: false

If true, the hits were not rescored, so their scores are estimates, and no query is excluded from the mean recall.

recall union number | string required nullable

The mean recall of the included queries, or null if no query is included.

included_queries number required

The number of queries included in the mean recall.

excluded_queries number required

The number of queries excluded from the mean recall, because the search found a document scoring above the baseline's lowest top k score.

took_ms number required

The time the searches took, in milliseconds.

vector_ops number required

The number of vector operations of the searches.

failures map string to object

The queries that failed, by query identifier. Not returned when wait_for_completion is false.

<string> object
error object required
type string required

The type of error

reason union string nullable

A human-readable explanation of the error, in English.

One of: string
stack_trace string

The server stack trace. Present only if the error_trace=true parameter was sent with the request.

caused_by object
Same fields as error in failures
root_cause object[]
Same fields as error in failures
suppressed object[]
Same fields as error in failures
task string

The identifier of the task that runs the evaluation. Only returned when wait_for_completion is false.