> 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

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`](/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)](/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](/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="/pages/NznoaOZPDT34Q6o79zU5">/pages/NznoaOZPDT34Q6o79zU5</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="/pages/oRgOGxUrNbTlcSvpJeau">/pages/oRgOGxUrNbTlcSvpJeau</a></td></tr><tr><td><strong>Tuning &#x26; tradeoffs</strong></td><td>The concept in the wider engine model.</td><td><a href="/pages/tVrk8vG4vvlGOMGKSaut">/pages/tVrk8vG4vvlGOMGKSaut</a></td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.telys.ai/tuning/why-tune.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.