> 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/list-and-fetch-by-id.md).

# List & fetch by ID

List the live external IDs in a Telys collection, count rows, test membership, and page through one partition with a scoped search.

Telys tracks every record by the external ID you assign. The read-only ID operations are `len(col)`, `ext in col`, and `col.ids(where=...)`. Combine `ids()` with a scoped search to walk the records in one partition.

{% hint style="info" %}
Telys has no `get(id)` method. Test that an ID is live with `ext in col`, enumerate IDs with `col.ids(...)`, and read a record's text or metadata with a scoped `search` / `search_text` and `with_metadata=True`.
{% endhint %}

## Before you start

These calls run against a collection you have already created and saved (see [Create a collection](https://docs.telys.ai/working-with-data/create-a-collection.md) and [Add & upsert records](https://docs.telys.ai/working-with-data/add-and-upsert.md)). They use the signed native runtime; if it is not installed, run `telys login` then `telys runtime verify` — see [Verify your install](https://docs.telys.ai/start-here/verify-install.md).

```python
from telys import Telys, Eq
from telys.embedding import AlgentaMultigramEmbedder

telys = Telys("./telys-data")

# open_collection auto-attaches an embedder from the provider registry; pass one
# explicitly here so search_text works without registering a provider first.
col = telys.open_collection("notes", embedder=AlgentaMultigramEmbedder())
```

## Count records — `len(col)`

`len(col)` returns the number of live external IDs — the same value `stats()` reports as `external_ids`.

```python
len(col)   # -> 1240
```

## Test membership — `ext in col`

`in` tests whether an external ID is currently live. It does not read the payload, so it is cheap.

```python
"note-42" in col          # -> True
"does-not-exist" in col   # -> False
```

## List external IDs — `col.ids()`

`ids(where=None)` returns the live external IDs as a list, in no guaranteed order. Without a filter you get every ID in the collection.

```python
col.ids()   # -> ['note-7', 'note-42', 'note-88', ...]
```

## Scope the listing with a filter

Pass `where=` to restrict the listing to one partition or filter value. The only filter class is `Eq(column, value)`; a single-key dict is shorthand for the same thing.

```python
col.ids(where=Eq("scope", "user:42"))     # IDs in one partition
col.ids(where={"scope": "user:42"})       # single-key dict — identical result
```

If you composed the partition key with `scope_key`, filter with the same composed string:

```python
from telys import scope_key

key = scope_key("acme", "user:42")        # "acme\x1fuser:42"
col.ids(where=Eq("scope", key))
```

{% hint style="warning" %}
`Eq` is the only filter Telys supports — no `And` / `Or` / `Not`, ranges, or `In`, and a dict filter must have exactly one key. See [Filter results](https://docs.telys.ai/working-with-data/filter-results.md) and the [Filters (Eq)](https://docs.telys.ai/reference/filters.md) reference.
{% endhint %}

## Fetch payloads (there is no `get(id)`)

To read the text or metadata behind an ID, run a scoped search with `with_metadata=True`. It returns external IDs plus the metadata for each hit.

```python
hits = col.search_text(
    "quarterly planning",
    top_k=5,
    where=Eq("scope", "user:42"),
    with_metadata=True,
)

for id_, meta in zip(hits["ids"], hits["metadata"]):
    print(id_, meta)
```

## Page through a partition

`ids()` returns the full partition list, so page through it client-side by slicing the Python list — there is no server-side cursor or offset:

```python
partition_ids = col.ids(where=Eq("scope", "user:42"))

for start in range(0, len(partition_ids), 100):
    page = partition_ids[start:start + 100]
    print(f"rows {start}-{start + len(page)}: {page[0]} ... {page[-1]}")
```

With no random-access fetch by ID, retrieve the content for a partition with a scoped search (above) rather than looping ID by ID.

## Expected result

Running the count, membership, and scoped-listing calls in order prints:

```
1240
True
['note-7', 'note-42', 'note-88']
```

`len(col)` and the length of `col.ids()` always agree, and a scoped `ids()` is a subset of the full listing.

{% hint style="info" %}
Over a [RemoteTelys](https://docs.telys.ai/reference/remote-api.md) connection, `RemoteCollection` exposes `ids()` but not `len()` or the `in` operator — use `ids()` (optionally with a `where` filter) to count and test membership remotely.
{% 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>Update records</strong></td><td>Replace the contents of rows that already exist.</td><td><a href="https://docs.telys.ai/working-with-data/update-records.md">Update records</a></td></tr><tr><td><strong>Filter results</strong></td><td>Scope searches and listings with Eq.</td><td><a href="https://docs.telys.ai/working-with-data/filter-results.md">Filter results</a></td></tr><tr><td><strong>Records, IDs &#x26; payloads</strong></td><td>How Telys models external IDs and metadata.</td><td><a href="https://docs.telys.ai/understand-telys/records-ids-payloads.md">Records &amp; IDs</a></td></tr></tbody></table>
