Run a knn search

  • POST also GET /{index}/_knn_search
Auth Deprecated
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 is num_candidates * num_shards. The hits.total.relation will always be eq, indicating an exact value.

Path parameters

index union string | string[] required

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.

Request body

_source union oneOf · default: true

Indicates which source fields are returned for matching documents. These fields are returned in the hits._source property of the search response.

One of:
docvalue_fields object[]

The request returns doc values for field names matching these patterns in the hits.fields property of the response. It accepts wildcard (*) patterns.

field string required

A wildcard pattern. The request returns values for field names matching this pattern.

format string

The format in which the values are returned.

include_unmapped boolean
stored_fields union oneOf

A list of stored fields to return as part of a hit. If no fields are specified, no stored fields are included in the response. If this field is specified, the _source parameter defaults to false. You can pass _source: true to return both source fields and stored fields in the search response.

One of: string[] or string
fields union oneOf

The request returns values for field names matching these patterns in the hits.fields property of the response. It accepts wildcard (*) patterns.

One of: string[] or string
filter union oneOf

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. If filter isn't provided, all documents are allowed to match.

One of: Query[] or Query
knn object required

The kNN query to run.

Reference
field string required

The name of the vector field to search against

query_vector number[] required

The query vector

k number required

The final number of nearest neighbors to return as top hits

num_candidates number required

The number of nearest neighbor candidates to consider per shard

Response

application/json
took number required

The milliseconds it took Elasticsearch to run the request.

timed_out boolean required

If true, the request timed out before completion; returned results may be partial or empty.

_shards object required

A count of shards used for the request.

failed number required

The number of shards the operation or search attempted to run on but failed.

successful number required

The number of shards the operation or search succeeded on.

total number required

The number of shards the operation or search will run on overall.

failures object[]
index string
node string
reason 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 reason in failures
root_cause object[]
Same fields as reason in failures
suppressed object[]
Same fields as reason in failures
shard number
status string
primary boolean
skipped number
hits object required

The returned documents and metadata.

total union oneOf

Total hit count information, present only if track_total_hits wasn't false in the search request.

One of:
relation enum required

Supported values include:

  • eq: Accurate
  • gte: Lower bound, including returned events or sequences
Values: eq gte
value number required
hits object[] required
_index string required
_id string
_score union number | string nullable
_explanation object
description string required
details object[] required
description string required
details object[]
Same fields as details in _explanation
value number required
value number required
fields map string to object
highlight map string to string
inner_hits map string to object
<string> object
hits object required
Same fields as hits
matched_queries union oneOf
One of: string[] or string to number
_nested object
field string required
offset number required
_nested object
Same fields as _nested in hits
_ignored string[]
ignored_field_values map string to oneOf
_shard string
_node string
_routing string
_source object
_rank number
_seq_no number
_primary_term number
_version number
sort union[]
max_score union number | string nullable
fields map string to object

The field values for the documents. These fields must be specified in the request using the fields parameter.

max_score number

The highest returned document score. This value is null for requests that do not sort by score.