# VSEARCH and VSIM

This page explains how ToriiDB ranks keys by cosine similarity with `VSEARCH` and compares or reads stored vectors with `VSIM` and `VGET`.

## Semantic Search

```text
VSEARCH embedded database
VSEARCH embedded database MATCH article:* LIMIT 5
VSEARCH embedded database LIMIT 5 MATCH article:*
```

| Parameter | REPL / `store` | Daemon `vsearch` |
|---|---|---|
| text | required, non-blank | required, non-blank |
| pattern | optional `MATCH`; empty matches all | required |
| limit | `<= 0` → `10` | `<= 0` → `100` |

The query vector comes from the cache or a synchronous embedding call; a fresh query embedding is cached too. Then, under the read lock, each entry is skipped if it is internal, expired, has no vector, has a different vector length, fails `path.Match`, or has a zero norm. A min-heap keeps the top `k`, and keys are returned highest similarity first.

## Similarity and Retrieval

```text
VSIM article:1 article:2
VGET article:1
```

| Call | Result |
|---|---|
| `VSim(key1, key2)` | Cosine similarity; missing key, missing vector, or zero vector is `vector is missing` (REPL `(nil)`); different lengths is `vector is mismatch: a vs b` |
| `VGet(key)` | A copy of the stored vector, or `false`; REPL prints a JSON array or `(nil)` |

The daemon does not expose `VSIM` or `VGET`.

## Related Pages

- [Attaching Vectors](/vector-search)
- [Server-Side Filtering](/socket-daemon-filtering)
- [Scan and Vector](/cli-reference-scan)