Type to search.

Run a knn search

  • POST also GET /{index}/_knn_search
Auth The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Preview since 8.0 This functionality is in technical preview and is ready for evaluation. Use with caution in production; it is not recommended for mission-critical workloads. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. Specific Support terms apply. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes. 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:
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 The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Generally available since 8.2 This functionality is generally available and ready for production usage. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes.

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.

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
fields map string to object
highlight map string to string
inner_hits map string to object
matched_queries union oneOf
One of: string[] or string to number
_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.