1. Why vectors? #
Searching meaning, not words.
Principle #
A lexical search (BM25) does not find "broken product" in a document about a "damaged parcel". An embedding model turns text into a vector of a few hundred numbers, so that texts with close meaning give close vectors. Searching then means finding the nearest neighbours (k-NN) of the query vector.
Good to know : Requests are written in the OpenSearch Dashboards Dev Tools console format (GET _cluster/health). On the command line, the same request iscurl -sk -u 'admin:Str0ng!Passw0rd-2026' https://localhost:9200/_cluster/health, with-H 'Content-Type: application/json' -d '…'when there is a body.
2. The k-NN plugin #
Storing and searching vectors.
A vector index #
PUT avis
{
"settings": {"index.knn": true},
"mappings": {
"properties": {
"texte": {"type": "text"},
"note": {"type": "integer"},
"vecteur": {
"type": "knn_vector",
"dimension": 3,
"space_type": "cosinesimil",
"method": {"name": "hnsw", "engine": "faiss", "parameters": {"m": 16, "ef_construction": 128}}
}
}
}
}
POST avis/_doc
{"texte": "colis abîmé à la livraison", "note": 1, "vecteur": [0.9, 0.1, 0.0]}
GET avis/_search
{
"size": 3,
"query": {
"knn": {
"vecteur": {
"vector": [0.85, 0.15, 0.05],
"k": 3,
"filter": {"range": {"note": {"lte": 2}}}
}
}
}
}The dimension must exactly match the model (384 for all-MiniLM-L6-v2, 768 for many BERT models). The example's 3 dimensions only serve to understand the mechanics.
Engines and methods #
| Parameter | Effect |
|---|---|
| m | links per HNSW graph node: more = better recall, more memory |
| ef_construction | graph quality at build time: more = slower indexing |
| ef_search | search effort: more = better recall, slower |
| space_type | l2 (Euclidean distance), cosinesimil, innerproduct: the model's one |
| quantization | compress vectors (fp16, bytes, binary) to cut memory |
Watch out : faiss HNSW graphs live in native memory, outside the JVM heap. Plan about 1.1 × (4 × dimension + 8 × m) bytes per vector: 10 million 768-dimension vectors already need over 35 GB.
3. Semantic search with ML Commons #
The cluster computes embeddings.
Deploying a model #
PUT _cluster/settings
{"persistent": {"plugins.ml_commons.only_run_on_ml_node": false, "plugins.ml_commons.native_memory_threshold": 99}}
POST _plugins/_ml/models/_register?deploy=true
{
"name": "huggingface/sentence-transformers/all-MiniLM-L6-v2",
"version": "1.0.2",
"model_format": "TORCH_SCRIPT"
}
GET _plugins/_ml/tasks/<task_id>Good to know : The list of pretrained models and their exact versions is in the ML Commons documentation: check it, as available versions change. In production, run models on dedicated ml nodes, or call an external model (Bedrock, OpenAI, Cohere…) through a connector.Ingestion and neural query #
PUT _ingest/pipeline/embedding
{"processors": [{"text_embedding": {"model_id": "<model_id>", "field_map": {"texte": "vecteur"}}}]}
PUT avis-semantique
{
"settings": {"index.knn": true, "default_pipeline": "embedding"},
"mappings": {"properties": {
"texte": {"type": "text"},
"vecteur": {"type": "knn_vector", "dimension": 384, "space_type": "cosinesimil", "method": {"name": "hnsw", "engine": "faiss"}}
}}
}
GET avis-semantique/_search
{"query": {"neural": {"vecteur": {"query_text": "produit cassé", "model_id": "<model_id>", "k": 5}}}}The default pipeline computes the vector on each indexing; the neural query computes the searched text's vector with the same model.
4. Hybrid search #
The best of both worlds.
Principle #
Lexical excels at exact words (references, proper names), vector at meaning. Their scores do not share a scale: a search pipeline normalizes, then combines them.
PUT _search/pipeline/hybride
{
"phase_results_processors": [{
"normalization-processor": {
"normalization": {"technique": "min_max"},
"combination": {"technique": "arithmetic_mean", "parameters": {"weights": [0.4, 0.6]}}
}
}]
}
GET avis-semantique/_search?search_pipeline=hybride
{
"query": {
"hybrid": {
"queries": [
{"match": {"texte": "produit cassé"}},
{"neural": {"vecteur": {"query_text": "produit cassé", "model_id": "<model_id>", "k": 20}}}
]
}
}
}The weights give 40% to lexical and 60% to vector. The score-ranker-processor also offers rank fusion (RRF), which does not depend on score scales.
RAG and agents #
For RAG (retrieval-augmented generation), OpenSearch retrieves relevant passages through hybrid search, then a response processor or an ML Commons agent passes them to an LLM through a connector. The Flow Framework automates building the whole chain (model, pipelines, index) in a single workflow template.
Best practice : Measure before choosing: build 50 real queries with expected good results, then compare lexical, vector and hybrid. Hybrid often wins, but not always.
Commands to know #
Commands to know
GET _plugins/_knn/stats: k-NN plugin stats and memoryPOST _plugins/_ml/models/_register?deploy=true: register and deploy a modelGET _plugins/_ml/models/<id>: model statusPUT _search/pipeline/<nom>: search pipeline (normalization)GET <index>/_search?search_pipeline=<nom>: search with a pipeline
Sources #
Checked in November 2026 (OpenSearch 3.x, Data Prepper 2.x): OpenSearch ships a minor release about every six weeks, check the release notes before relying on a detail.
