---
title: Approximate kNN search
description: Run fast, scalable approximate k-nearest neighbor (kNN) vector search in Elasticsearch, including search methods and indexing considerations.
url: https://www.elastic.co/elastic/docs-builder/docs/4300/solutions/search/vector/knn/approximate-knn
products:
- Elastic Documentation
applies_to:
- Elastic Cloud Serverless: Generally available
- Elastic Stack: Generally available
---
# Approximate kNN search
Approximate kNN search uses graph-based or clustered index structures to find similar vectors quickly at scale. Use it for most production workloads where you need low latency at scale. This page covers approximate kNN search methods, a basic example, mapping defaults, indexing considerations, and vector index mode.
If you use `semantic_text` fields, query them with a [`match` query](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/4300/reference/query-languages/query-dsl/query-dsl-match-query) for the simplest approach, or use the [`knn` query](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/4300/reference/query-languages/query-dsl/query-dsl-knn-query#knn-query-with-semantic-text) when you need more control over the search.
Approximate kNN search has specific resource requirements. For instance, for HNSW, all vector data must fit in the node’s page cache for efficient performance. Refer to the [approximate kNN tuning guide](https://www.elastic.co/elastic/docs-builder/docs/4300/deploy-manage/production-guidance/optimize-performance/approximate-knn-search) for configuration tips.
## Approximate kNN search methods
Elasticsearch provides three ways to run approximate kNN search, with different field type support:
| Method | Supported field types | Use case |
|--------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------|
| [Top-level `knn` option](#approximate-knn-example) | [`dense_vector`](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/4300/reference/elasticsearch/mapping-reference/dense-vector) | Standalone kNN search or hybrid search with score fusion |
| [`knn` query](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/4300/reference/query-languages/query-dsl/query-dsl-knn-query) | [`dense_vector`](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/4300/reference/elasticsearch/mapping-reference/dense-vector), [`semantic_text`](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/4300/reference/elasticsearch/mapping-reference/semantic-text) | Composable with other queries in a `bool` clause. Required for `semantic_text` fields |
| [`knn` retriever](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/4300/reference/elasticsearch/rest-apis/retrievers/knn-retriever) | [`dense_vector`](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/4300/reference/elasticsearch/mapping-reference/dense-vector) | Use within a retriever pipeline for ranking and result merging |
## Basic example
Follow these steps to map `dense_vector` fields, index embeddings, and run a basic approximate kNN query.
1. Map one or more `dense_vector` fields. Approximate kNN search is enabled by default, so no extra mapping options are required.
Optionally, you can configure additional parameters, including the similarity metric, index options, and quantization. Refer to [`dense_vector`](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/4300/reference/elasticsearch/mapping-reference/dense-vector#dense-vector-params) for the full list of parameters.
```json
{
"mappings": {
"properties": {
"image-vector": {
"type": "dense_vector",
"similarity": "l2_norm"
},
"title": {
"type": "text"
},
"file-type": {
"type": "keyword"
}
}
}
}
```
2. Index your data with embeddings. If you don't have vectors yet, refer to [Bring your own dense vectors](https://www.elastic.co/elastic/docs-builder/docs/4300/solutions/search/vector/bring-own-vectors) for options on generating or sourcing them.
```json
{ "index": { "_id": "1" } }
{ "image-vector": [1, 5, -20], "title": "moose family", "file-type": "jpg" }
{ "index": { "_id": "2" } }
{ "image-vector": [42, 8, -15], "title": "alpine lake", "file-type": "png" }
{ "index": { "_id": "3" } }
{ "image-vector": [15, 11, 23], "title": "full moon", "file-type": "jpg" }
...
```
3. Query using the [`knn` option](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-search#operation-search-body-application-json-knn):
```json
{
"knn": {
"field": "image-vector",
"query_vector": [-5, 9, -12],
"k": 10
}
}
```
Alternatively, use a [`knn` query](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/4300/reference/query-languages/query-dsl/query-dsl-knn-query), which you can combine with other queries in a `bool` clause:
```json
{
"query": {
"knn": {
"field": "image-vector",
"query_vector": [-5, 9, -12],
"k": 10
}
}
}
```
The document `_score` is a positive float calculated based on the chosen vector similarity metric. Refer to [`similarity`](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/4300/reference/elasticsearch/mapping-reference/dense-vector#dense-vector-similarity) for details on how kNN scores are computed.
## Mapping defaults
Approximate kNN works without any explicit mapping options. Unless you set them, Elasticsearch applies these defaults:
| Parameter | Default |
|----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `index` | `true`, so the field is searchable with approximate kNN |
| `element_type` | `float` |
| `dims` | Inferred from the first vector indexed into the field |
| `similarity` | `cosine`, except for `bit` vectors, which use `l2_norm` |
| `index_options.type` | `float` and `bfloat16` vectors are quantized automatically, using BBQ where available and `int8_hnsw` for low-dimensional vectors. `byte` and `bit` vectors are not quantized. |
The `index_options.type` default is particularly important: by default your `float` vectors are quantized, which is what keeps memory use manageable at scale. Refer to [Default quantization types](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/4300/reference/elasticsearch/mapping-reference/dense-vector#dense-vector-quantization) for how the default is chosen, and to [Optimize performance and accuracy](https://www.elastic.co/elastic/docs-builder/docs/4300/solutions/search/vector/knn/optimize-performance-accuracy) if you need to override it.
## Indexing considerations for approximate kNN search
For approximate kNN, Elasticsearch indexes dense vector values as an [HNSW graph](https://arxiv.org/abs/1603.09320) or as clusters using [DiskBBQ](https://www.elastic.co/search-labs/blog/diskbbq-elasticsearch-introduction). Building these structures is compute-intensive. [GPU-accelerated vector indexing](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/4300/solutions/search/vector/gpu-vector-indexing) is also supported. To reduce memory use and speed up vector distance calculations, Elasticsearch also [quantizes](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/4300/reference/elasticsearch/mapping-reference/dense-vector#dense-vector-quantization) vectors.
Quantization comes at the expense of recall, which you can compensate for by [oversampling and rescoring](/elastic/docs-builder/docs/4300/solutions/search/vector/knn/optimize-performance-accuracy#dense-vector-knn-search-rescoring) more vectors. The `hnsw` and `bbq_disk` types each come with their own settings to balance recall, indexing speed, and vector search speed.
For guidance on choosing and tuning these settings, refer to the [approximate kNN tuning guide](https://www.elastic.co/elastic/docs-builder/docs/4300/deploy-manage/production-guidance/optimize-performance/approximate-knn-search). When defining your `dense_vector` mapping, use [`index_options`](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/4300/reference/elasticsearch/mapping-reference/dense-vector#dense-vector-index-options) to set these parameters.
## Vector index mode
- Elastic Cloud Serverless: Generally available
- Elastic Stack: Generally available since 9.5
If an index is used primarily for vector search, create it with the `vectordb_document` [index mode](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/4300/reference/elasticsearch/index-settings/index-modules#index-mode-setting) to get defaults tuned for vector workloads:
```json
{
"settings": {
"index": {
"mode": "vectordb_document"
}
}
}
```
In this mode, Elasticsearch encodes vectors as `bfloat16` to halve raw vector storage, excludes vector values from `_source`, preloads vector index files into the filesystem cache, and tunes merging for vector data.
Refer to [Index modes for vector search](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/4300/reference/elasticsearch/mapping-reference/dense-vector#dense-vector-index-modes) for the full list of applied settings.
## Resources
- [Tune approximate kNN search](https://www.elastic.co/elastic/docs-builder/docs/4300/deploy-manage/production-guidance/optimize-performance/approximate-knn-search): Production guidance for vector memory, node sizing, indexing, filesystem cache, and on-disk rescoring.
- [Profile kNN search](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/4300/reference/elasticsearch/rest-apis/search-profile#profiling-knn-search): Inspect query timing and vector operation counts to diagnose slow kNN searches.
- [`dense_vector` field type](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/4300/reference/elasticsearch/mapping-reference/dense-vector): API reference for vector field mapping, including `index`, `similarity`, `index_options`, and quantization parameters.
- [`knn` query](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/4300/reference/query-languages/query-dsl/query-dsl-knn-query): API reference for the `knn` query, including parameters, `query_vector_builder` options, and usage with `dense_vector` and `semantic_text` fields.