Skip to content
Tutorials Center
My learning

Topics

Lesson 26 of 43 ยท Beyond Keywords

Vector and Semantic Search

Learn vector and semantic search in Elasticsearch: dense_vector, kNN, HNSW, similarity metrics, hybrid search with RRF and semantic_text, plus Python stand-ins.

Keyword search matches words. A shopper who types "puppy food" will not find a page that only says "dog treats", because the two share no term. Vector search tackles this gap by comparing meaning instead of spelling. An embedding model turns a piece of text (or an image, or a song) into a list of numbers, a vector, in such a way that similar meanings end up close together. Search then becomes "find the stored vectors nearest to the query's vector".

Elasticsearch stores vectors in a dense_vector field and finds neighbors with a kNN search ("k nearest neighbors"). You can combine it with ordinary full-text queries, which is called hybrid search, and recent versions can even create the embeddings for you. The real cluster cannot run here, so the requests are read-only. The Python stand-ins use tiny hand-made vectors so you can see the math, but they are toys, not a real embedding model.

From words to vectors

Text puppy food
Embedding model Maps meaning to numbers.
Vector A point in space, often 384 to 1,536 numbers.
Nearest neighbors Close points mean similar meaning.
1 / 2

Storing vectors

You declare the field and its size, and your application (or an ingest pipeline) fills it in.

JSON
PUT /articles
{
  "mappings": {
    "properties": {
      "title":     { "type": "text" },
      "title_vec": {
        "type": "dense_vector",
        "dims": 384,
        "index": true,
        "similarity": "cosine"
      }
    }
  }
}

dims must match the output size of your embedding model (the model decides it, for example 384 or 768), and every vector in the field has that length. With "index": true Elasticsearch builds an approximate nearest-neighbor structure so queries are fast. The similarity setting says how "closeness" is measured.

Similarity metrics

  • cosine looks at the angle between two vectors and ignores their length. It is the usual choice for text embeddings.
  • dot_product multiplies matching positions and adds them up. It is fast, but Elasticsearch expects unit-length vectors for it, and for those it gives the same ranking as cosine.
  • l2_norm is the straight-line (Euclidean) distance. Smaller is closer, and Elasticsearch converts it to a score as 1 / (1 + distanceยฒ).
  • max_inner_product is the dot product without the unit-length requirement, for models trained with it.

For cosine, the score Elasticsearch reports is (1 + cosine) / 2, which keeps scores positive (between 0 and 1). Always use the metric your embedding model was trained for.

Python Similarity metrics by hand

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Notice that the unit vectors have identical dot product and cosine. That is why dot_product is a faster stand-in for cosine when your vectors are already normalized.

A kNN search asks for the k vectors closest to a query vector.

JSON
GET /articles/_search
{
  "knn": {
    "field": "title_vec",
    "query_vector": [0.12, -0.03, 0.57],
    "k": 5,
    "num_candidates": 100,
    "filter": { "term": { "language": "en" } }
  },
  "_source": ["title"]
}

(The query vector is shortened here for display: a real one has all dims numbers.) Your application gets query_vector by running the same embedding model on the user's query text. num_candidates is how many nearest candidates each shard collects before the final k are chosen: higher is more accurate and slower. The filter is applied during the search, so you still get k results that satisfy it, unlike filtering the results afterwards.

HNSW in one paragraph

Comparing a query with every stored vector is exact but slow when you have millions. Elasticsearch's indexed vectors use HNSW (Hierarchical Navigable Small World), a graph where each vector is linked to some near neighbors, with sparse "express" layers on top. A search starts at the top, hops greedily to ever closer points, and descends. It examines a tiny fraction of the vectors, so it is approximate: occasionally a true neighbor is missed. Settings such as m (links per node) and ef_construction (build effort) trade index time and memory for accuracy, and quantized variants shrink memory by storing compressed vectors. Vectors take real RAM, so sizing matters (see Shards, Replicas and Clusters).

