> 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

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](/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](/working-with-data/list-and-fetch-by-id.md) — enumerate ids and pull records back out.
* [Partitions & scope keys](/understand-telys/partitions-scope-key.md) — design keys that filter well.
* [Filters (Eq)](/reference/filters.md) — the exact `Eq` API and its guarantees.


---

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