# Hybrid Search

> **TL;DR** — Combine semantic meaning with keyword precision. Best results when you know *some* of the words but not the exact phrasing.

Pure semantic search excels when you don't know the exact terminology. But sometimes you *do* know a keyword — a function name, an error code, a library name. Hybrid mode gives you both.

## How It Works

Hybrid search runs two searches in parallel and blends their scores:

1. **Semantic** — Model2Vec embeds your query and every code chunk, ranks by cosine similarity
2. **BM25** — built-in keyword matching with tf-idf scoring
3. **Fusion** — scores are combined with a configurable weight (default 70% semantic, 30% keyword)

## Usage

```bash
sgrep --hybrid "database connection pool" src/
```

## When to Use Hybrid

| Scenario | Mode | Why |
|----------|------|-----|
| Know the concept, not the code | Semantic (default) | No keywords to match |
| Know some keywords + concept | **Hybrid** | Keywords boost precision |
| Know exact string | Just use `grep`/`rg` | Exact match is faster |

## Tuning

The `--alpha` flag controls the balance:

```bash
# 70% semantic, 30% keyword (default)
sgrep --hybrid "error recovery" src/

# More keyword weight
sgrep --hybrid --alpha 0.4 "ConnectionPool" src/

# More semantic weight
sgrep --hybrid --alpha 0.9 "gracefully shut down" src/
```