Run a knn search Deprecated Technical preview
NOTE: The kNN search API has been replaced by the knn
option in the search API.
Perform a k-nearest neighbor (kNN) search on a dense_vector field and return the matching documents. Given a query vector, the API finds the k closest vectors and returns those documents as search hits.
Elasticsearch uses the HNSW algorithm to support efficient kNN search. Like most kNN algorithms, HNSW is an approximate method that sacrifices result accuracy for improved search speed. This means the results returned are not always the true k closest neighbors.
The kNN search API supports restricting the search using a filter. The search will return the top k documents that also match the filter query.
Path parameters
-
A comma-separated list of index names to search; use
_all
or to perform the operation on all indices
Query parameters
-
routing string
A comma-separated list of specific routing values
Body
_source boolean | object
Defines how to fetch a source. Fetching can be disabled entirely, or the source can be filtered.
-
docvalue_fields array[object]
The request returns doc values for field names matching these patterns in the hits.fields property of the response. Accepts wildcard (*) patterns.
-
stored_fields string | array[string]
-
fields string | array[string]
filter object | array[object]
Query to filter the documents that can match. The kNN search will return the top
k
documents that also match this filter. The value can be a single query or a list of queries. Iffilter
isn't provided, all documents are allowed to match.-
Additional properties are allowed.
curl \
-X POST http://api.example.com/{index}/_knn_search \
-H "Content-Type: application/json" \
-d '{"":true,"docvalue_fields":[{"field":"string","format":"string","include_unmapped":true}],"stored_fields":"string","fields":"string","filter":{},"knn":{"field":"string","query_vector":[42.0],"k":42.0,"num_candidates":42.0}}'
{
"": true,
"docvalue_fields": [
{
"field": "string",
"format": "string",
"include_unmapped": true
}
],
"stored_fields": "string",
"fields": "string",
"filter": {},
"knn": {
"field": "string",
"query_vector": [
42.0
],
"k": 42.0,
"num_candidates": 42.0
}
}
{
"took": 42.0,
"timed_out": true,
"_shards": {
"failed": 42.0,
"successful": 42.0,
"total": 42.0,
"failures": [
{
"index": "string",
"node": "string",
"reason": {
"type": "string",
"reason": "string",
"stack_trace": "string",
"caused_by": {},
"root_cause": [
{}
],
"suppressed": [
{}
]
},
"shard": 42.0,
"status": "string"
}
],
"skipped": 42.0
},
"hits": {
"total": {
"relation": "eq",
"value": 42.0
},
"hits": [
{
"_index": "string",
"_id": "string",
"_score": 42.0,
"_explanation": {
"description": "string",
"details": [
{}
],
"value": 42.0
},
"fields": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"highlight": {
"additionalProperty1": [
"string"
],
"additionalProperty2": [
"string"
]
},
"inner_hits": {
"additionalProperty1": {
"hits": {}
},
"additionalProperty2": {
"hits": {}
}
},
"matched_queries": [
"string"
],
"_nested": {
"field": "string",
"offset": 42.0,
"_nested": {}
},
"_ignored": [
"string"
],
"ignored_field_values": {
"additionalProperty1": [
{}
],
"additionalProperty2": [
{}
]
},
"_shard": "string",
"_node": "string",
"_routing": "string",
"_source": {},
"_rank": 42.0,
"_seq_no": 42.0,
"_primary_term": 42.0,
"_version": 42.0,
"sort": [
42.0
]
}
],
"max_score": 42.0
},
"fields": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"max_score": 42.0
}