> 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/apply-and-save.md).

# Apply & save

Apply a TuningPlan with col.apply\_tuning() to configure recall, crossover, and IVF, then persist the result with col.save().

Applying a plan and persisting it are two steps. `col.apply_tuning(plan)` writes the plan's settings onto the **live** collection; `col.save()` makes them **durable** on disk. A plan is only a description — there is no `TuningPlan.save`.

## Before you start

* You have a `TuningPlan` from [running a pass](https://docs.telys.ai/tuning/running-a-pass.md) (`plan = col.tune(dry_run=True)`).
* The signed runtime is installed and verified.

## What each call does

| Call                     | Signature                    | Effect                                                                                                                                                                                               |
| ------------------------ | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `col.apply_tuning(plan)` | `apply_tuning(plan) -> dict` | Sets `default_target_recall` and the exact-search crossover, builds or reuses the per-partition IVF, sets nprobe, and **returns the collection's `stats()`**.                                        |
| `col.save()`             | `save() -> str`              | Commits the collection to disk and returns its directory. Persists `default_target_recall` and `applied_tuner` (alongside name, dim, dtype, key name, filter columns, id map, and embedder profile). |

{% hint style="info" %}
`apply_tuning` changes the in-memory collection immediately, but nothing is durable until `save()` writes `collection.json`. Exit without saving and the applied tuning is lost.
{% endhint %}

## Apply, then save

{% stepper %}
{% step %}

#### Apply the plan

```python
from telys import Telys

db = Telys("./store")
col = db.open_collection("notes")

plan = col.tune(dry_run=True)     # compute a plan, apply nothing yet
stats = col.apply_tuning(plan)    # now configure the live collection
```

{% endstep %}

{% step %}

#### Read the returned stats

`apply_tuning` returns the same dictionary as `col.stats()`, so you can confirm the new configuration.

```python
print(stats["name"])              # notes
print(stats["external_ids"])      # live id count
print(stats)                      # runtime stats reflecting the applied IVF / recall
```

{% endstep %}

{% step %}

#### Persist it

```python
path = col.save()                 # commit; returns the collection directory
print(path)                       # ./store/notes
```

{% endstep %}

{% step %}

#### Confirm it survived a reopen

```python
db2 = Telys("./store")
reopened = db2.open_collection("notes")
print(reopened.stats())           # default_target_recall / applied_tuner are back
```

{% endstep %}
{% endstepper %}

## Expected result

After `apply_tuning`, the collection searches with the plan's recall target and IVF layout: large partitions use the approximate path, partitions below the crossover stay exact. After `save()`, reopening restores `default_target_recall` and `applied_tuner` from `collection.json` — no re-tuning needed.

```
notes
48213
./store/notes
```

From now on, every `col.search(...)` that does not pass its own `target_recall=` aims for the applied `default_target_recall`. Override per query, for example `col.search(vector, target_recall=0.995)`.

{% hint style="warning" %}
On a large collection, `apply_tuning` builds per-partition IVF indexes and can take a moment. This happens once at apply time, not on every query.
{% 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>Interpret tuning results</strong></td><td>Read the plan's predictions and verify them.</td><td><a href="https://docs.telys.ai/tuning/interpreting-results.md">Interpret results</a></td></tr><tr><td><strong>Inspect collection stats</strong></td><td>Confirm the applied configuration.</td><td><a href="https://docs.telys.ai/working-with-data/inspect-stats.md">Inspect stats</a></td></tr><tr><td><strong>Snapshots &#x26; persistence</strong></td><td>How <code>save()</code> commits to disk.</td><td><a href="https://docs.telys.ai/working-with-data/snapshots-and-persistence.md">Save &amp; snapshots</a></td></tr></tbody></table>
