Vector search

What it is

Elasticsearch ships dense vector storage, exact and approximate k-NN search, and an HNSW graph index from Lucene. Vectors power semantic search (via semantic_text or external embeddings), similarity search over images and audio, and hybrid retrieval combined with BM25 or filters.

Source layout

server/src/main/java/org/elasticsearch/index/codec/vectors/   Custom Lucene vector codecs (BBQ, BFloat, IVF)
server/src/main/java/org/elasticsearch/index/mapper/vectors/  DenseVectorFieldMapper, SparseVector
server/src/main/java/org/elasticsearch/search/vectors/        VectorSimilarityFunction, KnnVectorQueryBuilder
libs/simdvec/                                                 SIMD dot product / Manhattan / Hamming
libs/gpu-codec/                                               Optional GPU vector codec
x-pack/plugin/diskbbq/                                        Disk-backed BBQ vector format
x-pack/plugin/rank-vectors/                                   Vector ranker
x-pack/plugin/inference/                                      Bridges to embedding model providers

Field types

Field type	Backing	Notes
dense_vector	Lucene HNSW + custom codec	Float, byte, bit, BBQ, BFloat formats
sparse_vector	Inverted index of dimension -> weight	Used by ELSER and learned-sparse-retrieval
semantic_text	Auto-managed dense or sparse vectors	Auto-chunks text; stores both source and embedding

DenseVectorFieldMapper (server/src/main/java/org/elasticsearch/index/mapper/vectors/DenseVectorFieldMapper.java) handles the common configuration knobs: dims, similarity (cosine, dot_product, l2_norm, max_inner_product), index_options (HNSW / flat / IVF / BBQ).

Querying

GET /<index>/_search
{
  "knn": {
    "field": "embedding",
    "query_vector": [...],
    "k": 10,
    "num_candidates": 100,
    "filter": {...}
  }
}

KnnVectorQueryBuilder rewrites to a Lucene KnnFloatVectorQuery (or byte/bit variant), which uses HNSW to find approximate neighbors. The filter is applied during graph traversal so that filtered candidates are not pruned prematurely.

For exact (brute force) search, use script_score with cosineSimilarity / dotProduct / etc. — slower but deterministic.

SIMD acceleration

libs/simdvec/ provides SIMD-accelerated kernels for:

• cosine, dot_product, l2_norm, max_inner_product over float[] and byte[].
• Hamming distance over bit vectors.

Two implementations:

• Java Vector API path (preferred on JDK 21+): the JIT auto-vectorizes the kernels via the incubator vector API.
• Native path: precompiled binaries published from libs/simdvec/native/publish_vec_binaries.sh for AVX2/AVX-512 / NEON. JNI-loaded.

The SIMD path is the busiest single performance lever — publish_vec_binaries.sh is one of the most-edited files in the repo because the kernel set keeps growing.

BBQ (Better Binary Quantization)

x-pack/plugin/diskbbq/ and the BBQ codec in index/codec/vectors implement a quantization scheme that compresses each vector to a fraction of its original size while preserving recall. It is the default for high-dimensional embeddings in 9.x.

Hybrid search via RRF

The standard recipe for hybrid lexical + semantic search is Reciprocal Rank Fusion (x-pack/plugin/rank-rrf/). It combines top-N lists from a bm25 retriever and a knn retriever without requiring the user to pick weights.

Semantic text

semantic_text (server/.../mapper/vectors/SemanticTextFieldMapper.java plus pieces in x-pack/plugin/inference/) handles the boring parts of semantic search: chunk the text on ingest, run an inference model to embed it, store both the source and the embedding(s), and at query time route a semantic query to the right field type. This is the "no-config" frontend for semantic retrieval.

ESQL vector functions

ES|QL exposes KNN, MATCH, and similarity functions that route to the same low-level kernels. See ESQL.

Where to extend

• New vector codec: extend Lucene's KnnVectorsFormat and register through MapperPlugin#getKnnVectorsFormat-style hooks.
• New similarity: add to VectorSimilarityFunction and the SIMD kernels.
• New retriever combining vector + lexical: extend Retriever and register via SearchPlugin#getRetrievers.
• Native acceleration: build into libs/simdvec/native/ and update publish_vec_binaries.sh.