---
title: kNN search in Elasticsearch
description: Find semantically similar documents using k-nearest neighbor (kNN) vector search in Elasticsearch.
url: https://www.elastic.co/elastic/docs-builder/docs/4300/solutions/search/vector/knn
products:
  - Elastic Documentation
  - Elasticsearch
applies_to:
  - Elastic Cloud Serverless: Generally available
  - Elastic Stack: Generally available
---

# kNN search in Elasticsearch
A *k-nearest neighbor* (kNN) search finds the *k* nearest vectors to a query vector using a similarity metric such as cosine or L2 norm. In Elasticsearch, kNN is the primary way to query [`dense_vector`](https://www.elastic.co/elastic/docs-builder/docs/4300/solutions/search/vector/dense-vector) fields after you store embeddings.

## Common use cases for kNN vector similarity search

kNN vector similarity search supports use cases across search, recommendations, and analysis:
- **Search**
  - [Semantic text search](https://www.elastic.co/elastic/docs-builder/docs/4300/solutions/search/semantic-search): Find documents that match the meaning of a query, even when the wording differs.
- [Image and video similarity](/elastic/docs-builder/docs/4300/solutions/search/vector/vector-search-use-cases#multimodal-search): Search across text, images, audio, or video to find visually or semantically similar content.
- **Recommendations**
  - [Product recommendations](/elastic/docs-builder/docs/4300/solutions/search/vector/vector-search-use-cases#discovery-and-recommendations): Surface items similar to what a user is viewing or has interacted with.
- [Collaborative filtering](/elastic/docs-builder/docs/4300/solutions/search/vector/vector-search-use-cases#discovery-and-recommendations): Match users or items based on shared behavior or preference patterns in vector space.
- [Personalized content discovery](/elastic/docs-builder/docs/4300/solutions/search/vector/vector-search-use-cases#discovery-and-recommendations): Suggest articles, media, or other content tailored to individual user interests.
- **Analysis**
  - [Anomaly detection](/elastic/docs-builder/docs/4300/solutions/search/vector/vector-search-use-cases#duplicate-detection-fraud-and-anomaly-detection): Flag records whose vectors sit unusually far from their nearest neighbors.
- [Pattern matching](/elastic/docs-builder/docs/4300/solutions/search/vector/vector-search-use-cases#duplicate-detection-fraud-and-anomaly-detection): Find near-duplicates, suspicious matches, or other patterns that exact matching would miss.


## Prerequisites for kNN search

To run a kNN search in Elasticsearch:
- Your data must be vectorized. You can:
  - Use [`semantic_text`](https://www.elastic.co/elastic/docs-builder/docs/4300/solutions/search/semantic-search/semantic-search-semantic-text) to have Elastic generate embeddings automatically.
- Use the [Elastic Inference Service](https://www.elastic.co/elastic/docs-builder/docs/4300/explore-analyze/elastic-inference/eis) for managed inference.
- [Deploy an NLP model](https://www.elastic.co/elastic/docs-builder/docs/4300/explore-analyze/machine-learning/nlp/ml-nlp-text-emb-vector-search-example) on an ML node.
- Generate vectors outside of your Elastic deployment. Learn how to [Bring your own dense vectors](https://www.elastic.co/elastic/docs-builder/docs/4300/solutions/search/vector/bring-own-vectors).

<tip>
  Query vectors must have the same dimension and be created with the same model as the document vectors.
</tip>

- Required [index privileges](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/4300/reference/elasticsearch/security-privileges#privileges-list-indices):
  - `create_index` or `manage` to create an index with a `dense_vector` field
- `create`, `index`, or `write` to add data
- `read` to search the index

If you're using Elastic Cloud Serverless, [compare Elasticsearch and Vector Database projects](/elastic/docs-builder/docs/4300/solutions/vector-database#when-to-use-this-project-type) before implementing kNN search.

## kNN search methods

Elasticsearch provides two ways to perform kNN search. Select a method based on your dataset size, latency requirements, and whether you need exact scoring.
[**Approximate kNN**](https://www.elastic.co/elastic/docs-builder/docs/4300/solutions/search/vector/knn/approximate-knn) is best for most production workloads where low latency and scale matter more than perfect recall. It narrows the search to likely matches instead of scoring every document, reducing latency on large datasets.
[**Exact, brute-force kNN**](https://www.elastic.co/elastic/docs-builder/docs/4300/solutions/search/vector/knn/exact-knn) is best for small datasets, pre-filtered subsets, or when you need precise scoring without approximate indexing. It scores every matching document, which guarantees accurate results but does not scale well for large datasets. You can improve latency by filtering your data to a small subset of documents.

## kNN search examples

Every kNN search needs a query vector. You can provide it directly or have Elasticsearch generate or retrieve it at search time with `query_vector_builder`. The exact `dense_vector` query and the approximate kNN methods support query vector builders.
For examples that provide a query vector directly, refer to:
- [Approximate kNN search](/elastic/docs-builder/docs/4300/solutions/search/vector/knn/approximate-knn#approximate-knn-example)
- [Exact kNN with the `dense_vector` query](/elastic/docs-builder/docs/4300/solutions/search/vector/knn/exact-knn#exact-knn-dense-vector-query)
- [Exact kNN with a `script_score` query](/elastic/docs-builder/docs/4300/solutions/search/vector/knn/exact-knn#exact-knn-script-score-query)


### Generate or retrieve a query vector at search time

The following examples use `query_vector_builder` with the top-level `knn` option. You can use the same builders with the exact `dense_vector` query. For all available builders and their parameters, refer to [Query vector builders](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/4300/reference/query-languages/query-dsl/query-dsl-knn-query#query-vector-builders-overview).

#### Use the `text_embedding` query vector builder

Use the `text_embedding` query vector builder to generate a query vector from text. Specify the same model that generated the document vectors.
Reference the deployed model or its deployment in the `query_vector_builder` object, and pass the search string as `model_text`:
```json

{
  "knn": {
    "field": "dense-vector-field",
    "k": 10,
    "num_candidates": 100,
    "query_vector_builder": {
      "text_embedding": {
        "model_id": "my-text-embedding-model", <1>
        "model_text": "The opposite of blue" <2>
      }
    }
  }
}
```

For a walkthrough that covers deploying a model, generating document embeddings, and querying them, refer to this [end-to-end example](https://www.elastic.co/elastic/docs-builder/docs/4300/explore-analyze/machine-learning/nlp/ml-nlp-text-emb-vector-search-example).

#### Use the `lookup` query vector builder

<applies-to>
  - Elastic Stack: Generally available since 9.4
</applies-to>

Use the [`lookup` query vector builder](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/4300/reference/query-languages/query-dsl/query-dsl-knn-query#knn-query-builder-lookup) when the vector you want to search with is already stored in a document. This is the pattern behind "more like this" and recommendation features: instead of embedding new input, you take the vector from an item the user is viewing and find its nearest neighbors.
The following request finds the images most similar to document `2`:
```json

{
  "knn": {
    "field": "image-vector",
    "k": 10,
    "query_vector_builder": {
      "lookup": {
        "index": "image-index", <1>
        "id": "2", <2>
        "path": "image-vector" <3>
      }
    }
  }
}
```

Elasticsearch reads the vector from the indexed field rather than from `_source`, so the lookup works even when vector values are excluded from `_source`.
The looked-up document is its own nearest neighbor, so it comes back as the top hit. Exclude it with a filter when you only want other documents:
```json

{
  "knn": {
    "field": "image-vector",
    "k": 10,
    "query_vector_builder": {
      "lookup": {
        "index": "image-index",
        "id": "2",
        "path": "image-vector"
      }
    },
    "filter": {
      "bool": {
        "must_not": {
          "ids": {
            "values": ["2"]
          }
        }
      }
    }
  }
}
```


### Find more examples by method

For approximate kNN similarity thresholds, hybrid search, multiple vector fields, and aggregations, refer to [Approximate kNN query examples](https://www.elastic.co/elastic/docs-builder/docs/4300/solutions/search/vector/knn/approximate-knn-query-examples). For filtering, refer to [Filter approximate kNN results](https://www.elastic.co/elastic/docs-builder/docs/4300/solutions/search/vector/knn/filtered-knn-search).
For exact kNN filtering and scoring examples, refer to [Exact kNN search](https://www.elastic.co/elastic/docs-builder/docs/4300/solutions/search/vector/knn/exact-knn).

## Next steps

Continue with the guide for the kNN search method that fits your use case:
- [Approximate kNN search](https://www.elastic.co/elastic/docs-builder/docs/4300/solutions/search/vector/knn/approximate-knn): Learn how to map, index, and query `dense_vector` fields for fast, scalable approximate kNN search.
- [Exact kNN search](https://www.elastic.co/elastic/docs-builder/docs/4300/solutions/search/vector/knn/exact-knn): Learn how to run exact brute-force kNN search for small datasets or precise scoring.