[[knn-search-api]]
=== kNN search API
++++
<titleabbrev>kNN search</titleabbrev>
++++

deprecated::[8.4.0,"The kNN search API has been replaced by the <<search-api-knn, `knn` option>> in the search API."]

Performs a k-nearest neighbor (kNN) search and returns the matching documents.

////
[source,console]
----
PUT my-index
{
  "mappings": {
    "properties": {
      "image_vector": {
        "type": "dense_vector",
        "dims": 3,
        "index": true,
        "similarity": "l2_norm"
      }
    }
  }
}

PUT my-index/_doc/1?refresh
{
  "image_vector" : [0.5, 10, 6]
}
----
////

[source,console]
----
GET my-index/_knn_search
{
  "knn": {
    "field": "image_vector",
    "query_vector": [0.3, 0.1, 1.2],
    "k": 10,
    "num_candidates": 100
  },
  "_source": ["name", "file_type"]
}
----
// TEST[continued]
// TEST[warning:The kNN search API has been replaced by the `knn` option in the search API.]

[[knn-search-api-request]]
==== {api-request-title}

`GET <target>/_knn_search`

`POST <target>/_knn_search`

[[knn-search-api-prereqs]]
==== {api-prereq-title}

* If the {es} {security-features} are enabled, you must have the `read`
<<privileges-list-indices,index privilege>> for the target data stream, index,
or alias.

[[knn-search-api-desc]]
==== {api-description-title}

The kNN search API performs a k-nearest neighbor (kNN) search on a
<<dense-vector,`dense_vector`>> field. Given a query vector, it finds the _k_
closest vectors and returns those documents as search hits.

//tag::hnsw-algorithm[]
{es} uses the https://arxiv.org/abs/1603.09320[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.
//end::hnsw-algorithm[]

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.

[[knn-search-api-path-params]]
==== {api-path-parms-title}

`<target>`::
(Optional, string) Comma-separated list of data streams, indices, and aliases
to search. Supports wildcards (`*`). To search all data streams and indices,
use `*` or `_all`.

[role="child_attributes"]
[[knn-search-api-query-params]]
==== {api-query-parms-title}

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=routing]

[role="child_attributes"]
[[knn-search-api-request-body]]
==== {api-request-body-title}

`knn`::
(Required, object) 
include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=knn]


include::{es-repo-dir}/search/search.asciidoc[tag=docvalue-fields-def]
include::{es-repo-dir}/search/search.asciidoc[tag=fields-param-def]
include::{es-repo-dir}/search/search.asciidoc[tag=source-filtering-def]
include::{es-repo-dir}/search/search.asciidoc[tag=stored-fields-def]

[role="child_attributes"]
[[knn-search-api-response-body]]
==== {api-response-body-title}

A kNN search response has the exact same structure as a
<<search-api-response-body, search API response>>. However, certain sections
have a meaning specific to kNN search:

* The <<search-api-response-body-score,document `_score`>> is determined by
the similarity between the query and document vector. See
<<dense-vector-similarity, `similarity`>>.
* 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.