> 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/working-with-data/build-ivf-index.md).

# Build IVF index

Switch a large collection from exact to approximate IVF search with build\_ivf, and confirm the change in the stats output.

Small collections search exactly: Telys scans every vector in the target partition and returns the true nearest neighbours. Once a partition grows to tens of thousands of rows, an **IVF** (inverted-file) index pays off — it groups vectors into lists and probes only the nearest few, trading a sliver of recall for a large speedup. `build_ivf` performs that switch.

{% hint style="info" %}
IVF is an optimisation for **large** collections. Below the crossover, exact search is both faster and perfectly accurate, so there is nothing to build.
{% endhint %}

## Build the index

```python
from telys import Telys

telys = Telys("./telys-data")
col = telys.open_collection("events")

col.build_ivf(min_rows=20000, target_recall=0.98)
col.save()
```

| Parameter       | Default | Meaning                                                                     |
| --------------- | ------- | --------------------------------------------------------------------------- |
| `min_rows`      | `20000` | Row threshold to build at. A partition below this stays on exact search.    |
| `target_recall` | `0.98`  | The recall the index is built to hit; the probe count is chosen to meet it. |

`min_rows` guards against indexing a partition too small to benefit — raise it if exact search is still fast enough at your size, or lower it if you have measured that IVF wins earlier for your data. Always `save()` afterward so the index and its settings persist.

## Confirm the switch with `stats()`

`stats()` reports the index state, so read it before and after to confirm the change:

```python
s = col.stats()
print(s["name"], "->", s)
```

## Manual build vs. tuning

`build_ivf` is the manual lever. For a data-driven choice of `target_recall` and the exact-crossover point, run the [Tuner](https://docs.telys.ai/tuning/why-tune.md) instead: `apply_tuning` builds per-partition IVF, sets the crossover, and picks the probe count from a measured workload. Use `build_ivf` when you already know you want IVF; use tuning when you want Telys to decide. See [Run a tuning pass](https://docs.telys.ai/tuning/running-a-pass.md).

{% hint style="info" %}
`build_ivf` is exposed over a [RemoteTelys](https://docs.telys.ai/reference/remote-api.md) connection too, so you can build the index against a served collection. Tuning (`tune` / `apply_tuning`) is local-only — apply a saved tuning plan on the host, or build the index explicitly from the client.
{% endhint %}

## Expected result

Before the build, the collection reports exact search; after, it reports an IVF index with a probe count. Exact field names come from the runtime, so the shape below is illustrative:

```
# before
{'name': 'events', 'key_name': 'scope', 'external_ids': 84000, 'rows': 84000, 'index': 'exact'}

# after
{'name': 'events', 'key_name': 'scope', 'external_ids': 84000, 'rows': 84000, 'index': 'ivf', 'nprobe': 16, 'target_recall': 0.98}
```

The live row count (`external_ids`) is unchanged — `build_ivf` only changes how the collection is searched, not what it contains.

## 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 row counts, index state, and partitions.</td><td><a href="https://docs.telys.ai/working-with-data/inspect-stats.md">Inspect stats</a></td></tr><tr><td><strong>Why tune</strong></td><td>Let Telys choose recall and the crossover for you.</td><td><a href="https://docs.telys.ai/tuning/why-tune.md">Why tune</a></td></tr><tr><td><strong>Search internals (IVF)</strong></td><td>How exact and IVF search actually work.</td><td><a href="https://docs.telys.ai/understand-telys/search-internals-ivf.md">Search internals</a></td></tr></tbody></table>
