Elasticsearch kNN Search for Enterprise Retrieval and Semantic Search
Prerequisites
- Working knowledge of Elasticsearch clusters and index mappings
- Basic familiarity with embeddings and vector search concepts
Steps
Elasticsearch kNN search enables low-latency vector similarity retrieval for semantic search, recommendation, and RAG workloads on enterprise data. This guide explains architecture, implementation, security hardening, and operational trade-offs for production deployments.
Overview
Elasticsearch kNN search provides approximate nearest neighbor retrieval over dense vector embeddings stored in Elasticsearch indices. Enterprises use it to power semantic search, document discovery, fraud analytics, recommendation engines, and retrieval-augmented generation where keyword-only search is insufficient.
Core value comes from combining vector search with traditional Elasticsearch capabilities such as BM25, filters, aggregations, role-based access control, snapshots, and cross-cluster operations. In practice, teams often deploy hybrid retrieval, where lexical relevance and vector similarity are blended to improve precision and recall while preserving governance and operational consistency.
Architecture
A production kNN deployment typically includes ingest pipelines, embedding generation services, Elasticsearch data nodes, and client applications. Vectors are indexed into dense_vector fields and searched using kNN queries, often with metadata filters for tenant, geography, or classification.
View as text
[Client App] ---- 1. query text ----> [Embedding Service] [Embedding Service] ---- 2. query vector ----> [Elasticsearch Coordinating Node] [Coordinating Node] ---- 3. knn + filter ----> [Hot Data Nodes] [Hot Data Nodes] ---- 4. top-k candidates ----> [Coordinating Node] [Coordinating Node] ---- 5. ranked hits ----> [Client App] [Source Systems] ---- 6. documents ----> [Ingest Pipeline] [Ingest Pipeline] ---- 7. embeddings + metadata ----> [Elasticsearch Index]
Core components
- Embedding service: OpenAI, Azure OpenAI, Hugging Face, or internal model serving.
- Elasticsearch cluster: Coordinating, master, ingest, and data nodes.
- Index mapping:
dense_vectorplus structured fields for filtering. - Storage tiers: Hot nodes for active vector indices, warm for historical metadata.
Deployment models
- Elastic Cloud for managed operations and faster rollout.
- Self-managed on Kubernetes or VMs for strict residency and custom networking.
- Hybrid, with embeddings generated in cloud but indexed on-prem.
Implementation Guide
- Create an index with a vector field and metadata.
curl -u elastic:$ES_PWD --cacert /etc/elasticsearch/certs/http_ca.crt -X PUT https://es-prod-01:9200/docs-knn -H 'Content-Type: application/json' -d '{"settings":{"index":{"number_of_shards":3,"number_of_replicas":1}},"mappings":{"properties":{"title":{"type":"text"},"content":{"type":"text"},"tenant_id":{"type":"keyword"},"classification":{"type":"keyword"},"embedding":{"type":"dense_vector","dims":384,"index":true,"similarity":"cosine"}}}}'
- Load documents with embeddings.
curl -u elastic:$ES_PWD --cacert /etc/elasticsearch/certs/http_ca.crt -X POST https://es-prod-01:9200/docs-knn/_bulk -H 'Content-Type: application/x-ndjson' --data-binary @bulk.ndjson
- Run a filtered kNN query.
curl -u elastic:$ES_PWD --cacert /etc/elasticsearch/certs/http_ca.crt -X POST https://es-prod-01:9200/docs-knn/_search -H 'Content-Type: application/json' -d '{"knn":{"field":"embedding","query_vector":[0.12,0.98,0.44],"k":10,"num_candidates":100,"filter":{"term":{"tenant_id":"acme-prod"}}},"_source":["title","classification"]}'
- Tune
kandnum_candidates. Highernum_candidatesimproves recall but increases latency and memory pressure. - Use index lifecycle management, snapshots, and shard sizing to keep vector workloads stable.
Elasticsearch configuration
cluster.name: es-knn-prod
node.roles: [ data_hot, ingest, master ]
xpack.security.enabled: true
xpack.security.http.ssl.enabled: true
xpack.security.transport.ssl.enabled: true
search.max_buckets: 20000
thread_pool.search.queue_size: 2000
Code Examples
1. Index mapping
{
"mappings": {
"properties": {
"title": { "type": "text" },
"tenant_id": { "type": "keyword" },
"embedding": { "type": "dense_vector", "dims": 384, "index": true, "similarity": "cosine" }
}
}
}
2. Python query client
from elasticsearch import Elasticsearch
es = Elasticsearch("https://es-prod-01:9200", basic_auth=("svc_search", "REDACTED"), ca_certs="/etc/ssl/http_ca.crt")
query_vector = [0.12, 0.98, 0.44]
resp = es.search(index="docs-knn", knn={"field":"embedding","query_vector":query_vector,"k":5,"num_candidates":50,"filter":{"term":{"classification":"internal"}}})
for hit in resp["hits"]["hits"]:
print(hit["_score"], hit["_source"])
3. Elastic Cloud with Terraform
resource "ec_deployment" "search" {
name = "es-knn-prod"
region = "aws-eu-west-1"
version = "8.13.4"
deployment_template_id = "aws-general-purpose-v3"
elasticsearch {}
kibana {}
}
Security Hardening
- Enable TLS for HTTP and transport layers with enterprise PKI.
- Use service accounts or API keys instead of shared superuser credentials.
- Restrict index access with role-based privileges and document-level security where required.
- Isolate ingest and search traffic using private networking, security groups, and mTLS between services.
- Encrypt snapshots and validate retention policies for regulated data.
- Apply field-level controls to prevent vector leakage where embeddings may encode sensitive semantics.
Comparison
| Feature | Elasticsearch kNN Search | OpenSearch Vector Search | Pinecone |
|---|---|---|---|
| Pricing | Elastic consumption or subscription | Open-source plus infra or managed service costs | Usage-based managed pricing |
| Deployment | Cloud, self-managed, Kubernetes, hybrid | Self-managed, AWS managed options | Fully managed SaaS |
| Scalability | Strong horizontal scaling with full-text and analytics | Good scaling, similar OSS operational model | High managed elasticity for vector-native workloads |
| Security | RBAC, TLS, API keys, snapshots, DLS/FLS in enterprise tiers | IAM/TLS/security plugins depending on deployment | Managed auth, network controls, less native SIEM-style integration |
Troubleshooting
Error 1: Wrong vector dimensions
Log sample:
{"type":"server","timestamp":"2026-03-11T10:14:22,991Z","level":"WARN","component":"o.e.i.e.Engine","cluster.name":"es-knn-prod","node.name":"data-1","message":"failed to index document","error.type":"illegal_argument_exception","error.message":"The [query_vector] has invalid dimension [3]. Expected [384]."}
Fix: Ensure embedding model output matches index dims; version embedding models explicitly.
Error 2: Circuit breaker during search
Log sample:
[2026-03-11T10:16:44,102][ERROR][o.e.x.m.c.c.ClusterStatsCollector] [data-2] org.elasticsearch.common.breaker.CircuitBreakingException: [parent] Data too large, data for [knn] would be [8.1gb], which is larger than the limit of [7.9gb]
Fix: Lower num_candidates, reduce shard fan-out, add heap, or rebalance hot shards.
Error 3: TLS trust failure
Log sample:
curl: (60) SSL certificate problem: unable to get local issuer certificate
Fix: Distribute the CA bundle to clients and verify SAN entries on node certificates.
Best Practices
- Do combine kNN with metadata filters, for example
tenant_idandclassification, to reduce candidate sets. - Do benchmark recall and latency with production embeddings before changing
kor shard counts. - Do use hybrid search for enterprise knowledge bases where exact terms still matter.
- Don't store unrestricted embeddings from sensitive content without reviewing privacy impact.
- Don't overshard vector indices; fewer, larger shards often perform better than many small shards.
- Don't mix embedding models in one field unless dimensions and semantics are identical.
Have a project in mind?
Get an instant AI price estimate for it, or talk directly to our team.
One email a month on what we learn building with AI