> 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/interpreting-results.md).

# Interpret results

Read a tuning result in two parts. First, *what did the tuner predict, and why?* — that lives in the [`TuningPlan`](/tuning/tuner-and-plan.md). Second, *did the applied configuration deliver?* — confirm that against real searches. Never trust the prediction alone.

## Read what the tuner predicted

### `plan.expected`

The `expected` dict is the tuner's forecast for the plan it chose. Typical keys:

| Key             | Meaning                                                 | How to read it                                                                                |
| --------------- | ------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| `p50`           | Predicted median query latency (ms).                    | Your typical case.                                                                            |
| `p95`           | Predicted 95th-percentile latency (ms).                 | Your tail — what interactive users feel.                                                      |
| `recall_at_k`   | Predicted recall at the search `top_k`.                 | Should be at or above `plan.target_recall`.                                                   |
| `fallback_rate` | Share of queries expected to fall back to exact search. | High values mean many partitions sit below `exact_crossover_rows` and are still brute-forced. |

```python
plan = col.tune(dry_run=True)
print(plan.target_recall)          # the goal, e.g. 0.98
print(plan.expected["recall_at_k"]) # the prediction, e.g. 0.981
print(plan.expected["p95"])         # e.g. 4.3 (ms)
print(plan.expected["fallback_rate"])
```

### `plan.decision_trace`

`decision_trace` is an ordered list of readable steps showing *how* the tuner reached the plan — the statistics it read, the constraints it honored, and the tradeoff it settled on. Read it top to bottom when a plan surprises you.

```python
for step in plan.decision_trace:
    print(step)
```

`plan.constraints` records the bounds the tuner had to respect (latency, recall, memory). If `expected` looks worse than you hoped, the constraints usually explain why.

## Verify against reality

Predictions come from a model. Confirm them on your machine, with your data.

{% stepper %}
{% step %}

#### Check the applied configuration

After [applying and saving](/tuning/apply-and-save.md), `stats()` reflects the live IVF and recall settings.

```python
stats = col.stats()
print(stats["external_ids"])   # rows the config was sized for
print(stats)                   # runtime stats after apply
```

{% endstep %}

{% step %}

#### Explain a real search

Pass `explain=True` to see how a query was served — how many cells were probed and whether it used the approximate path or the exact fallback.

```python
res = col.search_text("reset my password", top_k=10, explain=True)
print(res["ids"])
print(res["explain"])          # per-query trace of how the search ran
```

{% endstep %}

{% step %}

#### Spot-check recall against exact

Compare a tuned result to an exact search by asking for full recall on that one query. Overlap in the returned ids is your measured recall.

```python
tuned = col.search_text("reset my password", top_k=10)
exact = col.search_text("reset my password", top_k=10, target_recall=1.0)
overlap = len(set(tuned["ids"]) & set(exact["ids"])) / len(exact["ids"])
print(overlap)                 # 1.0 means the tuned search missed nothing here
```

{% endstep %}
{% endstepper %}

## Make sense of the numbers

* **Recall below target.** Measured overlap under `target_recall` means the tuner gave up more recall than you want. Re-run with a higher recall objective or raise `target_recall`; expect latency to rise with it.
* **Latency higher than `expected`.** Predictions assume warm indexes and representative queries. First queries after `apply_tuning` run colder; measure the steady state.
* **`fallback_rate` near 1.0.** Most partitions sit below `exact_crossover_rows` and are already searched exactly, so tuning has little to do. This usually means the collection is not yet big enough to need it.
* **`p95` far above `p50`.** A heavy tail usually points at a few very large partitions. A finer partition key (see [Partitions & scope keys](/understand-telys/partitions-scope-key.md)) can flatten it.

{% hint style="info" %}
`RemoteCollection.search` supports `explain=True` but not `target_recall=`. Run the recall spot-check against a **local** collection, then deploy the saved settings behind a server.
{% 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>Inspect collection stats</strong></td><td>Read every field <code>stats()</code> returns.</td><td><a href="/pages/WGHEJNj5Rltcfakhls3R">/pages/WGHEJNj5Rltcfakhls3R</a></td></tr><tr><td><strong>Search internals (IVF)</strong></td><td>What nprobe and the crossover actually do.</td><td><a href="/pages/34ekyTEaG3dG24136d0C">/pages/34ekyTEaG3dG24136d0C</a></td></tr><tr><td><strong>Run a tuning pass</strong></td><td>Re-tune with different objectives.</td><td><a href="/pages/oRgOGxUrNbTlcSvpJeau">/pages/oRgOGxUrNbTlcSvpJeau</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/interpreting-results.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.