> 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/understand-telys/metadata-and-filtering.md).

# 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:

```python
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).

```python
col = db.create_collection(
    "docs",
    dim=emb.profile.dimension,
    partition_by="scope",
    embedder=emb,
    filter_columns=("lang", "kind"),     # declare up front
)
```

{% hint style="warning" %}
Declare filter columns **before** you add data. A `where=Eq(...)` should reference a declared column; filtering on an undeclared key has no index to use. Decide your filter axes when you design the collection.
{% endhint %}

## 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:

```python
from telys import Eq

res = col.search_text(
    "add two numbers",
    top_k=5,
    where=Eq("lang", "python"),          # only records with lang == "python"
    with_metadata=True,
)
print(res["ids"])
print(res["metadata"])

# The single-key dict form is equivalent:
res = col.search_text("add two numbers", where={"lang": "python"})
```

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)](https://docs.telys.ai/reference/filters.md).

## 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`:

```python
res = col.search_text("add two numbers", top_k=5, with_metadata=True)
for _id, meta in zip(res["ids"], res["metadata"]):
    print(_id, meta)
```

## 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:

```python
python_ids = col.ids(where=Eq("lang", "python"))
all_ids = col.ids()                      # every live id
```

## Modeling around single-equality

One equality per query sounds restrictive, but two features cover most needs:

* **Use `partition_by` for 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 with `scope_key(...)`; a list/tuple passed to `partition_by` uses only its first element. See [Partitions & scope keys](https://docs.telys.ai/understand-telys/partitions-scope-key.md).
* **Use one `Eq` for 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.

| Supported                            | Not supported                   |
| ------------------------------------ | ------------------------------- |
| `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 |

{% hint style="info" %}
Over MCP the filter is a single-key equality object; a multi-key `where` raises an error. The same single-key `where` applies across the 19 MCP tools — `telys_search`, `telys_search_lexical`, `telys_ids`, and `telys_count` all accept it. See [MCP overview](https://docs.telys.ai/mcp/overview.md).
{% 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>Filter results</strong></td><td>A hands-on guide to filtering searches with Eq.</td><td><a href="https://docs.telys.ai/working-with-data/filter-results.md">Filter results</a></td></tr><tr><td><strong>Filters (Eq)</strong></td><td>The complete Eq reference and its exact semantics.</td><td><a href="https://docs.telys.ai/reference/filters.md">Filters (Eq)</a></td></tr><tr><td><strong>List &#x26; fetch by ID</strong></td><td>Enumerate ids, optionally scoped by an Eq filter.</td><td><a href="https://docs.telys.ai/working-with-data/list-and-fetch-by-id.md">List &amp; fetch by ID</a></td></tr></tbody></table>

Next: read [Records, IDs & payloads](https://docs.telys.ai/understand-telys/records-ids-payloads.md) to see how metadata rides alongside vectors.
