Skip to main content

Build hybrid search with filters and reranking

TL;DR

Hybrid search combines semantic retrieval with sparse keyword matching, metadata filters, and optional reranking. Use it when users need natural-language matches plus exact terms, IDs, names, tenant or region constraints, source filters, and a final relevance pass over the top 10 or more candidate results.

Pure vector search can miss exact terms, IDs, names, and rare phrases. Keyword search can miss semantic matches. Hybrid search combines both, then reranking improves final ordering.

What you will build​

Answer

You will build a search flow that sends 1 natural-language query, optional sparse terms, metadata filters, and a reranking flag to VectorAmp. The pattern keeps exact constraints explicit while still letting semantic retrieval find results that do not use the same wording as the user.

Prerequisites​

  • A dataset with indexed text.
  • Metadata fields for filtering.
  • Node.js or Python SDK, or the VectorAmp CLI.

CLI example​

Install the CLI with npm:

npm install -g @vectoramp/cli

Run hybrid filtered search:

vectoramp --dataset ds_123 datasets search "refund exception for enterprise plan" \
  --hybrid \
  --sparse "refund enterprise" \
  --alpha 0.6 \
  --filter source=policy \
  --filter region=us \
  --rerank \
  --top-k 10

TypeScript example​

npm install @vectoramp/vectoramp
import { VectorAmp } from '@vectoramp/vectoramp';

const client = new VectorAmp({ apiKey: process.env.VECTORAMP_API_KEY });
const dataset = await client.datasets.get('ds_123');

const results = await dataset.search({
  queryText: 'refund exception for enterprise plan',
  topK: 10,
  includeMetadata: true,
  filter: { source: 'policy', region: 'us' },
  hybrid: true,
  sparseQuery: 'refund enterprise',
  alpha: 0.6,
  rerank: true
});

console.log(results.results);

Python example​

pip install vectoramp
from vectoramp import VectorAmp

client = VectorAmp(api_key="vsk_...")
dataset = client.datasets.get("ds_123")

results = dataset.search(
    text="refund exception for enterprise plan",
    top_k=10,
    filters={"source": "policy", "region": "us"},
    hybrid=True,
    sparse_query="refund enterprise",
    alpha=0.6,
)

When to use each option​

OptionUse when
Semantic searchusers ask natural-language questions
Sparse queryexact terms, IDs, names, or rare words matter
Metadata filtervisibility, tenant, region, status, or source must be constrained
Rerankingtop results are close and ordering quality matters

Validation checklist​

  • Exact keywords appear in the result set.
  • Semantic matches still appear when wording differs.
  • Filters exclude out-of-scope documents.
  • Reranking improves ordering without hiding required results.