Vector search in Elasticsearch: best practices explained

Introduction

Semantic search has become the backbone of modern discovery systems. Vector search in Elasticsearch: best practices explained walks through the practical techniques that let your search engine understand meaning, not just keywords. By combining dense vectors with intelligent filtering and optimization, you can build search experiences that feel natural to users while keeping infrastructure costs reasonable.

Understanding dense_vector fields

The foundation of vector search in Elasticsearch is the dense_vector field type. Unlike keyword or text fields that store words or phrases, dense vectors store fixed-size arrays of floating-point numbers—typically embeddings from models like OpenAI's embedding API, Sentence Transformers, or your own fine-tuned models. Each dimension captures a semantic aspect of your content.

When defining a dense vector field, you specify the vector dimension (the size of each embedding) and the similarity metric. Here's a practical mapping setup:

{
  "mappings": {
    "properties": {
      "content": {
        "type": "text"
      },
      "embedding": {
        "type": "dense_vector",
        "dims": 768,
        "index": true,
        "similarity": "cosine"
      }
    }
  }
}

The dims parameter must match your embedding model's output size. Setting index to true enables approximate nearest neighbor (ANN) search via HNSW (Hierarchical Navigable Small World) algorithms, which is critical for performance on large datasets. The similarity metric—cosine, dot_product, or l2_norm—should match how your embedding model was trained.

In production e-commerce systems we've worked on, cosine similarity works reliably across product descriptions, user reviews, and catalog content. It's robust to vector magnitude variations and aligns with how most transformer-based models are optimized. Cosine also handles sparse embedding patterns well, which matters when your embedding model hasn't seen certain categories.

Executing kNN search queries

With your dense vectors indexed, kNN (k-nearest neighbors) search finds the most similar documents to a query vector. The query structure is straightforward but worth understanding deeply for production tuning.

{
  "knn": {
    "field": "embedding",
    "query_vector": [0.12, -0.05, 0.33, ...],
    "k": 10,
    "num_candidates": 100
  }
}

The k parameter specifies how many results you want—typically 10 to 50 for a search API. The num_candidates parameter, however, is where tuning happens. Elasticsearch's HNSW index doesn't examine every vector; it jumps through a graph structure. num_candidates controls how many candidates the algorithm explores before returning the top k. A ratio of num_candidates to k around 5–10x balances recall against query latency.

Here's a real scenario from a travel search platform we supported: users searched for flight experiences by semantically querying "mountain hiking in summer." Without tuning, with k=10 and num_candidates=20, the system returned results in 8ms but sometimes missed relevant trips. Increasing num_candidates to 200 improved recall to 95% (measured against full exhaustive search) while query time remained under 25ms. That trade-off was worth it.

You'll also need to generate the query vector. Embed the incoming search query using the same model you used for your documents:

POST /experiences/_search
{
  "knn": {
    "field": "embedding",
    "query_vector": [/* 768 dimensions from your embedding model */],
    "k": 10,
    "num_candidates": 200
  },
  "_source": ["title", "description", "price"]
}

A common pattern in production: cache embedding model outputs for popular queries, and batch-embed less frequent queries in background jobs to avoid embedding API latency during search.

Combining filters with vector search

Pure kNN search finds semantic neighbors, but real applications need business logic. A ride-hailing platform needs to combine vector similarity (finding semantically similar ride options or driver reviews) with permissions filters (only active drivers, correct region). That's where combining knn with a filter clause comes in.

POST /driver_profiles/_search
{
  "knn": {
    "field": "embedding",
    "query_vector": [0.15, -0.22, ...],
    "k": 10,
    "num_candidates": 200,
    "filter": {
      "bool": {
        "must": [
          { "term": { "status": "active" } },
          { "term": { "region": "us-west" } },
          { "range": { "rating": { "gte": 4.0 } } }
        ]
      }
    }
  }
}

This query finds the 10 most semantically similar driver profiles (say, based on review embeddings or service style vectors) within the active, correct region, with a minimum rating. Elasticsearch applies the filter during the HNSW graph traversal, which means it explores more candidates to find k results that satisfy the filter. Performance depends on filter selectivity: if 80% of drivers match your filters, kNN stays fast. If only 5% match, you may need to increase num_candidates significantly or pre-filter your index.

A CRM platform we worked with used this pattern for lead scoring: they embedded job descriptions and company profiles, then filtered by industry and company size. Queries stayed under 30ms even with strict filters because they tuned num_candidates to 500 and indexed only hot segments (recent leads) in the vector index.

Quantization for memory efficiency

Large-scale vector search is memory-hungry. A million documents with 768-dimensional float32 vectors consume roughly 3 GB of memory just for the vectors themselves. Quantization reduces vector precision to save memory without sacrificing search quality dramatically.

Elasticsearch supports int8 quantization, which stores vectors as 8-bit integers instead of 32-bit floats—a 4x memory reduction. The trade-off is minimal accuracy loss in most semantic tasks because embeddings are already fairly redundant across dimensions.

Enable quantization at index creation:

{
  "mappings": {
    "properties": {
      "embedding": {
        "type": "dense_vector",
        "dims": 768,
        "index": true,
        "similarity": "cosine",
        "index_options": {
          "type": "hnsw",
          "ef_construction": 400,
          "m": 16,
          "quantized_vector": {
            "type": "int8"
          }
        }
      }
    }
  }
}

When you index a document, Elasticsearch automatically quantizes the float vector to int8. The search still uses the original query vector (float), but the HNSW graph navigates int8 vectors internally, cutting memory use dramatically.

In a SaaS platform supporting multi-tenant semantic search, we tested quantization on 2 million product embeddings. Memory use dropped from 6.8 GB to 1.9 GB. Query latency increased by about 3–5% (from 22ms to 23.5ms), but recall against non-quantized search remained above 98%. For most use cases, that's a winning trade.

Note: quantization works best with cosine and dot_product similarity. It's less effective with l2_norm on very high-dimensional vectors because scaling assumptions break down.

Common mistakes

• Mismatched embedding dimensions. If your model outputs 384 dimensions but your mapping defines 768, indexing fails. Always verify your embedding source matches your schema.
• Under-tuned num_candidates. Setting num_candidates equal to k (e.g., both 10) trades recall for speed and often produces poor results. Aim for a 5–10x ratio in production.
• Embedding model drift. Re-indexing documents with a new embedding model requires re-embedding all content. Index both old and new embeddings during transition, or accept a temporary quality dip.
• Forgetting to re-embed query text. If you embed documents with model A but embed search queries with model B, results are unreliable. Use the same model end-to-end.
• Ignoring filter selectivity. Adding a filter that matches only 1% of your documents forces the algorithm to explore far more candidates. Profile filter impact and adjust num_candidates accordingly.
• Quantizing before tuning recall. Quantization introduces precision loss. Optimize your non-quantized setup first (tune num_candidates, evaluate recall), then apply quantization on top of a solid baseline.

Key takeaways

• Dense vectors store semantic meaning in fixed-size arrays; set dimension and similarity metric to match your embedding model.
• Enable the HNSW index with "index": true for approximate nearest neighbor search at scale.
• Tune num_candidates relative to k (typically 5–10x) to balance recall and latency; test recall against exhaustive search to find your sweet spot.
• Combine kNN with bool filters for business logic like permissions or categories; increase num_candidates if filters are selective.
• Use int8 quantization to reduce memory by 4x with minimal accuracy loss once your unquantized setup is tuned.
• Always use the same embedding model for both indexing and querying; embedding model changes require full re-indexing.
• Profile query latency and recall on realistic data volumes and filter patterns before going to production.