---
title: ES|QL KNN function
description: 
url: https://www.elastic.co/elastic/docs-builder/docs/3028/reference/query-languages/esql/functions-operators/dense-vector-functions/knn
products:
  - Elasticsearch
---

# ES|QL KNN function
<applies-to>
  - Elastic Stack: Preview from 9.2 to 9.3
</applies-to>


## Syntax

![Embedded](https://www.elastic.co/elastic/docs-builder/docs/3028/reference/query-languages/esql/images/functions/knn.svg)


## Parameters

<definitions>
  <definition term="field">
    Field that the query will target. knn function can be used with dense_vector or semantic_text fields. Other text fields are not allowed
  </definition>
  <definition term="query">
    Vector value to find top nearest neighbours for.
  </definition>
  <definition term="options">
    (Optional) kNN additional options as [function named parameters](/elastic/docs-builder/docs/3028/reference/query-languages/esql/esql-syntax#esql-function-named-params). See [knn query](https://www.elastic.co/elastic/docs-builder/docs/3028/reference/query-languages/query-dsl/query-dsl-knn-query) for more information.
  </definition>
</definitions>


## Description

Finds the k nearest vectors to a query vector, as measured by a similarity metric. knn function finds nearest vectors through approximate search on indexed dense_vectors or semantic_text fields.

## Supported types


| field        | query        | options          | result  |
|--------------|--------------|------------------|---------|
| dense_vector | dense_vector | named parameters | boolean |
| text         | dense_vector | named parameters | boolean |


### Supported function named parameters

<definitions>
  <definition term="k">
    (integer) The number of nearest neighbors to return from each shard. Elasticsearch collects k results from each shard, then merges them to find the global top results. This value must be less than or equal to num_candidates. This value is automatically set with any LIMIT applied to the function.
  </definition>
  <definition term="boost">
    (float) Floating point number used to decrease or increase the relevance scores of the query.Defaults to 1.0.
  </definition>
  <definition term="min_candidates">
    (integer) The minimum number of nearest neighbor candidates to consider per shard while doing knn search.  KNN may use a higher number of candidates in case the query can't use a approximate results. Cannot exceed 10,000. Increasing min_candidates tends to improve the accuracy of the final results. Defaults to 1.5 * k (or LIMIT) used for the query.
  </definition>
  <definition term="visit_percentage">
    (float) The percentage of vectors to explore per shard while doing knn search with bbq_disk. Must be between 0 and 100. 0 will default to using num_candidates for calculating the percent visited. Increasing visit_percentage tends to improve the accuracy of the final results. If visit_percentage is set for bbq_disk, num_candidates is ignored. Defaults to ~1% per shard for every 1 million vectors
  </definition>
  <definition term="similarity">
    (double) The minimum similarity required for a document to be considered a match. The similarity value calculated relates to the raw similarity used, not the document score.
  </definition>
  <definition term="rescore_oversample">
    (double) Applies the specified oversampling for rescoring quantized vectors. See [oversampling and rescoring quantized vectors](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/3028/solutions/search/vector/knn#dense-vector-knn-search-rescoring) for details.
  </definition>
</definitions>


## Example

```esql
from colors metadata _score
| where knn(rgb_vector, [0, 120, 0])
| sort _score desc, color asc
```


| color:text | rgb_vector:dense_vector |
|------------|-------------------------|
| green      | [0.0, 128.0, 0.0]       |
| black      | [0.0, 0.0, 0.0]         |
| olive      | [128.0, 128.0, 0.0]     |
| teal       | [0.0, 128.0, 128.0]     |
| lime       | [0.0, 255.0, 0.0]       |
| sienna     | [160.0, 82.0, 45.0]     |
| maroon     | [128.0, 0.0, 0.0]       |
| navy       | [0.0, 0.0, 128.0]       |
| gray       | [128.0, 128.0, 128.0]   |
| chartreuse | [127.0, 255.0, 0.0]     |