OpenParable
Skip to content
← Back to skills

Vector Hybrid Search

Development
vector-hybrid-search

Vector Hybrid Search is an Agent Skill for development published in the elastic/kibana repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Guide for building vector search, hybrid search, and using Elasticsearch as a vector database. Covers semantic_text, dense_vector, embedding strategies, hybrid BM25+kNN via RRF, reranking, and production optimization. Use when a developer wants semantic search, hybrid search, kNN, embeddings, or Elasticsearch as a vector store.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/elastic/kibana/blob/HEAD/src/platform/packages/shared/kbn-search-agent/.elasticsearch-agent/skills/recipes/vector-hybrid-search/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/vector-hybrid-search, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Vector & Hybrid Search Guide

Covers the full lifecycle of vector or hybrid search with Elasticsearch — planning, data modeling, search implementation, and optimization. All API examples use SENSE syntax for Kibana Dev Tools.

Conversation flow — return to onboarding

This skill provides deep implementation detail for vector and hybrid search. It is not the main conversation driver.

After applying the guidance here, re-read /elasticsearch-onboarding to resume the structured onboarding playbook (Steps 1–7: intent → data → mapping → build → test → iterate). That playbook controls sequencing, the one-question-at-a-time rule, and the Dev Tools API-snippet workflow. If /elasticsearch-onboarding has not been loaded yet in this conversation, load it now — it is the primary conversation flow for all Elasticsearch search onboarding.

Decision: Embedding Strategy

Ask these routing questions first:

  1. "Are you already generating embeddings?" → Yes → dense_vector path. Briefly offer semantic_text as a simpler alternative.
  2. "What version of Elasticsearch?" → Below 8.15 → semantic_text unavailable, use dense_vector.
OptionWhen to Use
Built-in via EISDefault for Cloud (Serverless or ECH) on 8.15+. No ML node cost. Jina v3 is the current default dense model for semantic_text.
Third-party (OpenAI, Cohere)Existing model contract or specific model requirement.
Self-hostedCustom fine-tuned models deployed on ML nodes.

Decision: Vector Field Type

OptionField TypeWhen to Use
semantic_textsemantic_text8.15+, no existing vectors. Default recommendation — auto chunking, auto embedding.
dense_vectordense_vectorBringing your own vectors, need dims/similarity control, or pre-8.15.

semantic_text Mapping (Default)

Minimal — works out of the box on Serverless (uses the platform default model, currently Jina):

PUT /my-index
{
  "mappings": {
    "properties": {
      "content": { "type": "semantic_text" },
      "title": { "type": "text" },
      "category": { "type": "keyword" }
    }
  }
}

With a specific inference endpoint:

PUT /my-index
{
  "mappings": {
    "properties": {
      "content": {
        "type": "semantic_text",
        "inference_id": "my-inference-endpoint"
      }
    }
  }
}

dense_vector Mapping

PUT /my-index
{
  "mappings": {
    "properties": {
      "content": { "type": "text" },
      "content_embedding": {
        "type": "dense_vector",
        "dims": 1536,
        "index": true,
        "similarity": "cosine"
      },
      "category": { "type": "keyword" }
    }
  }
}

Set dims to match the embedding model output (OpenAI text-embedding-3-small = 1536, Jina v3 = 1024, E5-small = 384).

Before generating inference endpoint config, check EIS docs for current model IDs. Jina v3 is the current default dense model for semantic_text; Jina v5-small is available for cost-sensitive workloads. Model IDs change regularly.

Decision: Search Type

OptionWhen to Use
Pure kNNAll queries are semantic/meaning-based, no exact term matching needed.
Hybrid (BM25 + kNN via RRF)Users search with both keywords AND natural language. Default recommendation.
Semantic via semantic_textUsing semantic_text field — simplest semantic search.

Semantic Search (semantic_text)

POST /my-index/_search
{
  "retriever": {
    "standard": {
      "query": {
        "semantic": {
          "field": "content",
          "query": "how do I configure index mappings"
        }
      }
    }
  }
}

Pure kNN (dense_vector)

POST /my-index/_search
{
  "retriever": {
    "knn": {
      "field": "content_embedding",
      "query_vector": [0.1, 0.2, 0.3],
      "k": 10,
      "num_candidates": 100
    }
  }
}

Hybrid Search with RRF

POST /my-index/_search
{
  "retriever": {
    "rrf": {
      "retrievers": [
        {
          "standard": {
            "query": {
              "multi_match": {
                "query": "elasticsearch index mapping",
                "fields": ["title^2", "content"]
              }
            }
          }
        },
        {
          "knn": {
            "field": "content_embedding",
            "query_vector": [0.1, 0.2, 0.3],
            "k": 50,
            "num_candidates": 100
          }
        }
      ],
      "window_size": 100,
      "rank_constant": 60
    }
  }
}

Add filter clauses to both retrievers for filtered hybrid search.

Reranking

Start without reranking. Add text_similarity_reranker if relevance isn't good enough after tuning:

POST /my-index/_search
{
  "retriever": {
    "text_similarity_reranker": {
      "retriever": { "rrf": { "retrievers": [ ... ] } },
      "field": "content",
      "inference_id": "my-reranker-endpoint",
      "inference_text": "your query",
      "rank_window_size": 50
    }
  }
}

EIS provides managed rerankers (currently Jina Reranker v2 and v3). Check reranker docs for current setup.

Production Optimization

Quantization — reduces vector memory footprint:

TypeMemory ReductionRecall Impact
hnswBaselineBaseline
int8_hnsw~4xMinimal
int4_hnsw~8xSmall
bbq_hnsw~32xModerate

Shard sizing — target 10-50 GB per shard, max 200M docs per shard.

Common Follow-ups

QuestionAnswer
"Results aren't relevant"Tune window_size and rank_constant in RRF. Run _rank_eval with test queries.
"Memory is too high"Add int8_hnsw quantization to dense_vector mapping and reindex.
"How do I weight keyword vs semantic?"Adjust RRF window_size — higher favors semantic, lower favors BM25.