> 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/filter-results.md).

# Filter results

Constrain Telys searches and id listings to a partition or filter column using Eq or a single-key dict — the only filter Telys supports.

Telys filters by exact equality on a single column. Express it with `Eq("column", "value")` or an equivalent single-key dict `{"column": "value"}`. The same `where` argument works on `search`, `search_text`, and `ids`.

{% hint style="warning" %}
`Eq` is the **only** filter — no `And`, `Or`, `Not`, `Ne`, `Gt`, `Lt`, `In`, or range operators exist anywhere in Telys. To combine constraints, fold them into one column with `scope_key(...)` and filter on that — see [Combine constraints](#combine-constraints-without-and-or) below.
{% endhint %}

## What you can filter on

A column is filterable only if it is either:

* the collection's **partition key** (`partition_by`), or
* listed in **`filter_columns`** at [creation time](https://docs.telys.ai/working-with-data/create-a-collection.md).

Filtering any other column raises an error. Declare the columns you will query up front:

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

telys = Telys("telys-store")
embedder = AlgentaMultigramEmbedder()

docs = telys.create_collection(
    "docs",
    dim=embedder.profile.dimension,
    partition_by="tenant_id",           # always filterable
    embedder=embedder,
    filter_columns=("lang", "topic"),   # also filterable
)
docs.add_texts(
    ["release notes for v2", "notas de la versión v2"],
    ids=["en-1", "es-1"],
    metadata=[
        {"tenant_id": "acme", "lang": "en", "topic": "release"},
        {"tenant_id": "acme", "lang": "es", "topic": "release"},
    ],
)
docs.save()
```

## Filter a search

Pass `where` to `search_text` (or `search`). The `Eq` form and the dict form are equivalent:

```python
from telys import Eq

# Eq form
hits = docs.search_text("release notes", where=Eq("lang", "en"))

# single-key dict form
hits = docs.search_text("release notes", where={"lang": "en"})
```

Only records with `lang == "en"` match, so `es-1` never appears.

## Filter an id listing

`ids(where=...)` returns the live external ids, optionally scoped by the same filter — the fastest way to enumerate one partition without running a search:

```python
>>> docs.ids()
['en-1', 'es-1']
>>> docs.ids(where=Eq("tenant_id", "acme"))
['en-1', 'es-1']
>>> docs.ids(where={"lang": "es"})
['es-1']
```

## Combine constraints without And/Or

With no boolean composition, encode a multi-attribute scope as a single string key with `scope_key(...)`, store it in one column, partition or filter on that column, and match it with one `Eq`:

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

telys = Telys("telys-store")
embedder = AlgentaMultigramEmbedder()

chat = telys.create_collection(
    "chat",
    dim=embedder.profile.dimension,
    partition_by="scope",
    embedder=embedder,
)

key = scope_key("acme", "user:42")          # -> "acme\x1fuser:42"
chat.add_texts(["remember my timezone is UTC"], ids=["m-1"], metadata=[{"scope": key}])

hits = chat.search_text("timezone", where=Eq("scope", scope_key("acme", "user:42")))
```

One `Eq` on the composed key now does the work of an `AND` across tenant and user.

## Expected result

A filtered query returns only matching records; `ids(where=...)` returns the matching subset of ids:

```python
>>> docs.search_text("release notes", where=Eq("lang", "en"))["ids"]
['en-1']
>>> docs.ids(where={"lang": "es"})
['es-1']
```

## Next steps

* [List & fetch by ID](https://docs.telys.ai/working-with-data/list-and-fetch-by-id.md) — enumerate ids and pull records back out.
* [Partitions & scope keys](https://docs.telys.ai/understand-telys/partitions-scope-key.md) — design keys that filter well.
* [Filters (Eq)](https://docs.telys.ai/reference/filters.md) — the exact `Eq` API and its guarantees.
