Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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.

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.

Before you start

These calls run against a collection you have already created and saved (see Create a collection and Add & upsert records). They use the signed native runtime; if it is not installed, run telys login then telys runtime verify — see Verify your install.

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.

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.

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.

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.

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

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.

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:

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:

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

Over a RemoteTelys connection, RemoteCollection exposes ids() but not len() or the in operator — use ids() (optionally with a where filter) to count and test membership remotely.

Next steps

Last updated

Was this helpful?