> For the complete documentation index, see [llms.txt](https://docs.telys.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.telys.ai/tuning/why-tune.md).

# Why tune

Why and when to tune a Telys collection — trading recall, latency, and memory as it grows past a few tens of thousands of rows.

Tune a collection when a partition grows too large to score every vector on every query. A fresh collection searches **exactly**: every live vector in the queried partition is scored, so recall is 100% and no index is needed. Tuning trades a small, measured amount of recall for much lower query latency once a partition is big.

A tuning pass leaves your data, embeddings, and result meaning unchanged. It changes only *how* a search finds them.

## The three-way tradeoff

An approximate index balances three quantities. You cannot maximize all three; tuning picks a point on the curve.

| Lever       | What it means                                                           | Push it up and…                               |
| ----------- | ----------------------------------------------------------------------- | --------------------------------------------- |
| **Recall**  | Fraction of the true top-k that an approximate search actually returns. | Latency and memory rise.                      |
| **Latency** | Wall-clock time per query (reported as p50 / p95).                      | Recall or memory must give.                   |
| **Memory**  | Resident footprint of the index structures.                             | You can afford more probes at a given recall. |

Exact search gives perfect recall, but latency grows linearly with live rows in the partition. Tuning moves toward lower latency at a recall target you choose.

## What a tuning pass actually sets

A pass produces a [`TuningPlan`](https://docs.telys.ai/tuning/tuner-and-plan.md). Applying it configures three things:

{% stepper %}
{% step %}

#### A target recall

`default_target_recall` is the recall the engine aims for on any search that does not pass its own `target_recall=`. It picks nprobe (how many IVF cells a query scans) to hit that target.
{% endstep %}

{% step %}

#### An exact-search crossover

`exact_crossover_rows` is the row count below which a partition keeps searching **exactly**. Only partitions above it use the approximate IVF path; smaller ones stay brute-force at perfect recall. This is why tiny collections never need tuning.
{% endstep %}

{% step %}

#### Per-partition IVF parameters

The plan carries the IVF layout (for example cell count and nprobe) that the engine builds and uses for large partitions.
{% endstep %}
{% endstepper %}

For the IVF index itself, see [Search internals (IVF)](https://docs.telys.ai/understand-telys/search-internals-ivf.md).

## When you actually need it

{% hint style="info" %}
Consider tuning once a single **partition** holds more than roughly 20,000 live rows — the threshold the IVF builder uses (`build_ivf(min_rows=20000)`). Below that, exact search is fast and gives perfect recall.
{% endhint %}

Reach for a tuning pass when:

* A partition has grown past a few tens of thousands of rows and latency has crept up.
* p95 latency matters (an interactive agent, a user-facing search box) and you can accept, say, 98% recall instead of 100%.
* You want the engine to hold a **recall target** automatically as the partition grows, instead of re-picking nprobe by hand.

Skip it when the collection is small, when you are still iterating on embeddings, or when you already pass a per-query `target_recall`.

Partitioning keeps individual indexes small — a well-chosen partition key (see [Partitions & scope keys](https://docs.telys.ai/understand-telys/partitions-scope-key.md)) often defers tuning entirely. A `partition_by` list uses only its first element, so compose a compound scope with `scope_key(...)`.

## What tuning is not

* **Not** re-embedding. Vector spaces and dimensions are unchanged.
* **Not** a change to which documents are correct — only to how completely the approximate search recovers them.
* **Not** required for correctness. Skip it and you keep exact search.

{% hint style="warning" %}
Tuning runs inside the signed native runtime. The built-in `HeuristicTuner` and the optional `AlgentaTuner` resolve lazily from the runtime (or the `telys-algenta` adapter); on a runtime-free install, importing them raises `ImportError`. Install and verify first: `telys runtime install`, then `telys runtime verify`.
{% endhint %}

## Next steps

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Tuner &#x26; TuningPlan</strong></td><td>The objects a pass produces and consumes.</td><td><a href="https://docs.telys.ai/tuning/tuner-and-plan.md">Tuner &amp; plans</a></td></tr><tr><td><strong>Run a tuning pass</strong></td><td>Call <code>col.tune()</code> and read back a plan.</td><td><a href="https://docs.telys.ai/tuning/running-a-pass.md">Run a pass</a></td></tr><tr><td><strong>Tuning &#x26; tradeoffs</strong></td><td>The concept in the wider engine model.</td><td><a href="https://docs.telys.ai/understand-telys/tuning-tradeoffs.md">Tuning &amp; tradeoffs</a></td></tr></tbody></table>
