Metadata & filtering
Attach metadata to records, declare filter_columns, and narrow results with Eq — the single equality filter Telys supports across search and ids.
Every record can carry a metadata dictionary — a small payload of structured facts about the text. Return it with results, or filter on it so a search considers only matching records. Filtering is deliberately small: the only filter is Eq(column, value), an exact equality on one declared column. This page shows how to attach metadata, declare filterable keys, filter searches and ids(), and model your data around single-equality.
Attach metadata on write
Metadata is a list of dicts aligned position-by-position with your ids. Pass it to any ingest call:
from telys import Telys
from telys.embedding import AlgentaMultigramEmbedder
db = Telys("./memory")
emb = AlgentaMultigramEmbedder()
col = db.create_collection(
"docs",
dim=emb.profile.dimension,
partition_by="scope",
embedder=emb,
filter_columns=("lang", "kind"), # only these keys become filterable
)
col.add_texts(
texts=["def add(a, b): return a + b", "SELECT * FROM users"],
ids=["py-1", "sql-1"],
metadata=[
{"lang": "python", "kind": "code"},
{"lang": "sql", "kind": "code"},
],
)
col.save()Only the keys you declare in filter_columns are stored as retrievable columns. Whether a key can be filtered — and whether it returns from with_metadata=True — depends on that declaration.
Declare filter_columns at creation
filter_columns is a tuple passed to create_collection naming the metadata keys Telys stores as indexed, retrievable columns. Undeclared keys are not stored — they cannot be filtered and do not return from with_metadata=True. Declare a field to read it back or filter on it (list the partition key too if you want it in the with_metadata payload).
Filter with Eq — the only filter
Eq(column, value) is the sole filter class in Telys. Pass it as where= on a search, or use the equivalent single-key dict:
There are no And / Or / Not operators, no inequality (Ne), no ranges (Gt / Lt), and no In. A filter is exactly one column equal to exactly one value. That is the entire filter surface — see Filters (Eq).
Return payloads with with_metadata
By default, queries return only ids and scores. Set with_metadata=True to also get each hit's stored metadata dict, aligned to ids:
Scope ids() with a filter
ids() lists the live external ids and accepts the same filter, so you can enumerate one facet without running a search:
Modeling around single-equality
One equality per query sounds restrictive, but two features cover most needs:
Use
partition_byfor your primary axis. The partition key (tenant, user, project) is a physical split, not a filter — queries are naturally scoped to it. Compose a multi-part key withscope_key(...); a list/tuple passed topartition_byuses only its first element. See Partitions & scope keys.Use one
Eqfor a secondary facet. With the primary axis handled by partitioning, a single equality (e.g.lang == "python") usually covers the remaining cut.
For two combined facets, precompute a composite metadata value at write time — store {"lang_kind": "python:code"} and filter Eq("lang_kind", "python:code") — rather than reaching for a boolean combinator that does not exist.
Eq(column, value)
And / Or / Not
where={column: value} (single key)
Ne, Gt, Lt, In, ranges
with_metadata=True payloads
multi-key dict filters
ids(where=...)
filtering on undeclared columns
Next steps
Next: read Records, IDs & payloads to see how metadata rides alongside vectors.
Last updated
Was this helpful?