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.
A kNN search response has the exact same structure as a search API response. However, certain sections have a meaning specific to kNN search:
- The document
_score
is determined by the similarity between the query and document vector. - The
hits.total
object contains the total number of nearest neighbor candidates considered, which isnum_candidates * num_shards
. Thehits.total.relation
will always beeq
, indicating an exact value.
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. It accepts wildcard (*
) patterns. -
stored_fields string | array[string]
-
fields string | array[string]
filter object | array[object]
A 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.One of: An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
Additional properties are allowed.
-
Additional properties are allowed.
curl \
--request GET http://api.example.com/{index}/_knn_search \
--header "Content-Type: application/json" \
--data '{"":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
}