Loading

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 low latency matters more than perfect recall. This page covers approximate kNN search methods, running a basic approximate kNN search, indexing considerations, and limitations.

Tip

If you use semantic_text fields, query them with a match query for the simplest approach, or use the knn query when you need more control over the search.

Warning

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 for configuration tips.

Elasticsearch provides three ways to run approximate kNN search, with different field type support:

Method Supported field types Use case
Top-level knn option dense_vector Standalone kNN search or hybrid search with score fusion
knn query dense_vector, semantic_text Composable with other queries in a bool clause. Required for semantic_text fields
knn retriever dense_vector Use within a retriever pipeline for ranking and result merging

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 requires the following mapping options:

    • A similarity value. This value determines the similarity metric used to score documents based on similarity between the query and document vector. For a list of available metrics, see the similarity parameter documentation. The similarity setting defaults to cosine.
    				PUT image-index
					{
  "mappings": {
    "properties": {
      "image-vector": {
        "type": "dense_vector",
        "dims": 3,
        "similarity": "l2_norm"
      },
      "title-vector": {
        "type": "dense_vector",
        "dims": 5,
        "similarity": "l2_norm"
      },
      "title": {
        "type": "text"
      },
      "file-type": {
        "type": "keyword"
      }
    }
  }
}

  2. Index your data with embeddings.

    				POST image-index/_bulk?refresh=true
					{ "index": { "_id": "1" } }
{ "image-vector": [1, 5, -20], "title-vector": [12, 50, -10, 0, 1], "title": "moose family", "file-type": "jpg" }
{ "index": { "_id": "2" } }
{ "image-vector": [42, 8, -15], "title-vector": [25, 1, 4, -12, 2], "title": "alpine lake", "file-type": "png" }
{ "index": { "_id": "3" } }
{ "image-vector": [15, 11, 23], "title-vector": [1, 5, 25, 50, 20], "title": "full moon", "file-type": "jpg" }
...

  3. Query using the knn option or a knn query.

    				POST image-index/_search
					{
  "knn": {
    "field": "image-vector",
    "query_vector": [-5, 9, -12],
    "k": 10,
    "num_candidates": 100
  },
  "fields": [ "title", "file-type" ]
}

The document _score is a positive 32-bit floating-point number that ranks result relevance. In Elasticsearch kNN search, _score is derived from the chosen vector similarity metric between the query and document vectors. Refer to similarity for details on how kNN scores are computed.

Note

Support for approximate kNN search was added in version 8.0. Before 8.0, dense_vector fields did not support enabling index in the mapping. If you created an index before 8.0 with dense_vector fields, reindex using a new mapping with index: true (which is the default value) to use approximate kNN.

For approximate kNN, Elasticsearch stores dense vector values per segment as an HNSW graph or per segment as clusters using DiskBBQ. Building these approximate kNN structures is compute-intensive, which means indexing vectors can be time-consuming. As a result, you might need to increase client request timeouts for index and bulk operations. The approximate kNN tuning guide covers indexing performance, sizing, and configuration trade-offs that affect search performance.

In addition to search-time parameters, HNSW and DiskBBQ expose index-time settings that balance graph build cost, search speed, and accuracy. When defining your dense_vector mapping, use index_options to set these parameters:

Tip

When using the semantic_text field type with dense vector embeddings, you can also configure index_options directly on the field. Refer to Optimizing vector storage with index_options for examples.

				PUT image-index
					{
  "mappings": {
    "properties": {
      "image-vector": {
        "type": "dense_vector",
        "dims": 3,
        "similarity": "l2_norm",
        "index_options": {
          "type": "hnsw",
          "m": 32,
          "ef_construction": 100
        }
      }
    }
  }
}
  • When using kNN search in cross-cluster search, the ccs_minimize_roundtrips option is not supported.
  • Elasticsearch uses the HNSW algorithm for efficient kNN. Like most approximate methods, HNSW trades perfect accuracy for speed, so results aren’t always the true k closest neighbors.
Note

Approximate kNN always uses the dfs_query_then_fetch search type to gather the global top k matches across shards. You can’t set search_type explicitly for kNN search.

  • kNN search on Elasticsearch: Explore common use cases, prerequisites for kNN search, and a comparison of approximate and exact kNN methods.
  • Build search queries: Learn how to construct approximate kNN queries for filtering, hybrid retrieval, semantic search, multiple vector fields, and similarity thresholds.
  • Nested kNN search: Learn how to run approximate kNN search on nested vectors for passage retrieval, filtering, inner hits, and chunked content.
  • Optimize performance and accuracy: Learn how to tune search speed, recall, vector storage, quantization, and rescoring for approximate kNN search.
  • Exact kNN search: Learn how to run exact brute-force kNN search with script_score queries for small datasets or precise scoring.
  • Vector search in Elasticsearch: Learn the core concepts and terminology for vector search in Elasticsearch, including embeddings, field types, and how vector retrieval fits with other search strategies.
  • Knn query: API reference for the knn query, including parameters, query_vector_builder options, and usage with dense_vector and semantic_text fields.