All methods and paths for this operation:
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
Query parameters
-
If
false, the request returns an error if any wildcard expression, index alias, or_allvalue targets only missing or closed indices. This behavior applies even if the request targets other open indices.Default value is
true. -
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 withopen,closed, orboth.none: Wildcard expressions are not accepted.
Default value is
open. -
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. Iffalse, the request returns a task identifier, and stores the completed response for retrieval through the task management API.Default value is
true.
Body
Required
-
The
dense_vectorfield to evaluate. -
The number of nearest neighbors to compute the recall for, from 1 to 1000.
-
The source of the query vectors.
-
The settings of the search that the
knn_settingsentries are compared with. If not specified, it uses avisit_percentageof 20 and arescore_vector.oversampleof 100. -
The kNN search settings to evaluate, from 1 to 32 unique entries.
-
If
true, thebaselinecan beexact. An exact baseline compares every vector at full precision, and can severely slow down other searches.Default value is
false.
POST my-index/_knn_eval
{
"field": "my_vector",
"k": 10,
"query_source": {
"from": "docs",
"size": 100,
"seed": 42
},
"knn_settings": [
{ "visit_percentage": 1 },
{ "visit_percentage": 5 }
]
}resp = client.knn_eval(
index="my-index",
field="my_vector",
k=10,
query_source={
"from": "docs",
"size": 100,
"seed": 42
},
knn_settings=[
{
"visit_percentage": 1
},
{
"visit_percentage": 5
}
],
)const response = await client.knnEval({
index: "my-index",
field: "my_vector",
k: 10,
query_source: {
from: "docs",
size: 100,
seed: 42,
},
knn_settings: [
{
visit_percentage: 1,
},
{
visit_percentage: 5,
},
],
});response = client.knn_eval(
index: "my-index",
body: {
"field": "my_vector",
"k": 10,
"query_source": {
"from": "docs",
"size": 100,
"seed": 42
},
"knn_settings": [
{
"visit_percentage": 1
},
{
"visit_percentage": 5
}
]
}
)$resp = $client->knnEval([
"index" => "my-index",
"body" => [
"field" => "my_vector",
"k" => 10,
"query_source" => [
"from" => "docs",
"size" => 100,
"seed" => 42,
],
"knn_settings" => array(
[
"visit_percentage" => 1,
],
[
"visit_percentage" => 5,
],
),
],
]);curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"field":"my_vector","k":10,"query_source":{"from":"docs","size":100,"seed":42},"knn_settings":[{"visit_percentage":1},{"visit_percentage":5}]}' "$ELASTICSEARCH_URL/my-index/_knn_eval"var response = await client
.KnnEvalAsync(indices: new[] { "my-index" }, d1 => d1
.Field(x => x.MyVector)
.K(10)
.KnnSettings(d2 => d2
.VisitPercentage(1f), d2 => d2
.VisitPercentage(5f)
)
.QuerySource(new KnnEvalDocsQuerySource()
{
Seed = 42,
Size = 100
})
);{
"field": "my_vector",
"k": 10,
"query_source": {
"from": "docs",
"size": 100,
"seed": 42
},
"knn_settings": [
{ "visit_percentage": 1 },
{ "visit_percentage": 5 }
]
}{
"query_source": {
"from": "docs"
},
"baseline": {
"visit_percentage": 20.0,
"rescore_vector": {
"oversample": 100.0
}
},
"baseline_took_ms": 412,
"baseline_vector_ops": 2048000,
"baseline_vector_ops_kind": "quantized_visit_plus_rescore",
"results": [
{
"knn_settings": {
"visit_percentage": 1.0
},
"recall": 0.87,
"included_queries": 100,
"excluded_queries": 0,
"took_ms": 35,
"vector_ops": 102400
},
{
"knn_settings": {
"visit_percentage": 5.0
},
"recall": 0.97,
"included_queries": 99,
"excluded_queries": 1,
"took_ms": 96,
"vector_ops": 512000
}
],
"failures": {}
}