To see why meaning-based search finds things keywords cannot, here is a miniature. Each word gets a hand-made vector over four invented "topics" (animals, vehicles, food, computers), a document is the normalized sum of its word vectors, and search is cosine similarity. A real embedding model learns thousands of such directions from data; here we write them down.

Python Keyword search vs a toy vector search

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

For "puppy" the keyword search returns nothing, because no document contains that word. The vector search puts document 1 (dog cat) first, then document 5 (car dog), since they point in the "animals" direction. That is semantic search in a nutshell. The flip side is also visible: the vector search always returns something, even when nothing is a good match, so real systems use a minimum similarity (similarity parameter in the knn section) or a score cutoff.

Hybrid search with RRF

Vectors are great at meaning and poor at exact things: product codes, names, rare words, error numbers. BM25 is the opposite. Hybrid search runs both and merges the two ranked lists. The scores are not comparable (BM25 scores are unbounded, cosine scores sit between 0 and 1), so Elasticsearch uses Reciprocal Rank Fusion (RRF), which ignores scores and uses only ranks:

rrf_score(doc) = sum over lists of 1 / (rank_constant + rank)

with a rank_constant that defaults to 60. A document that appears near the top of both lists beats one that is first in just one.

JSON
GET /articles/_search
{
  "retriever": {
    "rrf": {
      "retrievers": [
        { "standard": { "query": { "match": { "title": "puppy food" } } } },
        { "knn": { "field": "title_vec", "query_vector": [0.12, -0.03, 0.57], "k": 20, "num_candidates": 100 } }
      ],
      "rank_window_size": 50,
      "rank_constant": 60
    }
  }
}
Python Reciprocal rank fusion

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Documents A and C appear in both lists, so they take the top two spots. They tie at 0.03227, because "first in one list and third in the other" scores the same either way (the stand-in breaks the tie by name). Documents seen in only one list follow, each worth about half of that.

semantic_text: let Elasticsearch handle the embeddings

Running your own embedding pipeline is work. The semantic_text field type moves it into the cluster: you point the field at an inference endpoint (a configured embedding model, either hosted by Elastic or by another provider), and Elasticsearch embeds text at index time and your query text at search time.

JSON
PUT /faq
{ "mappings": { "properties": {
    "answer": { "type": "semantic_text" }
} } }

GET /faq/_search
{ "query": { "semantic": { "field": "answer", "query": "how do I reset my password?" } } }

Which endpoint and model are used by default depends on your version and deployment, so check the documentation for yours. The trade-offs are the same as before: embedding costs time and money per document, the model decides quality, and changing the model means re-embedding everything.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does a dense_vector field's dims setting have to match?

    Every stored and query vector must have exactly dims numbers, and that length is determined by the embedding model you use.
  2. 2. Why is HNSW search called approximate?

    HNSW trades a little accuracy for a large speedup by hopping through a graph instead of comparing with every vector. Raising num_candidates improves recall.
  3. 3. Why does hybrid search use Reciprocal Rank Fusion instead of adding scores?

    BM25 scores are unbounded while cosine-based scores sit between 0 and 1. RRF uses 1 / (rank_constant + rank) per list and sidesteps the scale problem.
  4. 4. A user searches "puppy" and your keyword index has only documents about "dog". What helps most?

    The words share no term, so BM25 finds nothing. Embeddings place "puppy" near "dog", so a vector retriever can match them.

Summary

  • Embeddings turn text into vectors; similar meaning means nearby vectors.
  • dense_vector stores them (dims, similarity), and the knn search finds the nearest ones using an approximate HNSW graph.
  • Use the similarity metric your model was trained for: cosine for most text models, dot_product for unit-length vectors.
  • Hybrid search merges BM25 and kNN results with RRF, which works on ranks, not scores.
  • semantic_text lets Elasticsearch create embeddings through an inference endpoint; check your version's defaults.

Next: Geo Queries and Time-Series Data.