> ## Documentation Index
> Fetch the complete documentation index at: https://vecgrep.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# hybrid_search

> Blend vector similarity and graph structure into a single ranked result

## Overview

Combines vector (semantic) search with graph-structural scoring into a single ranked result set. The final score is a weighted blend:

```
score = alpha * vector_score + (1 - alpha) * graph_score
```

If no graph index exists, `hybrid_search` degrades gracefully to pure vector search — identical to `search_code`.

## Parameters

| Parameter   | Type      | Default  | Description                                                                     |
| ----------- | --------- | -------- | ------------------------------------------------------------------------------- |
| `query`     | `string`  | required | Natural language description of what you're looking for                         |
| `path`      | `string`  | required | Absolute path to the codebase root directory                                    |
| `top_k`     | `integer` | `8`      | Number of results to return                                                     |
| `alpha`     | `float`   | `0.6`    | Weight given to vector score (0.0–1.0). `1.0` = pure vector, `0.0` = pure graph |
| `min_score` | `float`   | `0.0`    | Minimum blended score threshold; results below this are filtered out            |

## Example

```
hybrid_search("how does token validation work", "/path/to/myproject")
```

**Returns:**

```
[1] src/tokens.py:34-61 (score: 0.89)
def decode_jwt(token: str) -> dict:
    ...

[2] src/auth.py:45-72 (score: 0.84)
def authenticate_user(token: str) -> User:
    ...
```

## When to use

| Query type                                                     | Recommended tool                 |
| -------------------------------------------------------------- | -------------------------------- |
| Semantic / behaviour ("how does X work")                       | `search_code` or `hybrid_search` |
| Structural / navigation ("where is X defined", "what calls Y") | `search_graph`                   |
| Both semantic and structural context needed                    | `hybrid_search`                  |

## Notes

* Index the graph first with `index_graph` to unlock the graph component; without it, results are identical to `search_code`
* Average \~3,324 tokens per result set (\~87% reduction vs raw file reads)
* Average latency \~76ms
* Tune `alpha` toward `0.0` to weight structural connectivity more heavily; toward `1.0` for pure semantic relevance