> 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

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](/working-with-data/create-a-collection.md) and [Add & upsert records](/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](/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](/working-with-data/filter-results.md) and the [Filters (Eq)](/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](/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="/pages/IEihttmP8r8zxpFDyjgd">/pages/IEihttmP8r8zxpFDyjgd</a></td></tr><tr><td><strong>Filter results</strong></td><td>Scope searches and listings with Eq.</td><td><a href="/pages/f1kH8mnLEAKBG7sEkDOZ">/pages/f1kH8mnLEAKBG7sEkDOZ</a></td></tr><tr><td><strong>Records, IDs &#x26; payloads</strong></td><td>How Telys models external IDs and metadata.</td><td><a href="/pages/25a92W1qdHq0jNswnnSy">/pages/25a92W1qdHq0jNswnnSy</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/list-and-fetch-by-id.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.