> 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/inspect-stats.md).

# Inspect stats

Read row counts, index state, and partitions from a collection's stats, alongside its name, key column, and external IDs.

`stats()` returns one dictionary describing a collection: the runtime statistics — row counts, index state, partitions — plus the collection's `name`, its partition-key column `key_name`, and its `external_ids`. Use it to read the size and shape of a collection without reading any records.

{% hint style="info" %}
`stats()` reports live state only; it does not read payloads. It works whether the collection uses exact or [IVF](https://docs.telys.ai/working-with-data/build-ivf-index.md) search.
{% endhint %}

## Read the stats

```python
from telys import Telys

telys = Telys("./telys-data")
col = telys.open_collection("notes")   # no embedder needed to read stats

s = col.stats()

print("name       :", s["name"])
print("key column :", s["key_name"])
print("external   :", s["external_ids"])
print("full stats :", s)
```

## What the dictionary contains

| Key            | Always present   | What it tells you                                                               |
| -------------- | ---------------- | ------------------------------------------------------------------------------- |
| `name`         | yes              | The collection name.                                                            |
| `key_name`     | yes              | The physical partition-key column (from `partition_by`).                        |
| `external_ids` | yes              | The live external IDs — mirrors `len(col)`.                                     |
| runtime stats  | runtime-provided | Row counts, index state (exact / IVF), partition breakdown, and probe settings. |

`key_name` is the **single** physical partition key. A list or tuple passed to `partition_by` uses only its first element — Telys builds no composite keys, so compose one string with `scope_key(...)` if you need several parts. See [Partitions & scope keys](https://docs.telys.ai/understand-telys/partitions-scope-key.md).

{% hint style="warning" %}
The runtime-statistics keys come from the runtime and may vary by version. Read `name`, `key_name`, and `external_ids` by name; treat the rest as informational and do not hard-code assumptions about it.
{% endhint %}

## Expected result

For a saved collection of 1,240 rows partitioned by `scope`, still on exact search:

```
name       : notes
key column : scope
external   : 1240
full stats : {'name': 'notes', 'key_name': 'scope', 'external_ids': 1240, 'rows': 1240, 'index': 'exact', 'partitions': 12}
```

`external_ids` always agrees with `len(col)`. If `index` reports `exact` on a large collection, that is your cue to [build an IVF index](https://docs.telys.ai/working-with-data/build-ivf-index.md) or run a tuning pass.

{% hint style="info" %}
`stats()` is also available over a [RemoteTelys](https://docs.telys.ai/reference/remote-api.md) connection — `RemoteCollection` includes it, so you can inspect a served collection the same way.
{% 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>Turn stats and a tuning plan into decisions.</td><td><a href="https://docs.telys.ai/tuning/interpreting-results.md">Interpret results</a></td></tr><tr><td><strong>Build the IVF index</strong></td><td>Act on an exact index that has grown large.</td><td><a href="https://docs.telys.ai/working-with-data/build-ivf-index.md">Build IVF index</a></td></tr><tr><td><strong>Tuning &#x26; tradeoffs</strong></td><td>How recall, speed, and memory trade off.</td><td><a href="https://docs.telys.ai/understand-telys/tuning-tradeoffs.md">Tuning &amp; tradeoffs</a></td></tr></tbody></table>
