> 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

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](/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](/tuning/running-a-pass.md).

{% hint style="warning" %}
`build_ivf` is local-only — it is not exposed over a [RemoteTelys](/reference/remote-api.md) connection. Build the index before serving the collection, or apply a saved tuning plan.
{% 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="/pages/WGHEJNj5Rltcfakhls3R">/pages/WGHEJNj5Rltcfakhls3R</a></td></tr><tr><td><strong>Why tune</strong></td><td>Let Telys choose recall and the crossover for you.</td><td><a href="/pages/dUb8SpYWDKmPq4apsKnQ">/pages/dUb8SpYWDKmPq4apsKnQ</a></td></tr><tr><td><strong>Search internals (IVF)</strong></td><td>How exact and IVF search actually work.</td><td><a href="/pages/34ekyTEaG3dG24136d0C">/pages/34ekyTEaG3dG24136d0C</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/working-with-data/build-ivf-index.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.