> 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/reference/filters.md).

# Filters (Eq)

Reference for Eq — the single equality filter Telys supports on search, search\_text, and ids, and how it maps to the single-key dict at the MCP boundary.

Telys has exactly one filter primitive: `Eq`. It matches rows where a metadata column equals a value. There are no boolean combinators, negation, or comparison operators anywhere in the API.

```python
from telys import Eq

Eq(column, value)
```

## Signature

| Constructor         | Parameters             | Description                               |
| ------------------- | ---------------------- | ----------------------------------------- |
| `Eq(column, value)` | `column: str`, `value` | Match rows whose `column` equals `value`. |

Declare a filter column at creation via `filter_columns=(...)`:

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

ame = Telys("./memory")
emb = AlgentaMultigramEmbedder()
col = ame.create_collection(
    "notes", dim=emb.profile.dimension, partition_by="scope",
    embedder=emb,
    filter_columns=("tenant_id", "kind"),
)
```

## Where you can pass it

`Eq` (or an equivalent single-key dict) is accepted by the `where=` parameter of three methods:

| Method                                               | Filter parameter |
| ---------------------------------------------------- | ---------------- |
| `Collection.search(vector, ..., where=None, ...)`    | `where`          |
| `Collection.search_text(text, ..., where=None, ...)` | `where`          |
| `Collection.ids(where=None)`                         | `where`          |

```python
from telys import Eq

# Eq instance
hits = col.search_text("q3 roadmap", where=Eq("tenant_id", "acme"))

# Equivalent single-key dict
hits = col.search_text("q3 roadmap", where={"tenant_id": "acme"})

# Restrict a listing to one tenant
live = col.ids(where=Eq("tenant_id", "acme"))
```

Both forms are equivalent. `where=None` (the default) filters nothing.

## The MCP boundary

Over MCP, `telys_search` accepts a `where` object that must be a **single-key equality**. A dict with more than one key raises an error.

{% code title="telys\_search arguments" %}

```json
{
  "collection": "notes",
  "query": "q3 roadmap",
  "where": { "tenant_id": "acme" }
}
```

{% endcode %}

## Not supported

None of these exist in the SDK, the CLI, or MCP.

| You might want                               | Status           |
| -------------------------------------------- | ---------------- |
| `And(...)`, `Or(...)`, `Not(...)`            | Not available.   |
| `Ne`, `Gt`, `Lt`, `Gte`, `Lte` (comparisons) | Not available.   |
| `In([...])`, ranges                          | Not available.   |
| Multi-key `where` dict at MCP                | Raises an error. |
| Time-travel / `as_of()` / validity windows   | Not available.   |

## Patterns for what Eq cannot express

Model your data so one equality answers the query.

{% hint style="info" %}
Fold several facets into one column with [`scope_key`](https://docs.telys.ai/reference/sdk-api-index.md#scope-key), then filter on that exact key. Example: store `scope_key("acme", "notes")` and query `Eq("scope", scope_key("acme", "notes"))`.
{% endhint %}

* Combine tenant and kind: precompute a composite value (`f"{tenant}:{kind}"`) at write time and `Eq` on it.
* Scope every query to a subject: put the subject in `partition_by`, then `Eq` on a second `filter_column` within it.

## See also

<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>Task walkthrough of scoping queries with Eq.</td><td><a href="https://docs.telys.ai/working-with-data/filter-results.md">Filter results</a></td></tr><tr><td><strong>Metadata &#x26; filtering</strong></td><td>How filter columns and metadata relate.</td><td><a href="https://docs.telys.ai/understand-telys/metadata-and-filtering.md">Metadata &amp; filtering</a></td></tr><tr><td><strong>Partitions &#x26; scope keys</strong></td><td>Compose one key from several fields.</td><td><a href="https://docs.telys.ai/understand-telys/partitions-scope-key.md">Partitions &amp; scopes</a></td></tr><tr><td><strong>SDK API index</strong></td><td>The full public surface.</td><td><a href="https://docs.telys.ai/reference/sdk-api-index.md">SDK API index</a></td></tr></tbody></table>
